← Browse the extensions catalog

pglogical

Source README ↗

pglogical

Logical replication through PostgreSQL connections. Upstream project.

Follow the quick start to set up extension-update email alerts first, then use the CronJob to install and refresh the catalog. These examples inherit image references and runtime settings from the catalog. The Cluster YAML is an excerpt: replace imageCatalogRef: ... with your catalog reference and keep your existing instance and storage settings.

Supported images

PostgreSQL 18; Debian Trixie and Bookworm; amd64 and arm64 build targets.

Usage

1. Add the pglogical extension image to your Cluster

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-pglogical
spec:
  imageCatalogRef: ...
  postgresql:
    shared_preload_libraries:
    - pglogical
    parameters:
      wal_level: logical
      output_plugin_libraries: pgoutput,test_decoding,pglogical_output
    extensions:
    - name: pglogical

2. Enable the extension in a database

Once the extension's files are available in the cluster, you can install it in a database in either of two ways:

Platform teams may make extension containers available across their clusters without installing every extension in every database. Install only the extensions a database uses; letting users enable them through SQL alongside the rest of their DDL schema management code can be a convenient approach.

For extensions that normally require superuser privileges, platform teams can use pgextwlist to allow non-superusers to install an administrator-approved selection of extensions.

3. Verify installation

Connect to the database with psql and run \dx to check the installed extensions.

Operation and privileges

Create provider and subscriber databases with this extension and matching table definitions. Both endpoints must use CNPG-managed PostgreSQL Services. Store connection credentials in Kubernetes Secrets and initialize nodes/subscriptions from a declarative Job or your deployment system. Administrative setup and replication roles need the privileges required by pglogical.

Call pglogical.create_node for each endpoint, register tables with pglogical.replication_set_add_table, and call pglogical.create_subscription on the subscriber. Set synchronize_structure := false. Optional schema synchronization is unsupported until its temporary-file storage, access, retention and cleanup are designed. Apply schema changes through your normal migration process.

Monitor replication lag and retained WAL on the PostgreSQL data volume. Plan slot limits and disk capacity; remove unused subscriptions with pglogical.drop_subscription and remove unused nodes after their consumers are stopped. Failed consumers must not retain WAL indefinitely. No extra listener or container shell setup is required.

Dependencies and updates

The image contains only the PGDG package server payload and license notices. The matching CNPG minimal image supplies PostgreSQL, libc and its base runtime. Project automation tracks package updates and rebuilds the extension images. Use the catalog maintenance schedule in the quick start to consume published PostgreSQL and extension image updates. Monitor pending SQL extension upgrades and review them separately; SQL versions need not match package versions.

Licenses and ownership

PostgreSQL. Redistribution notices are preserved under /licenses/.

The package also includes pglogical_origin version 1.0.0, an empty compatibility extension for upgrades from PostgreSQL 9.4. It is not needed for new PostgreSQL 18 replication setups. The upstream SQL suite exercises it in selected replication cases.