old_snapshot_threshold

Definition PG 16 manual

Sets the minimum amount of time that a query snapshot can be used without risk of a “snapshot too old” error occurring when using the snapshot. Data that has been dead for longer than this threshold is allowed to be vacuumed away. This can help prevent bloat in the face of snapshots which remain in use for a long time. To prevent incorrect results due to cleanup of data which would otherwise be visible to the snapshot, an error is generated when the snapshot is older than this threshold and the snapshot is used to read a page which has been modified since the snapshot was built.

If this value is specified without units, it is taken as minutes. A value of -1 (the default) disables this feature, effectively setting the snapshot age limit to infinity. This parameter can only be set at server start.

Useful values for production work probably range from a small number of hours to a few days. Small values (such as 0 or 1min) are only allowed because they may sometimes be useful for testing. While a setting as high as 60d is allowed, please note that in many workloads extreme bloat or transaction ID wraparound may occur in much shorter time frames.

When this feature is enabled, freed space at the end of a relation cannot be released to the operating system, since that could remove information needed to detect the “snapshot too old” condition. All space allocated to a relation remains associated with that relation for reuse only within that relation unless explicitly freed (for example, with VACUUM FULL).

This setting does not attempt to guarantee that an error will be generated under any particular circumstances. In fact, if the correct results can be generated from (for example) a cursor which has materialized a result set, no error will be generated even if the underlying rows in the referenced table have been vacuumed away. Some tables cannot safely be vacuumed early, and so will not be affected by this setting, such as system catalogs. For such tables this setting will neither reduce bloat nor create a possibility of a “snapshot too old” error on scanning.

How it works

old_snapshot_threshold, available through PG16 and removed in PG17, marked snapshots as too old after a configured time so page pruning could proceed more aggressively. A later read could fail with snapshot-too-old rather than return a historical page image.

It was not a transaction timeout: the transaction could continue until it touched data whose old versions had been removed. The feature required startup-time tracking overhead even before a failure appeared.

It did not replace vacuum discipline or prevent all bloat. Because the feature was removed, migration must not carry the parameter into PG17+ and applications must not depend on its error behavior. Its postmaster context fixes the value at server start; changing it requires a restart.

Operational considerations

Changing old_snapshot_threshold 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: Do not carry old_snapshot_threshold into a modern analytical cluster. Benchmark the supported current mechanisms instead of trying to emulate a removed implementation detail.

OLTP: Do not tune old_snapshot_threshold on current PostgreSQL: remove it from upgrade targets and use the current replacement behavior described above. Retain it only when reproducing the historical version.

SMALL: Delete old_snapshot_threshold during version migration; an unknown-parameter startup failure is more likely than a benefit. Historical test instances should keep the old upstream default.