From c098bdb09315dc1691f851d0070465721d8e1b95 Mon Sep 17 00:00:00 2001 From: "Kristiansen, Erling Gustav Moland" Date: Tue, 24 Mar 2026 11:28:32 +0100 Subject: [PATCH] feat: add `pg_qualstats` container image pg_qualstats is a PostgreSQL extension that collects statistics on query predicates (WHERE clauses and JOIN conditions). It records execution counts and selectivity information per operator and column, enabling query tuning and index recommendation tools like PoWA. Closes #206 Signed-off-by: Kristiansen, Erling Gustav Moland --- pg-qualstats/Dockerfile | 29 +++++++++++ pg-qualstats/README.md | 104 ++++++++++++++++++++++++++++++++++++++ pg-qualstats/metadata.hcl | 37 ++++++++++++++ 3 files changed, 170 insertions(+) create mode 100644 pg-qualstats/Dockerfile create mode 100644 pg-qualstats/README.md create mode 100644 pg-qualstats/metadata.hcl diff --git a/pg-qualstats/Dockerfile b/pg-qualstats/Dockerfile new file mode 100644 index 0000000..17df694 --- /dev/null +++ b/pg-qualstats/Dockerfile @@ -0,0 +1,29 @@ +# 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}-pg-qualstats=${EXT_VERSION}" + +FROM scratch +ARG PG_MAJOR + +# Licenses +COPY --from=builder /usr/share/doc/postgresql-${PG_MAJOR}-pg-qualstats/copyright /licenses/postgresql-${PG_MAJOR}-pg-qualstats/ + +# Libraries +COPY --from=builder /usr/lib/postgresql/${PG_MAJOR}/lib/pg_qualstats* /lib/ +COPY --from=builder /usr/lib/postgresql/${PG_MAJOR}/lib/bitcode/ /lib/bitcode/ + +# Share +COPY --from=builder /usr/share/postgresql/${PG_MAJOR}/extension/pg_qualstats* /share/extension/ + +USER 65532:65532 diff --git a/pg-qualstats/README.md b/pg-qualstats/README.md new file mode 100644 index 0000000..7316406 --- /dev/null +++ b/pg-qualstats/README.md @@ -0,0 +1,104 @@ +# pg_qualstats + + +[pg_qualstats](https://github.com/powa-team/pg_qualstats) is a PostgreSQL +extension that collects statistics about predicates (quals) found in +`WHERE` clauses and `JOIN` conditions. It can be used to identify missing +indexes and understand query workload patterns. For more information, see the +[official documentation](https://powa.readthedocs.io/en/latest/components/pg_qualstats.html). + +## Usage + +The `pg_qualstats` extension must be loaded via `shared_preload_libraries` +to hook into the query executor and collect predicate statistics. + +### 1. Add the pg_qualstats extension image to your Cluster + +Define the `pg-qualstats` extension under the `postgresql.extensions` section +of your `Cluster` resource. For example: + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: Cluster +metadata: + name: cluster-pg-qualstats +spec: + imageName: ghcr.io/cloudnative-pg/postgresql:18-minimal-trixie + instances: 1 + + storage: + size: 1Gi + + postgresql: + shared_preload_libraries: + - pg_qualstats + extensions: + - name: pg-qualstats + image: + # renovate: suite=trixie-pgdg depName=postgresql-18-pg-qualstats + reference: ghcr.io/cloudnative-pg/pg-qualstats:2.1.3-18-trixie +``` + +### 2. Enable the extension in a database + +You can install `pg_qualstats` 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-qualstats-app +spec: + name: app + owner: app + cluster: + name: cluster-pg-qualstats + extensions: + - name: pg_qualstats + # renovate: suite=trixie-pgdg depName=postgresql-18-pg-qualstats + version: '2.1.3' +``` + +### 3. Verify installation + +Once the database is ready, connect to it with `psql` and run: + +```sql +\dx +``` + +You should see `pg_qualstats` listed among the installed extensions. + +## 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_qualstats` 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-qualstats/metadata.hcl b/pg-qualstats/metadata.hcl new file mode 100644 index 0000000..f50c0cd --- /dev/null +++ b/pg-qualstats/metadata.hcl @@ -0,0 +1,37 @@ +# SPDX-FileCopyrightText: Copyright © contributors to CloudNativePG, established as CloudNativePG a Series of LF Projects, LLC. +# SPDX-License-Identifier: Apache-2.0 +metadata = { + name = "pg-qualstats" + sql_name = "pg_qualstats" + image_name = "pg-qualstats" + licenses = ["PostgreSQL"] + shared_preload_libraries = ["pg_qualstats"] + postgresql_parameters = {} + extension_control_path = [] + dynamic_library_path = [] + ld_library_path = [] + bin_path = [] + env = {} + auto_update_os_libs = false + required_extensions = [] + create_extension = true + + versions = { + bookworm = { + "18" = { + // renovate: suite=bookworm-pgdg depName=postgresql-18-pg-qualstats + package = "2.1.3-1.pgdg12+1" + // renovate: suite=bookworm-pgdg depName=postgresql-18-pg-qualstats extractVersion=^(?\d+\.\d+\.\d+) + sql = "2.1.3" + } + } + trixie = { + "18" = { + // renovate: suite=trixie-pgdg depName=postgresql-18-pg-qualstats + package = "2.1.3-1.pgdg13+1" + // renovate: suite=trixie-pgdg depName=postgresql-18-pg-qualstats extractVersion=^(?\d+\.\d+\.\d+) + sql = "2.1.3" + } + } + } +}