diff --git a/pg-partman/Dockerfile b/pg-partman/Dockerfile new file mode 100644 index 0000000..a36e494 --- /dev/null +++ b/pg-partman/Dockerfile @@ -0,0 +1,34 @@ +# SPDX-FileCopyrightText: Copyright © contributors to CloudNativePG, established as CloudNativePG a Series of LF Projects, LLC. +# SPDX-License-Identifier: Apache-2.0 + +ARG BASE=ghcr.io/cloudnative-pg/postgresql:18-minimal-trixie +FROM $BASE AS builder + +ARG PG_MAJOR +ARG EXT_VERSION + +USER 0 + +# Install extension via `apt-get` +RUN apt-get update && apt-get install -y --no-install-recommends \ + "postgresql-${PG_MAJOR}-partman=${EXT_VERSION}" + +FROM scratch +ARG PG_MAJOR + +# Licenses +COPY --from=builder /usr/share/doc/postgresql-${PG_MAJOR}-partman/copyright /licenses/postgresql-${PG_MAJOR}-partman/ + +# Libraries +COPY --from=builder /usr/lib/postgresql/${PG_MAJOR}/lib/pg_partman_bgw.so /lib/ +COPY --from=builder /usr/lib/postgresql/${PG_MAJOR}/lib/bitcode/ /lib/bitcode/ + +# Share +COPY --from=builder /usr/share/postgresql/${PG_MAJOR}/extension/pg_partman* /share/extension/ + +# Binaries (maintenance scripts) +COPY --from=builder /usr/lib/postgresql/${PG_MAJOR}/bin/check_unique_constraint.py /bin/ +COPY --from=builder /usr/lib/postgresql/${PG_MAJOR}/bin/dump_partition.py /bin/ +COPY --from=builder /usr/lib/postgresql/${PG_MAJOR}/bin/vacuum_maintenance.py /bin/ + +USER 65532:65532 diff --git a/pg-partman/README.md b/pg-partman/README.md new file mode 100644 index 0000000..dda5e52 --- /dev/null +++ b/pg-partman/README.md @@ -0,0 +1,123 @@ +# pg_partman + + +[pg_partman](https://github.com/pgpartman/pg_partman) is a PostgreSQL extension +for automated table partition management. It supports both time-based and +ID-based partitioning with automatic creation and maintenance of child tables. + +The extension includes a background worker (`pg_partman_bgw`) that can +automatically run partition maintenance at configured intervals, removing the +need for external cron jobs. + +For more information, see the +[official documentation](https://github.com/pgpartman/pg_partman). + +## Usage + +The `pg_partman` extension must be loaded via `shared_preload_libraries` to +enable the background worker. The worker periodically runs +`partman.run_maintenance_proc()` to create new partitions and drop expired ones. + +### 1. Add the pg_partman extension image to your Cluster + +Define the `pg-partman` extension under the `postgresql.extensions` section of +your `Cluster` resource. For example: + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: Cluster +metadata: + name: cluster-pg-partman +spec: + imageName: ghcr.io/cloudnative-pg/postgresql:18-minimal-trixie + instances: 1 + + storage: + size: 1Gi + + postgresql: + shared_preload_libraries: + - pg_partman_bgw + extensions: + - name: pg-partman + image: + # renovate: suite=trixie-pgdg depName=postgresql-18-partman + reference: ghcr.io/cloudnative-pg/pg-partman:5.4.3-18-trixie +``` + +### 2. Enable the extension in a database + +You can install `pg_partman` in a specific database by creating or updating a +`Database` resource. For example, to enable it in the `app` database: + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: Database +metadata: + name: cluster-pg-partman-app +spec: + name: app + owner: app + cluster: + name: cluster-pg-partman + extensions: + - name: pg_partman + # renovate: suite=trixie-pgdg depName=postgresql-18-partman + version: '5.4.3' +``` + +### 3. Verify installation + +Once the database is ready, connect to it with `psql` and run: + +```sql +\dx +``` + +You should see `pg_partman` listed among the installed extensions. + +## Included utilities + +This image also bundles the following Python maintenance scripts in `/bin/`: + +- `check_unique_constraint.py` — validates unique constraints across partitions +- `dump_partition.py` — exports individual partitions for archival +- `vacuum_maintenance.py` — targeted vacuum operations on partitioned tables + +> [!NOTE] +> These scripts require a Python 3 runtime and the `psycopg2` library, which +> are not included in the minimal base image. They are provided for +> environments where Python is available on the host or in a sidecar container. + +## Contributors + +This extension is maintained by: + +- Erling Kristiansen (@egkristi) + +The maintainers are responsible for: + +- Monitoring upstream releases and security vulnerabilities. +- Ensuring compatibility with supported PostgreSQL versions. +- Reviewing and merging contributions specific to this extension's container + image and lifecycle. + +--- + +## Licenses and Copyright + +This container image contains software that may be licensed under various +open-source licenses. + +All relevant license and copyright information for the `pg_partman` extension +and its dependencies are bundled within the image at: + +```text +/licenses/ +``` + +By using this image, you agree to comply with the terms of the licenses +contained therein. diff --git a/pg-partman/metadata.hcl b/pg-partman/metadata.hcl new file mode 100644 index 0000000..4871179 --- /dev/null +++ b/pg-partman/metadata.hcl @@ -0,0 +1,27 @@ +# SPDX-FileCopyrightText: Copyright © contributors to CloudNativePG, established as CloudNativePG a Series of LF Projects, LLC. +# SPDX-License-Identifier: Apache-2.0 +metadata = { + name = "pg-partman" + sql_name = "pg_partman" + image_name = "pg-partman" + licenses = ["PostgreSQL"] + shared_preload_libraries = ["pg_partman_bgw"] + extension_control_path = [] + dynamic_library_path = [] + ld_library_path = [] + bin_path = ["bin"] + auto_update_os_libs = false + required_extensions = [] + create_extension = true + + versions = { + bookworm = { + // renovate: suite=bookworm-pgdg depName=postgresql-18-partman + "18" = "5.4.3-1.pgdg12+1" + } + trixie = { + // renovate: suite=trixie-pgdg depName=postgresql-18-partman + "18" = "5.4.3-1.pgdg13+1" + } + } +}