Logical replication workers

For DBAs and operators

Processes and how to see them

SELECT subname, worker_type, pid, leader_pid, relid::regclass,
       received_lsn, latest_end_lsn, last_msg_receipt_time
  FROM pg_stat_subscription;          -- worker_type: apply | table synchronization | parallel apply

SELECT srrelid::regclass, srsubstate FROM pg_subscription_rel;
-- i = init, d = copying data, f = copy finished, s = synchronized, r = ready

SELECT subname, apply_error_count, sync_error_count, confl_insert_exists
  FROM pg_stat_subscription_stats;    -- confl_* columns are new in 18

Lifecycle

1. The launcher is a background worker started at server start (it exists on every server that is not in recovery, even without subscriptions, as long as max_logical_replication_workers > 0; a standby starts it only after promotion). CREATE/ALTER SUBSCRIPTION wakes it; it starts an apply worker for every enabled subscription that has none.
2. The apply worker connects to the publisher (a walsender there) and runs START_REPLICATION SLOT … LOGICAL.
3. For tables in state i it starts up to max_sync_workers_per_subscription (default 2) tablesync workers. Each opens its own walsender, creates its own replication slot (pg_<subid>_sync_<relid>_<sysid>, dropped when the sync is done), runs COPY, then replays changes until it reaches the apply worker's position and hands the table over (s → r).
4. Large transactions are streamed by the publisher before they commit once they exceed logical_decoding_work_mem. With streaming = parallel (the default since PostgreSQL 18; before it was off) the leader passes them to a parallel apply worker through a shared memory queue, up to max_parallel_apply_workers_per_subscription (default 2). Without a free worker it writes the stream to a temporary file and applies it at commit.

Errors and restarts

A conflict (unique violation, missing permissions, missing table) makes the apply worker exit; the launcher restarts it after wal_retrieve_retry_interval (5s), it hits the same change again, and so on:

The CONTEXT line shows the origin, the remote transaction and its "finished at" LSN. Options: fix the data on the subscriber, ALTER SUBSCRIPTION … SKIP (lsn = '…'), or create the subscription with disable_on_error = true so it stops instead of looping. Meanwhile the publisher's slot retains WAL.

Sizing

• Apply + tablesync + parallel apply workers of all subscriptions share max_logical_replication_workers (restart to change). If it is too small, table syncs simply wait. Raise max_worker_processes with it: these are background workers, as are parallel query workers.
• Each subscription needs a replication origin: max_active_replication_origins (new in 18, previously max_replication_slots was used on the subscriber).
• The publisher needs one walsender (and slot) per apply worker plus one per running tablesync.
• Killing an apply worker with pg_terminate_backend() just makes the launcher start a new one; a SIGKILL causes a crash restart of the subscriber.