[tests] For testing, run Postgres from Docker (#177)

Instead of assuming a local installation of Postgres (which is a lot
more intrusive), just assume the existence of Docker, and run Postgres
inside a Docker container. This allows running a clean Docker container
in every test, which will unblock wider testing with Postgres.

This also reduces the dependencies for running the test suite from
requiring Postgres to only requiring Docker, which should be fine to
assume since we already use Docker for a bunch of stuff in LNT.

Finally, this also moves the installation.shtest from being a unit test
to something that we only run in the CI. This was a slow test which
required the network and really didn't belong in a Lit test.

This patch was created with Claude's assistance but I did review
everything, made manual tweaks, etc.

Author: ldionne

.github/workflows/check-installation.yaml

@@ -0,0 +1,37 @@
+name: Check installation
+
+permissions:
+  contents: read
+
+on:
+  - push
+  - pull_request
+
+jobs:
+  check-installation:
+    runs-on: ubuntu-latest
+    name: "Python ${{ matrix.python-version }}"
+
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+      fail-fast: false
+
+    steps:
+    - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install PostgreSQL development headers
+      run: sudo apt-get install -y libpq-dev
+    - name: Check client installation
+      run: |
+        python -m venv .venv-client
+        .venv-client/bin/python -m pip install -r requirements.client.txt
+        .venv-client/bin/lnt create lnt-client-instance
+    - name: Check server installation
+      run: |
+        python -m venv .venv-server
+        .venv-server/bin/python -m pip install -r requirements.server.txt
+        .venv-server/bin/lnt create lnt-server-instance

.github/workflows/tox.yaml

@@ -10,12 +10,11 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
-    name: "Python ${{ matrix.python-version }}, Postgres=${{ matrix.with-postgres }}"
+    name: "Python ${{ matrix.python-version }}"
 
     strategy:
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
-        with-postgres: [true, false]
       fail-fast: false
 
     steps:
@@ -30,11 +29,6 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install tox tox-gh-actions
-    - name: Install PostgreSQL
-      if: ${{ matrix.with-postgres }}
-      uses: tj-actions/install-postgresql@a889ed6c6fa05022333ed4101295bb1d604f97a8 # v3.2.0
-      with:
-        postgresql-version: 17
     - name: Tox flake8
       run: tox -e flake8
     - name: Tox docs

docs/developer_guide.rst

@@ -19,8 +19,8 @@ virtual environment and installing the development dependencies::
     pip install ".[dev]"
 
 This will install the current version of the package, along with the dependencies
-required for development (``lit``, ``filecheck``, etc). Note that ``curl`` and
-``jq`` are also required for running the tests.
+required for development (``lit``, ``filecheck``, etc). Note that ``curl``, ``jq``
+and ``docker`` are also required for running the tests.
 
 Running LNT's Regression Tests
 ------------------------------

tests/SharedInputs/postgres_wrapper.sh

@@ -2,7 +2,6 @@
 
 import os
 import platform
-import shutil
 
 import lit.formats
 import lit.util
@@ -39,20 +38,13 @@ config.environment['I'] = ""
 src_root = os.path.join(config.test_source_root, '..')
 config.substitutions.append(('%src_root', src_root))
 config.substitutions.append(('%{src_root}', src_root))
-config.substitutions.append(('%{shared_inputs}', os.path.join(
-            src_root, 'tests', 'SharedInputs')))
+config.substitutions.append(('%{shared_inputs}', os.path.join(config.test_source_root, 'SharedInputs')))
+config.substitutions.append(('%{utils}', os.path.join(config.test_source_root, 'utils')))
 config.substitutions.append(('%{test_exec_root}', config.test_exec_root))
 
 if lit_config.params.get('long', None):
     config.available_features.add('long')
 
-# Enable postgres database support testing if the postgres binary can be found.
-# Note that you do not need to setup an actual server, the tests will create
-# temporary instances on demand.
-postgres = shutil.which('postgres')
-if postgres is not None:
-    config.available_features.add('postgres')
-
 # Enable tidylib testing. This requires pytidylib and tidy-html5.
 if lit_config.params.get('tidylib', None):
     config.substitutions.append(('%{tidylib}', '--use-tidylib'))

tests/lit.cfg

@@ -1,15 +1,12 @@
-# REQUIRES: postgres
 # RUN: rm -rf "%t.install"
-# RUN: %{shared_inputs}/postgres_wrapper.sh "%t.install" bash %s "%t.install" postgresql://pgtest@localhost:9100 "%{shared_inputs}"
+# RUN: mkdir -p "%t.install"
+# RUN: %{utils}/with_postgres.sh %t.log bash %s "%t.install" "%{shared_inputs}"
 set -eux
 
 TESTDIR="$1"
-PGURL="$2"
-SHARED_INPUTS="$3"
-dropdb --if-exists --maintenance-db="${PGURL}/postgres" lnt_regr_test_PostgresDB
-createdb --maintenance-db="${PGURL}/postgres" lnt_regr_test_PostgresDB
+SHARED_INPUTS="$2"
 
-lnt create "${TESTDIR}/instance" --db-dir ${PGURL} --default-db lnt_regr_test_PostgresDB
+lnt create "${TESTDIR}/instance" --db-dir ${LNT_TEST_DB_URI} --default-db ${LNT_TEST_DB_NAME}
 
 # Import a test set.
 lnt import "${TESTDIR}/instance" "${SHARED_INPUTS}/sample-a-small.plist" --show-sample-count

tests/lnttool/PostgresDB.shtest

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+#
+# with_postgres.sh <LOG_FILE> <command> [args...]
+#
+# Start a fresh PostgreSQL container, run the wrapped command, then stop and
+# remove the container. The following environment variables are exported before
+# the command runs:
+#
+#   LNT_TEST_DB_URI      Base connection URL (no database), e.g. postgresql://postgres@127.0.0.1:PORT
+#   LNT_TEST_DB_NAME     Name of a ready-to-use database ("lnt_test")
+#
+# Example:
+#   with_postgres.sh /tmp/my.log bash my_test.sh "${LNT_TEST_DB_URI}" "${LNT_TEST_DB_NAME}"
+#
+set -euo pipefail
+
+if ! command -v docker > /dev/null 2>&1; then
+    echo "error: Could not find 'docker' -- Docker is required to run the tests"
+    exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Arguments
+# ---------------------------------------------------------------------------
+if [ $# -lt 2 ]; then
+    echo 1>&2 "usage: $(basename "$0") <LOG_FILE> <command> [args...]"
+    exit 1
+fi
+
+LOG_FILE="$1"
+shift
+
+if [ -f "${LOG_FILE}" ]; then
+    echo 1>&2 "error: Log file ${LOG_FILE} already exists"
+    exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Unique container name — allows parallel test runs without collision.
+# ---------------------------------------------------------------------------
+CONTAINER_NAME="lnt_pg_$(uuidgen | tr '[:upper:]' '[:lower:]' | tr -d '-')"
+
+# ---------------------------------------------------------------------------
+# Cleanup — always stop and remove the container, success or failure.
+# ---------------------------------------------------------------------------
+cleanup() {
+    local exit_code=$?
+    echo "Stopping container ${CONTAINER_NAME} ..."
+    docker stop  "${CONTAINER_NAME}" > /dev/null 2>&1 || true
+    docker rm    "${CONTAINER_NAME}" > /dev/null 2>&1 || true
+    exit "${exit_code}"
+}
+trap cleanup EXIT
+
+# ---------------------------------------------------------------------------
+# Start the container in the background and bind a random port from the host
+# to the container's 5432 port. Stream the logs of the container into the
+# specified log file -- useful for debugging.
+#
+# Key flags:
+#   POSTGRES_HOST_AUTH_METHOD=trust     no password needed
+#   --tmpfs /var/lib/postgresql/data    store data in RAM — faster, no cleanup needed
+# ---------------------------------------------------------------------------
+echo "Starting container ${CONTAINER_NAME} ..."
+docker run \
+    --detach \
+    --name "${CONTAINER_NAME}" \
+    --publish "127.0.0.1::5432" \
+    --env POSTGRES_HOST_AUTH_METHOD=trust \
+    --tmpfs /var/lib/postgresql/data \
+    postgres:17-alpine \
+    > /dev/null 2>&1
+
+echo "Streaming PostgreSQL server logs into ${LOG_FILE}"
+docker logs --follow "${CONTAINER_NAME}" >> "${LOG_FILE}" 2>&1 &
+
+# ---------------------------------------------------------------------------
+# Discover the host port that Docker assigned.
+# `docker port` output: "n.n.n.n:PORT"
+# ---------------------------------------------------------------------------
+HOST_PORT=$(docker port "${CONTAINER_NAME}" 5432/tcp | head -1 | sed 's/.*://')
+if [ -z "${HOST_PORT}" ]; then
+    echo 1>&2 "error: could not determine host port for container ${CONTAINER_NAME}"
+    docker logs "${CONTAINER_NAME}" 1>&2
+    exit 1
+fi
+
+export LNT_TEST_DB_URI="postgresql://postgres@127.0.0.1:${HOST_PORT}"
+echo "PostgreSQL available at: ${LNT_TEST_DB_URI}"
+
+# ---------------------------------------------------------------------------
+# Wait for PostgreSQL to accept connections (up to 30 seconds).
+# pg_isready is available inside the official postgres image.
+#
+# NOTE: We use '-h localhost' to check via TCP rather than the Unix socket.
+# The official postgres image runs a temporary server during initdb that
+# listens only on the Unix socket (listen_addresses=''). Without '-h localhost',
+# pg_isready can succeed against that temp server, then createdb fails when
+# the socket disappears during the transition to the real server.
+# ---------------------------------------------------------------------------
+MAX_TRIES=30
+for i in $(seq 1 "${MAX_TRIES}"); do
+    if docker exec "${CONTAINER_NAME}" pg_isready --quiet -h localhost; then
+        echo "PostgreSQL ready after ${i} attempt(s)."
+        break
+    fi
+    if [ "${i}" -eq "${MAX_TRIES}" ]; then
+        echo 1>&2 "error: PostgreSQL did not become ready after ${MAX_TRIES}s."
+        docker logs "${CONTAINER_NAME}" 1>&2
+        exit 1
+    fi
+    sleep 1
+done
+
+# ---------------------------------------------------------------------------
+# Create a default database for tests to use.
+# ---------------------------------------------------------------------------
+docker exec "${CONTAINER_NAME}" createdb --username=postgres lnt_test
+export LNT_TEST_DB_NAME="lnt_test"
+
+# ---------------------------------------------------------------------------
+# Run the wrapped command.
+# ---------------------------------------------------------------------------
+eval "$@"