PostgreSQL Role Transition Management#

CloudNativePG manages PostgreSQL promotion and demotion through the instance manager (running inside each pod) in coordination with the operator. The two core workflows are switchover (planned, operator-initiated) and failover (unplanned, triggered by primary loss). Both converge on the same instance-level primitives but take different orchestration paths.

Key Files#

Promotion (Replica → Primary)#

Promotion is performed by PromoteAndWait() which:

1. Runs pg_ctl promote -w to trigger PostgreSQL promotion.
2. Polls until standby.signal is removed from PGDATA (the canonical PostgreSQL signal that the instance is no longer a standby).
3. Issues a CHECKPOINT — required so that pg_rewind on the old primary can find a consistent divergence point.

Known gap: PromoteAndWait() does not call pg_switch_wal() after promotion. If the promotion LSN falls mid-segment, that WAL segment contains pages from two timelines. Backups whose redo location lands in this mixed segment will fail to restore. See issue #10422 for details and workaround.

Demotion (Primary → Replica)#

On an old primary that has been superseded, verifyPgDataCoherenceForPrimary() runs at startup and drives the full demotion sequence 1:

1. Wait for CurrentPrimary == TargetPrimary in cluster status — confirms the new primary is recognized.
2. Wait for the new primary to accept connections (WaitForPrimaryAvailable).
3. Clean up any stale PID file.
4. Set postgresql.auto.conf writable (mode 0600) so pg_rewind can write to it — it's normally locked to 0400 2.
5. Archive all pending WAL via ArchiveAllReadyWALs — prevents losing WAL before the rewind.
6. Run pg_rewind to realign the data directory with the new primary.
7. Call Demote() to finalize replica configuration.

Demote() is a thin wrapper that calls UpdateReplicaConfiguration(), which writes override.conf and creates standby.signal 3.

Configuration File Management#

CNPG uses two operator-managed config files alongside PostgreSQL's standard files:

override.conf#

Written by writePostgresOverrideConfFile(), this file always contains 4:

• restore_command — WAL restore via the instance manager
• recovery_target_timeline = latest
• primary_conninfo — connection string to the upstream primary
• primary_slot_name — HA replication slot name (when non-empty)

During pg_rewind, configurePostgresOverrideConfFileForRewind() replaces override.conf with a rewind-specific variant that passes --rewind to wal-restore, disabling WAL prefetching and end-of-stream detection. After a successful rewind, Demote() replaces it with the standard replica configuration 5.

postgresql.auto.conf#

PostgreSQL's ALTER SYSTEM writes go here. CNPG locks this file to read-only (0400) to prevent user-initiated ALTER SYSTEM calls from conflicting with operator-managed settings. Permissions are temporarily relaxed to 0600 before pg_rewind runs, then restored by the reconciliation loop. This behavior is version-aware (active only for PostgreSQL < 17) 6.

Historical note: Before v1.21, replication settings were stored in postgresql.auto.conf. A migratePostgresAutoConfFile() function moved them to override.conf. This migration shim was removed in PR #9965 (merged Feb 2026) after all clusters had sufficient time to upgrade 7.

custom.conf (operator-managed GUCs)#

The operator writes cluster GUC settings to the custom configuration file (PostgresqlCustomConfigurationFile) via RefreshConfigurationFilesFromCluster() 8. This is separate from override.conf and is reconciled on every configuration change — it is not role-sensitive.

Replication Slot Persistence Across Role Changes#

HA Physical Slots (always enabled)#

CNPG creates a physical HA slot per cluster instance on the primary (named _cnpg_<instance>). On standbys, a background runner synchronizes slots from the primary: creating, updating (advancing restart_lsn), and deleting stale slots. Slots that hold xmin are specifically deleted from demoted-primaries to prevent VACUUM blocking.

The synchronizeReplicationSlots function was previously a first-error-aborts-all loop. Issue #11113 documented that a single failing slot blocked synchronization and cleanup of every other slot on a standby; a fix (PR #11119) changes this to continue processing remaining slots 9.

Logical Slot Synchronization (SynchronizeLogicalDecoding)#

When spec.replicationSlots.highAvailability.synchronizeLogicalDecoding: true is set, CNPG synchronizes logical replication slots across standbys (requires PostgreSQL 17+). The primary includes the synchronized slot names in synchronous_standby_names configuration generated in createPostgresqlConfiguration() 10.

Post-switchover orphan bug (issue #9969): After a switchover, the demoted primary retains logical slots with synced=false. PostgreSQL 17's slot sync worker refuses to overwrite these, so they accumulate WAL indefinitely. The proposed fix drops slots matching synced=false AND failover=true AND active=false. Workaround: manually drop the orphaned slot on the replica 11:

SELECT pg_drop_replication_slot(slot_name)
FROM pg_replication_slots
WHERE slot_name = '<SLOT_NAME>'
  AND synced = false
  AND pg_is_in_recovery();

Startup Coherence Check#

verifyPgDataCoherenceForPrimary() runs at every instance manager startup. It detects three states 12:

Known Issues Summary#