---
id: v1.25
title: Release notes for CloudNativePG 1.25
---

# Release notes for CloudNativePG 1.25
<!-- SPDX-License-Identifier: CC-BY-4.0 -->

History of user-visible changes in the 1.25 minor release of CloudNativePG.

For a complete list of changes, please refer to the
[commits](https://github.com/cloudnative-pg/cloudnative-pg/commits/release-1.25)
on the release branch in GitHub.

## Version 1.25.4

**Release date:** Oct 23, 2025

:::warning
    This is the final release in the 1.25.x series.
    Users are strongly encouraged to upgrade to a newer minor version, as 1.25
    is no longer supported.
:::

### Changes

- Adopted the new format of `postgres-containers` and `postgis-containers`
  images and image catalog artifacts, and **updated** the default PostgreSQL
  version to `18.0-system-trixie` (PostgreSQL 18 is now supported).
  ([#8578](https://github.com/cloudnative-pg/cloudnative-pg/pull/8578),
  [#8760](https://github.com/cloudnative-pg/cloudnative-pg/pull/8760),
  [#8558](https://github.com/cloudnative-pg/cloudnative-pg/pull/8558))

- Deprecated the `monitoring.enablePodMonitor` field in the `Cluster` and
  `Pooler` resources. This field will be removed in a future release. Users who
  rely on `PodMonitor` resources should create them manually instead.
  ([#8753](https://github.com/cloudnative-pg/cloudnative-pg/pull/8753))

### Enhancements

- Added support for overriding the PgBouncer `auth_type`, `server_tls_sslmode`,
  and `client_tls_sslmode` settings, which were previously hardcoded. Default
  values remain consistent with the former behavior but can now be customized
  when required.
  ([#8674](https://github.com/cloudnative-pg/cloudnative-pg/pull/8674))

- Added a `CHECKPOINT` step before PostgreSQL smart and fast shutdowns to
  reduce shutdown duration and replica promotion time, especially on systems
  with a high `checkpoint_timeout`.
  ([#8867](https://github.com/cloudnative-pg/cloudnative-pg/pull/8867))

- Added a warning in the instance manager for deprecated or unsupported OS
  versions, based on the official `postgres-containers` project.
  ([#8601](https://github.com/cloudnative-pg/cloudnative-pg/pull/8601))

- Improved certificate parsing error reporting. Failures now log specific
  errors instead of a generic message, aiding troubleshooting. This is
  particularly relevant after the CVE-2025-58187 fix in Go 1.25.2 and 1.24.8,
  which may trigger parsing failures for invalid DNS SANs.
  ([#8801](https://github.com/cloudnative-pg/cloudnative-pg/pull/8801))

- Added a check to ensure the destination WAL archive path is empty when
  bootstrapping a cluster using the `pg_basebackup` method, consistent with
  other bootstrap methods.
  ([#8895](https://github.com/cloudnative-pg/cloudnative-pg/pull/8895))

- Added validation to prevent backups from running on hibernated clusters.
  Backups attempted on such clusters now fail with reason
  `ClusterIsHibernated`, following the standard prerequisite check pattern.
  ([#8870](https://github.com/cloudnative-pg/cloudnative-pg/pull/8870))

- Added support for `pprof` profiling. Instances can now enable the `pprof`
  tool by adding the `alpha.cnpg.io/enableInstancePprof` annotation to the
  `Cluster` resource for advanced debugging.
  ([#7876](https://github.com/cloudnative-pg/cloudnative-pg/pull/7876))

- `cnpg` plugin:

   - Updated the Flexible I/O Tester (FIO) image to
     `wallnerryan/fiotools-aio:v2`, as provided by Ryan Wallner.
     ([#8847](https://github.com/cloudnative-pg/cloudnative-pg/pull/8847))

   - Enhanced the `cnpg status backup` command to provide more detailed status
     information when using a `barman-cloud`-based backup plugin.
     ([#8780](https://github.com/cloudnative-pg/cloudnative-pg/pull/8780),
     [#8690](https://github.com/cloudnative-pg/cloudnative-pg/pull/8690))

### Fixes

- Fixed backup restoration failures when using custom WAL segment sizes with
  parallel WAL recovery. The operator no longer manages the end-of-WAL file
  marker during restoration, preventing errors when backups span multiple WAL
  segments.
  ([#8873](https://github.com/cloudnative-pg/cloudnative-pg/pull/8873))

- Fixed a bug in major upgrades where a volume snapshot from a previous minor
  version could be incorrectly used to optimize replica creation.
  ([#8475](https://github.com/cloudnative-pg/cloudnative-pg/pull/8475))

- Fixed `initdb` to wait for the application user secret before bootstrapping
  a new cluster, preventing potential race conditions.
  ([#8663](https://github.com/cloudnative-pg/cloudnative-pg/pull/8663))

- Fixed the connection retry logic in the `cnpgi` plugin. The reconciliation
  loop now detects connection pool changes correctly and uses exponential
  backoff to reduce "closed pool" errors.
  ([#8554](https://github.com/cloudnative-pg/cloudnative-pg/pull/8554))

- Fixed volume snapshot usage during replica scaling to work with backup plugins.
  Previously, this optimization was only available with the in-tree backup
  implementation, but now clusters using backup plugins can also leverage volume
  snapshots when creating new replicas.
  ([#8506](https://github.com/cloudnative-pg/cloudnative-pg/pull/8506))

- Fixed the `Pooler` templating to correctly inherit settings for the
  bootstrap controller init container.
  ([#8394](https://github.com/cloudnative-pg/cloudnative-pg/pull/8394))

- Fixed webhook errors to use the correct API group (`postgresql.cnpg.io`) in
  `Pooler` and backup webhooks, ensuring consistent API error reporting.
  ([#8485](https://github.com/cloudnative-pg/cloudnative-pg/pull/8485))

- Fixed a potential nil pointer dereference in the hibernation reconciler when
  handling errors. Contributed by @PascalBourdier.
  ([#8756](https://github.com/cloudnative-pg/cloudnative-pg/pull/8756))

- Fixed an issue in the environment cache where callers could inadvertently
  modify shared data. The `LoadEnv` function now returns a copy of cached
  environment slices to prevent mutations from affecting the cache.
  ([#8880](https://github.com/cloudnative-pg/cloudnative-pg/pull/8880))

## Version 1.25.3

**Release date:** Jul 25, 2025

*In memory of [DJ Walker-Morgan](https://www.linkedin.com/in/codepope/).*

### Changes

- Removed `386` and ARM (v5/v6/v7) architectures from the `cnpg` plugin build
  matrix, reducing the number of published binaries
  ([#7648](https://github.com/cloudnative-pg/cloudnative-pg/pull/7648)).

### Enhancements

- Improved validation of `shared_buffers` by correctly considering `HugePages`
  settings, ensuring accurate memory configuration checks
  ([#7864](https://github.com/cloudnative-pg/cloudnative-pg/pull/7864)).

- Set `oom_score_adj` for PostgreSQL worker processes to improve prioritization
  during out-of-memory situations
  ([#7891](https://github.com/cloudnative-pg/cloudnative-pg/pull/7891)).

- Added `fqdn-uri` and `fqdn-jdbc-uri` fields in user secrets to simplify
  application connection string management and align with DNS-based connection
  best practices ([#7852](https://github.com/cloudnative-pg/cloudnative-pg/pull/7852)).

- Added the `systemID` field and related condition in the `Cluster` status to track
  the PostgreSQL system identifier.
  ([#7717](https://github.com/cloudnative-pg/cloudnative-pg/pull/7717)).

### Fixes

- Added a mutex in the connection pooler to protect concurrent access to the
  connections map, improving stability in high-concurrency environments
  ([#7804](https://github.com/cloudnative-pg/cloudnative-pg/pull/7804)).

- Fixed replica cluster instance ordering by correctly detecting the designated
  primary, improving replica cluster stability and switchover operations
  ([#8108](https://github.com/cloudnative-pg/cloudnative-pg/pull/8108)).

- Added support for reconciling `VolumeAttributesClass` for PVCs, enhancing
  storage compatibility and lifecycle management
  ([#7885](https://github.com/cloudnative-pg/cloudnative-pg/pull/7885)).

- Made the internal webserver routines non-blocking to improve responsiveness
  under load ([#8071](https://github.com/cloudnative-pg/cloudnative-pg/pull/8071)).

- Fixed an issue where the `ensureReplicationClientLeafCertificate` error did
  not display the correct `secretName` in the not found message
  ([#8086](https://github.com/cloudnative-pg/cloudnative-pg/pull/8086)).

- Prevented invalid `ALTER SUBSCRIPTION` statements by updating only
  PostgreSQL‑supported parameters; unsupported options like `copy_data` are
  ignored to avoid reconciliation failures
  ([7844](https://github.com/cloudnative-pg/cloudnative-pg/pull/7844)).

- Fixed an issue where the `bootstrap-controller` in the connection pooler did
  not apply `resources` settings correctly
  ([#7922](https://github.com/cloudnative-pg/cloudnative-pg/pull/7922)).

- Ensured online backups fail cleanly if the `targetPod` becomes unhealthy
  during backup, preventing partial or misleading backups
  ([#7944](https://github.com/cloudnative-pg/cloudnative-pg/pull/7944)).

- Ensured the Backup resource status is set properly after a failure, improving
  observability and scripting reliability
  ([#7898](https://github.com/cloudnative-pg/cloudnative-pg/pull/7898)).

## Version 1.25.2

**Release date:** May 23, 2025

### Important Changes

- **CloudNativePG is now officially a CNCF project**: CloudNativePG has been
  accepted into the Cloud Native Computing Foundation (CNCF), marking a
  significant milestone in its evolution. As part of this transition, the project
  is now governed under **CloudNativePG, a Series of LF Projects, LLC**, ensuring
  long-term sustainability and community-driven innovation. (#7203)

### Enhancements

- Added the `KUBERNETES_CLUSTER_DOMAIN` configuration option to the operator,
  allowing users to specify the domain suffix for fully qualified domain names
  (FQDNs) generated within the Kubernetes cluster. If not set, it defaults to
  `cluster.local`. (#6989) <!-- no 1.22 -->

- Implemented the `cnpg.io/validation` annotation, enabling users to disable
  the validation webhook on CloudNativePG-managed resources. Use with caution,
  as this allows unrestricted changes. (#7196)

- Added support for collecting `pg_stat_wal` metrics in PostgreSQL 18. (#7005)

- Added support for LZ4, XZ, and Zstandard compression methods when archiving
  WAL files via Barman Cloud (*deprecated*). (#7151)

- CloudNativePG Interface (CNPG-I):

  - A plugin can now trigger instance rollouts by implementing the `EVALUATE`
    verb, ensuring that plugin-induced changes are properly reconciled. (#7126) <!-- no 1.24 1.22 -->

  - Introduced support for WAL recovery via CNPG-I plugins during snapshot
    restore. (#7284) <!-- no 1.24 and 1.22 -->

### Security

- Set `imagePullPolicy` to `Always` for the operator deployment to ensure that
  images are always pulled from the registry, reducing the risk of using
  outdated or potentially unsafe local images. (#7250)

### Fixes

- Fixed native replication slot synchronization and logical replication
  failover for PostgreSQL 17 by appending the `dbname` parameter to
  `primary_conninfo` in replica configurations (#7298).

- Fixed a regression in WAL restore operations that prevented fallback to the
  in-tree `barmanObjectStore` configuration defined in the `externalCluster`
  source when a plugin failed to locate a WAL file (#7507). <!-- no 1.24 1.22 -->

- Improved backup efficiency by introducing a fail-fast mechanism in WAL
  archiving, allowing quicker detection of unexpected primary demotion and
  avoiding unnecessary retries (#7483).

- Fixed an off-by-one error in parallel WAL archiving that could cause one
  extra worker process to be spawned beyond the requested number (#7389).

- Resolved a race condition that caused the operator to perform two switchovers
  when updating the PostgreSQL configuration. (#6991)

- Corrected the `PodMonitor` configuration by adjusting the `matchLabels` scope
  for the targeted pooler and cluster pods. Previously, the `matchLabels` were
  too broad, inadvertently inheriting labels from the cluster and leading to data
  collection from unintended targets. (#7063)

- Added a webhook warning for clusters with a missing unit (e.g., MB, GB) in
  the `shared_buffers` configuration. This will become an error in future
  releases. Users should update their configurations to include explicit units
  (e.g., `512MB` instead of `512`). (#7160)

- Treated timeout errors during volume snapshot creation as retryable to
  prevent unnecessary backup failures. (#7010) <!-- no 1.24 1.22 -->

- Moved the defaulting logic for `.spec.postgresql.synchronous.dataDurability`
  from the CRD to the webhook to avoid UI issues with OLM. (#7600) <!-- no 1.24 1.22 -->

- CloudNativePG Interface (CNPG-I):

  - Implemented automatic reloading of TLS certificates for plugins when they
    change. (#7029) <!-- no 1.22 -->

  - Ensured the operator properly closes the plugin connection when
    performing a backup using the plugin. (#7095, #7096) <!-- no 1.22 -->

  - Improved performance and resilience of CNPG-I by removing timeouts for local
    plugin operations, avoiding failures during longer backup or WAL archiving
    executions (#7496). <!-- no 1.22 -->

- `cnpg` plugin:

  - Increased the buffer size in the `logs pretty` command to better handle
    larger log output (#7281). <!-- no 1.24 1.22 -->

  - Ensured the `plugin-name` parameter is required for plugin-based backups
    and disallowed for non-plugin backup methods (#7506). <!-- no 1.24 1.22 -->

  - Ensured that the primary Pod is recreated during an imperative restart when
    `primaryUpdateMethod` is set to `restart`, aligning its definition with the
    replicas. (#7122)

### Changes

- Updated the default PostgreSQL version to 17.5 for new cluster
  definitions. (#7556)

- Updated the default PgBouncer version to **1.24.1** for new `Pooler`
  deployments (#7399).

## Version 1.25.1

**Release Date:** February 28, 2025

### Enhancements

- Introduced a startup probe for the operator to enhance reliability and
  prevent premature liveness probe failures during initialization. (#7008)
- Added support for using the `-r` service with the Pooler. (#6868)
- Introduced an optional `--ttl` flag for the `pgbench` plugin, enabling
  automatic deletion of completed jobs after a user-defined duration. (#6701)
- Marked known error messages from the Azure CSI Driver for volume snapshots as
  retryable, improving resilience. (#6906)
- Updated the default PostgreSQL version to 17.4 for new cluster
  definitions. (#6960)

### Security

- The operator image build process has been enhanced to strengthen
  security and transparency. Images are now signed with `cosign`, and
  OCI attestations are generated, incorporating the Software Bill of
  Materials (SBOM) and provenance data. Additionally, OCI annotations
  have been added to improve traceability and ensure the integrity of
  the images.

### Bug Fixes

- Fixed inconsistent behavior in default probe knob values when `.spec.probes`
  is defined, ensuring users can override all settings, including
  `failureThreshold`. If unspecified in the startup probe, `failureThreshold` is
  now correctly derived from `.spec.startupDelay / periodSeconds` (default: `10`,
  now overridable). The same logic applies to liveness probes via
  `.spec.livenessProbeTimeout`. (#6656)
- Managed service ports now take precedence over default operator-defined
  ports. (#6474)
- Fixed an issue where WAL metrics were unavailable after an instance restart
  until a configuration change was applied. (#6816)
- Fixed an issue in monolithic database import where role import was skipped if
  no roles were specified. (#6646)
- Added support for new metrics introduced in PgBouncer 1.24. (#6630)
- Resolved an issue where `Database`, `Publication`, and `Subscription` CRDs
  became stuck in `cluster resource has been deleted, skipping reconciliation`
  after cluster rehydration. This patch forces `status.observedGeneration` to
  zero, ensuring proper reconciliation. (#6607) <!-- 1.25 only -->
- Improved handling of replication-sensitive parameter reductions by ensuring
  timely reconciliation after primary server restarts. (#6440)
- Introduced a new `isWALArchiver` flag in the CNPG-I plugin configuration,
  allowing users to designate a plugin as a WAL archiver. This enables seamless
  migration from in-tree Barman Cloud support to the plugin while maintaining WAL
  archive consistency. (#6593)
- Ensured `override.conf` is consistently included in `postgresql.conf` during
  replica cluster bootstrapping, preventing replication failures due to missing
  configuration settings. (#6808)
- Ensured `override.conf` is correctly initialized before invoking `pg_rewind`
  to prevent failures during primary role changes. (#6670)
- Enhanced webhook responses to return both warnings and errors when
  applicable, improving diagnostic accuracy. (#6579)
- Ensured the operator version is correctly reconciled. (#6496)
- Improved PostgreSQL version detection by using a more precise check of the
  data directory. (#6659)
- Volume Snapshot Backups:
    - Fixed an issue where unused backup connections were not properly cleaned
      up. (#6882)
    - Ensured the instance manager closes stale PostgreSQL connections left by
      failed volume snapshot backups. (#6879)
    - Prevented the operator from starting a new volume snapshot backup while
      another is already in progress. (#6890)
- `cnpg` plugin:
    - Restored functionality of the `promote` plugin command. (#6476)
    - Enhanced `kubectl cnpg report --logs <cluster>` to collect logs from all
      containers, including sidecars. (#6636)
    - Ensured `pgbench` jobs can run when a `Cluster` uses an `ImageCatalog`.
      (#6868)

### Technical Enhancements

- Added support for Kubernetes `client-gen`, enabling automated generation of
  Go clients for all CloudNativePG CRDs. (#6695)

## Version 1.25.0

**Release Date:** December 23, 2024

### Features

- **Declarative Database Management**: Introduce the `Database` Custom Resource
  Definition (CRD), enabling users to create and manage PostgreSQL databases
  declaratively within a cluster. (#5325)

- **Logical Replication Management**: Add `Publication` and `Subscription` CRDs
  for declarative management of PostgreSQL logical replication. These simplify
  replication setup and facilitate online migrations to CloudNativePG. (#5329)

- **Experimental Support for CNPG-I**: Introducing CNPG-I (CloudNativePG
  Interface), a standardized framework designed to extend CloudNativePG
  functionality through third-party plugins and foster the growth of the CNPG
  ecosystem.
  The [Barman Cloud Plugin](https://github.com/cloudnative-pg/plugin-barman-cloud) serves as a live
  example, illustrating how plugins can be developed to enhance backup and
  recovery workflows. Although CNPG-I support is currently experimental, it
  offers a powerful approach to extending CloudNativePG without modifying the
  operator’s core code—akin to PostgreSQL extensions. We welcome community
  feedback and contributions to shape this exciting new capability.

### Enhancements

- Add the `dataDurability` option to the `.spec.postgresql.synchronous` stanza,
  allowing users to choose between `required` (default) or `preferred`
  durability in synchronous replication. (#5878)
- Enable customization of startup, liveness, and readiness probes through the
  `.spec.probes` stanza. (#6266)
- Support additional `pg_dump` and `pg_restore` options to enhance database
  import flexibility. (#6214)
- Add support for `maxConcurrentReconciles` in the CloudNativePG controller and
  set the default to 10, improving the operator's ability to efficiently manage
  larger deployments out of the box. (#5678)
- Add the `cnpg.io/userType` label to secrets generated for predefined users,
  specifically `superuser` and `app`. (#4392)
- Improved validation for the `spec.schedule` field in ScheduledBackups,
  raising warnings for potential misconfigurations. (#5396)
- `cnpg` plugin:
    - Enhance the `backup` command to support plugins. (#6045)
    - Honor the `User-Agent` header in HTTP requests with the API server. (#6153)

### Bug Fixes

- Ensure the former primary flushes its WAL file queue to the archive before
  re-synchronizing as a replica, reducing recovery times and enhancing data
  consistency during failovers. (#6141)
- Clean the WAL volume along with the `PGDATA` volume during bootstrap. (#6265)
- Update the operator to set the cluster phase to `Unrecoverable` when
  all previously generated `PersistentVolumeClaims` are missing. (#6170)
- Fix the parsing of the `synchronous_standby_names` GUC when
  `.spec.postgresql.synchronous.method` is set to `first`. (#5955)
- Resolved a potential race condition when patching certain conditions
  in CRD statuses, improving reliability in concurrent updates. (#6328)
- Correct role changes to apply at the transaction level instead of the
  database context. (#6064)
- Remove the `primary_slot_name` definition from the `override.conf` file on
  the primary to ensure it is always empty. (#6219)
- Configure libpq environment variables, including `PGHOST`, in PgBouncer pods
  to enable seamless access to the `pgbouncer` virtual database using `psql`
  from within the container. (#6247)
- Remove unnecessary updates to the Cluster status when verifying changes in
  the image catalog. (#6277)
- Prevent panic during recovery from an external server without proper backup
  configuration. (#6300)
- Resolved a key collision issue in structured logs, where the name field was
  inconsistently used to log two distinct values. (#6324)
- Ensure proper quoting of the inRoles field in SQL statements to prevent
  syntax errors in generated SQL during role management. (#6346)
- `cnpg` plugin:
    - Ensure the `kubectl` context is properly passed in the `psql` command. (#6257)
    - Avoid displaying physical backups block when empty with `status` command. (#5998)

### Supported Versions

- **Kubernetes**: 1.32, 1.31, 1.30, and 1.29
- **PostgreSQL**: 17, 16, 15, 14, and 13
    - Default image: PostgreSQL 17.2
    - Officially dropped support for PostgreSQL 12
    - PostgreSQL 13 support ends on November 12, 2025
