max_sync_workers_per_subscription

Definition PG 18 manual

Maximum number of synchronization workers per subscription. This parameter controls the amount of parallelism of the initial data copy during the subscription initialization or when new tables are added.

Currently, there can be only one synchronization worker per table.

The synchronization workers are taken from the pool defined by max_logical_replication_workers.

The default value is 2. This parameter can only be set in the postgresql.conf file or on the server command line.

How it works

Maximum number of table synchronization workers per subscription. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

Initial table copies use synchronization workers up to this per-subscription ceiling. They share max_logical_replication_workers and max_worker_processes with apply workers, so the configured number is not a guaranteed concurrency level.

Monitor and change max_sync_workers_per_subscription together with max_logical_replication_workers, max_parallel_apply_workers_per_subscription, max_worker_processes. 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

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.

Failing over to a node that lacks the old primary's capacity or prerequisites.

Using infinite waits or WAL retention to hide a failed consumer.

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 max_sync_workers_per_subscription 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.