Contributing#

Bug reports, feature requests, code changes, and documentation improvements are welcome through GitHub issues and pull requests.

Development#

pgpartix is packaged as a Docker image. It is developed with Bash and SQL. For development, you will Docker need pre-commit.

Install pre-commit:

python3.12 -m pip install --upgrade pre-commit

Install the Git hooks:
```
pre-commit install
```

Project structure#

.
├── src
│   ├── bin                       # Binaries (pgp-*)
│   ├── sql                       # Database functions, numbered by load order
│   ├── schema.json               # JSON Schema for lifecycle configuration files
│   └── createcluster.conf        # Debian pg_createcluster defaults for the image
├── docs                          # Schema doc tooling (schema_doc_generator.sh, schema_doc.yaml)
│   └── docs                      # Published guides (index.md is the index),
│                                    plus the generated schema.html — this is the GitHub Pages root
├── examples                      # End-to-end configuration examples
├── tests                         # Bats integration tests and fixtures
│   ├── fixtures
│   │   ├── expire_partitions
│   │   ├── make_partitions
│   │   └── initdir               # SQL applied once when the test cluster starts
│   ├── test_make_partitions.sh
│   ├── test_expire_partitions.sh
│   ├── test_get_migration_filename.sh
│   ├── test_setup_infrastructure.sh
│   ├── test_start.sh
│   ├── run-tests.sh              # Builds the test image and runs the suite in Docker
│   ├── run-coverage.sh           # Runs bats under kcov and enforces MIN_COVERAGE
│   └── docker-compose-test.yaml
├── tools                         # Repo lifecycle scripts (schema doc freshness check)
└── config.sample.yaml            # Complete annotated configuration reference

Architecture#

pgpartix has two main components:

The Binaries: The src/bin commands orchestrate lifecycle generation.
The Database Functions: Functions in src/sql inspect PostgreSQL and render the DDL for lifecycle generation

Testing#

Tests are Bats integration tests driven through the public CLI, run inside the project's Docker image against a disposable PostgreSQL cluster. There is no unit-test layer or pgTAP suite; every SQL function is exercised only through the CLI commands that call it.

Each test_*.sh file under tests/ covers one binary. test_make_partitions.sh and test_expire_partitions.sh additionally auto-discover every fixture directory under tests/fixtures/{make_partitions,expire_partitions}/ and run it as its own test case, so adding coverage for a new option is usually just adding a fixture, not editing the .sh file.

A fixture directory can contain:

File	Purpose
`setup.sql`	Optional. Applied before the command runs (schema, tables, template objects, `ALTER SYSTEM SET mock.now = ...`). Requires a matching `teardown.sql`.
`teardown.sql`	Drops what `setup.sql` created. Required whenever `setup.sql` is present.
`config.yaml`	The lifecycle configuration passed to `-c`. Fixtures with multiple config files (e.g. one per scenario) each get their own `*.expected.sql`, matched by stripping the `.yaml`/`.yml` extension.
`config.expected.sql` (or `<name>.expected.sql`)	The exact output the command must produce, including `pgrubic format`'s formatting.

The test runner diffs the generated file against *.expected.sql and then applies the generated SQL to a throwaway database to confirm it is valid, executable DDL - not just textually correct.

tests/coverage collects kcov output from run-coverage.sh, which is what docker-compose-test.yaml runs inside the container; run-tests.sh is the entry point that builds the image and drives that container.

To run tests, use:

./tests/run-tests.sh

To run tests for a specific postgres version, use:

PGP_PG_MAJOR_VERSION=<POSTGRES_MAJOR_VERSION> ./tests/run-tests.sh

Documentation#

The schema reference is generated with json-schema-for-humans. After changing src/schema.json, run:

./docs/schema_doc_generator.sh

Preview docs/docs/schema.html in a browser.

Release#

To create a release:

git checkout -B Release
git pull --rebase origin main
git fetch --tags
git tag

# using the next available version, create a new tag e.g
git tag -a 0.7.0 -m "Release 0.7.0"

# push the new tag to trigger the release
git push origin 0.7.0