debug_logical_replication_streaming

Definition PG 18 manual

The allowed values are buffered and immediate. The default is buffered. This parameter is intended to be used to test logical decoding and replication of large transactions. The effect of debug_logical_replication_streaming is different for the publisher and subscriber:

On the publisher side, debug_logical_replication_streaming allows streaming or serializing changes immediately in logical decoding. When set to immediate, stream each change if the streaming option of CREATE SUBSCRIPTION is enabled, otherwise, serialize each change. When set to buffered, the decoding will stream or serialize changes when logical_decoding_work_mem is reached.

On the subscriber side, if the streaming option is set to parallel, debug_logical_replication_streaming can be used to direct the leader apply worker to send changes to the shared memory queue or to serialize all changes to the file. When set to buffered, the leader sends changes to parallel apply workers via a shared memory queue. When set to immediate, the leader serializes all changes to files and notifies the parallel apply workers to read and apply them at the end of the transaction.

How it works

debug_logical_replication_streaming forces large-transaction logical replication paths to stream or serialize immediately instead of waiting for normal buffering thresholds. buffered is the production behavior.

On a publisher, immediate streams each change when subscription streaming is enabled or serializes it otherwise, bypassing the logical_decoding_work_mem trigger. On a parallel subscriber, immediate forces file serialization instead of the normal shared-memory queue path.

The two sides therefore exercise different code paths. This is a regression and fault-reproduction control, not a latency or memory tuning shortcut. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Operational considerations

Leaving debug_logical_replication_streaming enabled after the bounded diagnostic or recovery task.

Running the experiment on the only copy of production data.

Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.

Treating a server that merely starts or completes a query as proof that data and behavior are correct.

Workload guidance

OLAP: Long analytical runs can amplify debug_logical_replication_streaming's debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.

OLTP: Do not tune production OLTP with debug_logical_replication_streaming. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.

SMALL: Keep debug_logical_replication_streaming at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation.