Merge branch 'main' into docs

* main:
  🐋 Dockerfile migrations (#77)
  💽 `postgresql://` in all environments (#73)

.env.development

@@ -1,2 +1,2 @@
-DB_HOST=""
-DB_URL="sqlite:///chowda.development.sqlite"
+
+DB_URL="postgresql://postgres:postgres@localhost:5432/chowda-development"

.env.test

@@ -1 +1 @@
-DB_URL="sqlite:///chowda.test.sqlite"
+DB_URL='postgresql://postgres:postgres@localhost/chowda-test'

.github/workflows/CI.yml

@@ -2,15 +2,18 @@ name: 🧪 Integration Tests
 
 on: [push, pull_request, workflow_dispatch]
 
+env:
+  DB_URL: postgresql://postgres:postgres@postgres:5432/chowda-test
+
 jobs:
   tests:
     name: ⚗️ Application Tests
-    uses: WGBH-MLA/.github/.github/workflows/pytest-with-postgres.yml@pytest-with-postgres
+    uses: WGBH-MLA/.github/.github/workflows/pytest-with-postgres.yml@main
     secrets: inherit
     with:
       pdm_args: -G test,ci
       pytest_args: -n auto --nbmake -ra -s
-      pg_db: chowda
+      pg_db: chowda-test
 
   lint:
     name: 👕 Lint

Dockerfile

@@ -2,13 +2,19 @@
 # 'base' build stage, common to all build stages
 ###########################
 FROM python as base
+
 # Set working dir to /app, where all Chowda code lives.
 WORKDIR /app
 RUN pip install -U pip
+
 # Copy app code to container
 COPY pyproject.toml pdm.lock README.md ./
 COPY chowda chowda
 
+# Copy migration files
+COPY alembic.ini ./
+COPY migrations migrations
+
 
 ###########################
 # 'dev' build stage

chowda/db.py

@@ -1,23 +1,10 @@
 from sqlalchemy import create_engine
 from sqlmodel import SQLModel
 
-# NOTE: models must be imported prior to calling SQL.metadata.create_all(engine)
-# Using this method to create the database schems is only temporary until we
-# replace it with a proper migration tool, e.g. Alembic. Disable Ruff linting
-# that flags unused imports: this import *is* used in the sense that once it's
-# imported, it lets SQLModel know about the schema behind the scenes, so that
-# the SQLModel.metadata.create_all(engine) command will actually create the db
-# tables.
-from chowda import models  # noqa: F401
 from chowda.config import DB_URL, DEBUG
 
-print('\n\nabout to create all!\n\n')
-
 engine = create_engine(DB_URL, echo=DEBUG)
 
-# Create database from SQLModel schema
-SQLModel.metadata.create_all(engine)
-
 
 # TODO: implement async engine
 def create_async_engine():
@@ -31,4 +18,11 @@ def init_db():
 
     from chowda import models  # noqa: F401
 
+    # NOTE: models must be imported prior to calling SQL.metadata.create_all(engine)
+    # Using this method to create the database schems is only temporary until we
+    # replace it with a proper migration tool, e.g. Alembic. Disable Ruff linting
+    # that flags unused imports: this import *is* used in the sense that once it's
+    # imported, it lets SQLModel know about the schema behind the scenes, so that
+    # the SQLModel.metadata.create_all(engine) command will actually create the db
+    # tables.
     SQLModel.metadata.create_all(engine)

docs/install.md

@@ -1,5 +1,6 @@
 # Install
 
+
 ### Clone the repository::
 
 ```shell
@@ -40,12 +41,44 @@ Install the package
 pip install .
 ```
 
+### Create PostgreSQL database and start the database server
+Chowda needs to have a PostgreSQL server running and database named `chowda-development` (tests use a database `chowda-test`).
+
+There are many ways to do this, but an easy way is to use docker. After starting Docker on your local machine, the following command will start a container using the `postgres` image in Dockerhub.
+
+```shell
+docker run --rm --name pg -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=chowda-development postgres
+```
+#### Command explained
+* `docker run` runs a docker container
+* `--rm` option will remove the docker container once it exits.
+* `--name pg` will name the running container `pg` so it can be identified when listing running containers.
+* `-p 5432:5432` forwards port 5432 on your local machine to port 5432 (default postgres port) on the running container.
+* `-e POSTGRES_USER=postgres` sets ENV var on container for the postgres username
+* `-e POSTGRES_PASSWORD=postgres` sets ENV var on container for postgres password
+
+    !!! note
+
+        Not a secure password, but that's ok for test and development environments.
+
+* `-e POSTGRES_DB=chowda-development` sets ENV var on container for the name of postgres database to use
+
+    !!! note
+
+        The `postgres` image will create the database when starting the container.
+
+* `postgres` is the name of the Docker image to use when starting the container.
+
+!!! note
+
+    the environment variables values in the command must match the values that are part of the `DB_URL` environment variable specified in `.env.development`.
+
+
 ## Run database migrations with Alembic
 ```shell
 alembic upgrade head
 ```
 
-
 ## Run the application
 
 ```shell
@@ -64,6 +97,23 @@ python tests/seeds.py
 
 **Optional:** Customize the number of records created by changing the `num_*` variables in the `seed` function.
 
+
+## Running tests
+Chowda uses `pytest` for testing.
+
+### Creating the test database and running a postgres server
+This is done the same way as in the development environment (see above), only the database name is changed.
+```shell
+docker run --rm --name pg -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=chowda-development postgres
+```
+
+
+### Running the tests from terminal
+```shell
+pytest --vcr-record=none --nbmake
+```
+
+
 ## Deactivate the virtual environment
 
 Run the `deactivate` command to return to your normal shell environment.