primary_slot_name

Definition PG 18 manual

Optionally specifies an existing replication slot to be used when connecting to the sending server via streaming replication to control resource removal on the upstream node (see Section 26.2.6). This parameter can only be set in the postgresql.conf file or on the server command line. If this parameter is changed while the WAL receiver process is running, that process is signaled to shut down and expected to restart with the new setting. This setting has no effect if primary_conninfo is not set or the server is not in standby mode.

How it works

Sets the name of the replication slot to use on the sending server. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

The receiver names an existing upstream physical slot so the sender retains WAL needed by this standby. It improves continuity across disconnects but transfers disk-retention risk to the primary and must match slot lifecycle during failover.

Monitor and change primary_slot_name together with wal_keep_segments, wal_keep_size, wal_segment_size. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Operational considerations

Creating a slot without monitoring restart_lsn and primary disk usage.

Dropping or reusing the slot during failover without proving consumer position.

Assuming a slot alone archives or backs up WAL.

Changing it on the wrong primary, standby, sender, or subscriber role.

Watching only configured bytes/time instead of actual lag, slot position, and worker state.

Workload guidance

OLAP: Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.

OLTP: Size primary_slot_name from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.

SMALL: Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.