Add Docker test image and documentation

Based on PR pgpartman#279 by @jcoleman, this includes a Dockerfile for a PG17 based
image, scripts to automate re/building the extension and re/creating the test
DB, and notes on how to run the tests the same way as the CI pipeline.

Author: calebj

docker/Dockerfile

@@ -0,0 +1,9 @@
+FROM pgxn/pgxn-tools:latest
+
+RUN NO_CLUSTER=1 pg-start 17 postgresql-17-pgtap
+
+ADD entrypoint.sh /usr/local/bin/
+
+WORKDIR /pg_partman
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
+CMD ["/bin/bash"]

docker/README_docker.md

@@ -0,0 +1,56 @@
+## Docker Environment
+
+If you don't have a build environment setup on your local machine, the project provides a docker container setup for your convenience. As long as Docker is installed, you can use the following commands to run tests:
+
+```sh
+# Build the image:
+docker build -t partman_test_image ./docker
+
+# Start the container. This will initialize and start Postgres, then drop to a shell.
+docker run -it --name partman_test -v "$(pwd):/pg_partman" partman_test_image
+```
+
+The source code for pg_partman is mounted inside the container rather than included in the build, so any changes can be tested without rebuilding the container.
+
+Example commands to run inside the container:
+
+```sh
+# Convenience script to build and install pg_partman, then create a database named partman_test.
+# This does a fresh build+install each time, and the database is recreated if it already exists.
+docker/build_for_tests.sh
+
+# Run a specific test
+pg_prove -ovf -U postgres -d partman_test test/<test_file_path>.sql
+
+# Build, install, create DB and run all tests
+docker/build_and_test.sh
+
+# The script can run specific tests as well (relative to test/)
+docker/build_and_test.sh <test_file_path>.sql
+```
+
+You can also start the container and run the tests in one command with:
+
+```sh
+# All tests
+docker run --rm -it -v "$(pwd):/pg_partman" partman_test_image docker/build_and_test.sh
+
+# Specific tests, again relative to test/
+docker run --rm -it -v "$(pwd):/pg_partman" partman_test_image docker/build_and_test.sh <test_file_path>.sql
+```
+
+When finished, stop and optionally remove the container.
+
+```sh
+docker stop partman_test
+docker rm partman_test
+```
+
+### Replicating the CI environment
+
+Both the above image and the GitHub CI pipeline use the [pgxn-tools](https://github.com/pgxn/docker-pgxn-tools) image. The Dockerfile and entrypoint in this folder are meant to ease iterative development, but you can use the standalone entrypoint to run the same steps that CI does.
+
+```sh
+# Install PostgreSQL 17 and run all tests, discarding the container afterwards
+docker run -it --rm -w /pg_partman --volume "$(pwd):/pg_partman" pgxn/pgxn-tools docker/pgxn_standalone_entrypoint.sh 17
+```

docker/build_and_test.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+set -e
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+
+cd "$SCRIPT_DIR/.."
+
+docker/build_for_tests.sh
+
+cd test
+
+pg_prove --dbname partman_test --username postgres --ext .sql --comments --verbose --failures ${@:-.}

docker/build_for_tests.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+set -e
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+
+cd "$SCRIPT_DIR/.."
+
+make && make install
+
+psql -U postgres -c "DROP DATABASE IF EXISTS partman_test"
+psql -U postgres -c "CREATE DATABASE partman_test"
+psql -U postgres -d partman_test -c "CREATE EXTENSION pgtap"
+psql -U postgres -d partman_test -c "CREATE SCHEMA partman"
+psql -U postgres -d partman_test -c "CREATE EXTENSION pg_partman SCHEMA partman"

docker/entrypoint.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -e
+
+pg_createcluster 17 test --start -p 5432 --pgoption max_locks_per_transaction=128 -- -A trust
+
+exec $@

docker/pgxn_standalone_entrypoint.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -e
+
+if [ ! -n $1 ] ; then
+    echo "Usage: $0 <PG_VERSION> [test_to_run.sql ...]" >&2
+    exit 1
+elif ! [[ $1 =~ ^[0-9]+$ ]]; then
+    echo "PG_VERSION must be a positive integer." >&2
+    exit 1
+else
+    PG_VERSION=$1
+    shift
+fi
+
+CREATE_OPTIONS="--pgoption max_locks_per_transaction=128" pg-start $PG_VERSION postgresql-$PG_VERSION-pgtap
+
+exec /pg_partman/docker/build_and_test.sh $@

test/README_test.md

@@ -39,3 +39,11 @@ Tests for the Background Worker can be found in the test/test_bgw folder. Please
 Tests for procedures are in their own folders. These must be run in stages with manual commands between them since pgTap cannot handle distinct commits within a single test run.
 
 Tests for the reindexing script are in development and will return once the reindexing feature has been updated. They can be found in the test/test_reindex folder. These tests cannot just be run all at once and are not run within rolled back transactions. They must be run in order, one at a time, and there are explicit instructions at the end of each test for what to do next.
+
+### Running tests in Docker
+See [README_docker.md](../docker/README_docker.md) for instructions on testing inside a persistent container running PostgreSQL 17.
+
+To run the same tests as GitHub CI (on PostgreSQL 17):
+```sh
+docker run -it --rm -w /pg_partman --volume "$(pwd):/pg_partman" pgxn/pgxn-tools docker/pgxn_standalone_entrypoint.sh 17
+```