vacuum_freeze_table_age

Definition PG 18 manual

VACUUM performs an aggressive scan if the table's pg_class.relfrozenxid field has reached the age specified by this setting. An aggressive scan differs from a regular VACUUM in that it visits every page that might contain unfrozen XIDs or MXIDs, not just those that might contain dead tuples. The default is 150 million transactions. Although users can set this value anywhere from zero to two billion, VACUUM will silently limit the effective value to 95% of autovacuum_freeze_max_age, so that a periodic manual VACUUM has a chance to run before an anti-wraparound autovacuum is launched for the table. For more information see Section 24.1.5.

How it works

Sets the XID age at which VACUUM switches to an aggressive scan so it can advance a table’s relfrozenxid. It is a user-context setting.

An aggressive XID scan visits every page not already all-frozen and freezes eligible XIDs. PostgreSQL caps the effective value at 95% of autovacuum_freeze_max_age, leaving room for manual maintenance before forced anti-wraparound autovacuum.

Monitor age(relfrozenxid) and age(datfrozenxid), not relminmxid. The separate vacuum_multixact_freeze_table_age controls MXID-driven aggressive scans.

Operational considerations

Monitoring relminmxid instead of the XID horizon relfrozenxid.

Setting a value above 95% of autovacuum_freeze_max_age and assuming PostgreSQL will use it unchanged.

Forcing aggressive scans too frequently on large mutable tables.

Waiting for forced anti-wraparound autovacuum instead of measuring routine full-scan completion time.

Workload guidance

OLAP: Schedule aggressive XID freezing for static or newly loaded partitions while I/O headroom is available; lowering the threshold can spread work across maintenance windows.

OLTP: Set an XID aggressive-scan threshold that routine maintenance can reach and complete before autovacuum_freeze_max_age. Confirm full-table scan time on the largest relations.

SMALL: Keep the default and watch the oldest relfrozenxid in every database. Setting zero forces aggressive behavior for every VACUUM and is rarely appropriate globally.