max_replication_slots

Definition PG 18 manual

Specifies the maximum number of replication slots (see Section 26.2.6) that the server can support. The default is 10. This parameter can only be set at server start. Setting it to a lower value than the number of currently existing replication slots will prevent the server from starting. Also, wal_level must be set to replica or higher to allow replication slots to be used.

How it works

PostgreSQL allocates replication-slot control capacity at server start. Physical slots can reserve WAL for standbys, while logical slots can reserve both WAL and catalog visibility information for decoding consumers.

The setting limits slot objects, not active WAL-sender connections; max_wal_senders is a separate limit. Slot use also requires wal_level = replica or higher. Reducing the setting below the number of existing slots prevents the server from starting.

An unused slot is not harmless merely because it has no active process. A persistent inactive slot can retain WAL, and a logical slot can hold catalog_xmin, so slot inventory and consumer lifecycle are as important as the numerical ceiling.

Operational considerations

Confusing the slot limit with max_wal_senders, which limits concurrent sender processes.

Lowering the value below the current slot count and making PostgreSQL fail to start.

Assuming inactive slots cannot retain WAL or catalog row versions.

Raising the ceiling without monitoring restart_lsn, catalog_xmin, and consumer health.

Creating permanent slots during experiments and never dropping them.

Workload guidance

OLAP: Allow for logical consumers and migration jobs, but remember that high-WAL batch periods magnify the cost of any abandoned slot. Monitor restart_lsn and confirmed_flush_lsn before and during bulk work.

OLTP: Budget slots from named physical standbys, logical subscriptions, CDC consumers, backup or migration tools, failover slots, and provisioning headroom. Keep a small reserve, but pair a larger ceiling with ownership, expiry, and lag monitoring.

SMALL: Keep the ceiling close to the real consumer count plus limited reserve. A large value does not itself retain WAL, but it makes unmanaged slot sprawl easier and can turn a small disk incident into an outage.