Use testcontainers for DB tests

.github/workflows/tests.yaml

@@ -42,18 +42,6 @@ jobs:
                 # version.
                 python-version: ["3.13"]
                 postgres-version: [17]
-        services:
-            postgres:
-                image: postgres:${{ matrix.postgres-version }}
-                env:
-                    POSTGRES_PASSWORD: postgres
-                options: >-
-                    --health-cmd pg_isready
-                    --health-interval 10s
-                    --health-timeout 5s
-                    --health-retries 5
-                ports:
-                    - 5432:5432
         steps:
             - uses: actions/checkout@v3
             - name: Set up Python ${{ matrix.python-version }}
@@ -66,19 +54,10 @@ jobs:
                   pip install -r requirements/requirements.txt
                   pip install -r requirements/test-requirements.txt
                   pip install -r requirements/extras/postgres.txt
-            - name: Setup postgres
-              run: |
-                  export PGPASSWORD=postgres
-                  psql -h localhost -c 'CREATE DATABASE piccolo;' -U postgres
-                  psql -h localhost -c "CREATE USER piccolo PASSWORD 'piccolo';" -U postgres
-                  psql -h localhost -c "GRANT ALL PRIVILEGES ON DATABASE piccolo TO piccolo;" -U postgres
-                  psql -h localhost -c "CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\";" -d piccolo -U postgres
             - name: Run integration tests
               run: ./scripts/test-integration.sh
               env:
-                  PG_HOST: localhost
-                  PG_DATABASE: piccolo
-                  PG_PASSWORD: postgres
+                  TC_POSTGRES_VERSION: ${{ matrix.postgres-version }}
 
     postgres:
         runs-on: ubuntu-latest
@@ -88,24 +67,6 @@ jobs:
                 python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
                 postgres-version: [14, 15, 16, 17, 18]
 
-        # Service containers to run with `container-job`
-        services:
-            # Label used to access the service container
-            postgres:
-                # Docker Hub image
-                image: postgres:${{ matrix.postgres-version }}
-                # Provide the password for postgres
-                env:
-                    POSTGRES_PASSWORD: postgres
-                # Set health checks to wait until postgres has started
-                options: >-
-                    --health-cmd pg_isready
-                    --health-interval 10s
-                    --health-timeout 5s
-                    --health-retries 5
-                ports:
-                    - 5432:5432
-
         steps:
             - uses: actions/checkout@v3
             - name: Set up Python ${{ matrix.python-version }}
@@ -118,20 +79,10 @@ jobs:
                   pip install -r requirements/requirements.txt
                   pip install -r requirements/test-requirements.txt
                   pip install -r requirements/extras/postgres.txt
-            - name: Setup postgres
-              run: |
-                  export PGPASSWORD=postgres
-                  psql -h localhost -c 'CREATE DATABASE piccolo;' -U postgres
-                  psql -h localhost -c "CREATE USER piccolo PASSWORD 'piccolo';" -U postgres
-                  psql -h localhost -c "GRANT ALL PRIVILEGES ON DATABASE piccolo TO piccolo;" -U postgres
-                  psql -h localhost -c "CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\";" -d piccolo -U postgres
-
             - name: Test with pytest, Postgres
               run: ./scripts/test-postgres.sh
               env:
-                  PG_HOST: localhost
-                  PG_DATABASE: piccolo
-                  PG_PASSWORD: postgres
+                  TC_POSTGRES_VERSION: ${{ matrix.postgres-version }}
             - name: Upload coverage
               uses: codecov/codecov-action@v1
               if: matrix.python-version == '3.13'
@@ -155,17 +106,10 @@ jobs:
                   pip install -r requirements/requirements.txt
                   pip install -r requirements/test-requirements.txt
                   pip install -r requirements/extras/postgres.txt
-            - name: Setup CockroachDB
-              run: |
-                  wget -qO- https://binaries.cockroachdb.com/cockroach-${{ matrix.cockroachdb-version }}.linux-amd64.tgz | tar xz
-                  ./cockroach-${{ matrix.cockroachdb-version }}.linux-amd64/cockroach start-single-node --insecure --background
-                  ./cockroach-${{ matrix.cockroachdb-version }}.linux-amd64/cockroach sql --insecure -e 'create database piccolo;'
-
             - name: Test with pytest, CockroachDB
               run: ./scripts/test-cockroach.sh
               env:
-                  PG_HOST: localhost
-                  PG_DATABASE: piccolo
+                  TC_COCKROACH_VERSION: ${{ matrix.cockroachdb-version }}
             - name: Upload coverage
               uses: codecov/codecov-action@v1
               if: matrix.python-version == '3.13'

docs/src/piccolo/contributing/index.rst

@@ -8,25 +8,6 @@ instructions.
 
 -------------------------------------------------------------------------------
 
-Running Cockroach
------------------
-
-To get a local Cockroach instance running, you can use:
-
-.. code-block:: console
-
-    cockroach start-single-node --insecure --store=type=mem,size=2GiB
-
-Make sure the test database exists:
-
-.. code-block:: console
-
-    cockroach sql --insecure
-    >>> create database piccolo;
-    >>> use piccolo;
-
--------------------------------------------------------------------------------
-
 Get the tests running
 ---------------------
 
@@ -37,7 +18,7 @@ Get the tests running
 * Install development dependencies: ``pip install -r requirements/dev-requirements.txt``
 * Install test dependencies: ``pip install -r requirements/test-requirements.txt``
 * Install database drivers: ``pip install -r requirements/extras/postgres.txt -r requirements/extras/sqlite.txt``
-* Setup database engines, and make sure a database called ``piccolo`` exists (see ``tests/postgres_conf.py``, ``tests/sqlite_conf.py``, ``tests/cockroach_conf.py``). For an easy test database setup, you can use the Docker composition in ``tests/docker-compose.yml``.
+* Make sure Docker is running - Postgres and Cockroach are started automatically via `testcontainers <https://testcontainers-python.readthedocs.io/en/latest/>`_. To use an external database instead, set ``TESTCONTAINERS=false`` and configure it via the ``PG_*`` env vars (see ``tests/postgres_conf.py``). For an easy external database setup, you can use the Docker composition in ``tests/docker-compose.yaml``.
 * Run the automated code linting/formatting tools: ``./scripts/lint.sh``
 * Run the test suite with Postgres: ``./scripts/test-postgres.sh``
 * Run the test suite with Cockroach: ``./scripts/test-cockroach.sh``

pyproject.toml

@@ -17,7 +17,8 @@ module = [
     "jinja2",
     "orjson",
     "aiosqlite",
-    "uvicorn"
+    "uvicorn",
+    "testcontainers.*"
 ]
 ignore_missing_imports = true
 

requirements/test-requirements.txt

@@ -3,4 +3,5 @@ httpx==0.28.1
 pytest-cov==7.1.0
 pytest==9.0.3
 python-dateutil==2.9.0
+testcontainers>=4.0.0
 typing-extensions>=4.15.0

tests/README.md

@@ -2,11 +2,9 @@
 
 ## Database
 
-A local database needs to be running with the following credentials:
+Postgres and Cockroach are started automatically via testcontainers, so
+Docker needs to be running.
 
-```
-host = localhost:5432
-database = piccolo
-user = piccolo
-password = piccolo
-```
+To use an external database instead, set `TESTCONTAINERS=false` and point
+`PG_HOST` / `PG_PORT` / `PG_DATABASE` / `PG_USER` / `PG_PASSWORD` at it (see
+`postgres_conf.py`).

tests/apps/sql_shell/commands/test_run.py

@@ -1,3 +1,4 @@
+import os
 from unittest import TestCase
 from unittest.mock import MagicMock, patch
 
@@ -18,11 +19,11 @@ def test_psql(self, subprocess: MagicMock):
         assert subprocess.run.call_args.args[0] == [
             "psql",
             "-U",
-            "postgres",
+            os.environ.get("PG_USER", "postgres"),
             "-h",
-            "localhost",
+            os.environ.get("PG_HOST", "localhost"),
             "-p",
-            "5432",
+            os.environ.get("PG_PORT", "5432"),
             "piccolo",
         ]