subtransaction_buffers

Definition PG 18 manual

Specifies the amount of shared memory to use to cache the contents of pg_subtrans (see Table 66.1). If this value is specified without units, it is taken as blocks, that is BLCKSZ bytes, typically 8kB. The default value is 0, which requests shared_buffers/512 up to 1024 blocks, but not fewer than 16 blocks. This parameter can only be set at server start.

How it works

subtransaction_buffers allocates a dedicated shared buffer pool for pg_subtrans, which caches subtransaction parent mappings. This is real startup shared memory, not a planner estimate.

Zero is an automatic-sizing request: PostgreSQL derives shared_buffers/512 and clamps it between 16 and 1024 blocks. The unit is BLCKSZ blocks, normally 8kB.

A larger cache can reduce SLRU read/write churn for unusually heavy use of the underlying feature, but it permanently consumes shared memory and does not increase the feature's logical capacity. Its postmaster context fixes the value at server start; changing it requires a restart.

Operational considerations

Changing subtransaction_buffers without applying its documented unit and configuration context.

Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.

Assuming a configured value guarantees operating-system or storage behavior.

Failing to retest startup, failover, and workload latency after the change.

Workload guidance

OLAP: Analytical workload labels alone do not justify changing subtransaction_buffers; tune only when the underlying transaction-state facility, not table scans, is the measured bottleneck.

OLTP: Leave subtransaction_buffers at automatic or upstream sizing unless SLRU-specific I/O and contention prove this cache is undersized. A larger number consumes shared memory for the entire server lifetime.

SMALL: Keep subtransaction_buffers at its default on a small host. Moving scarce shared memory into an internal cache without direct evidence can reduce room for more valuable caches and processes.