Что такое transaction ID wraparound и почему autovacuum не должен отставать?

Пороги и аварийная остановка

-- Текущие параметры
SHOW autovacuum_freeze_max_age;  -- 200 000 000 по умолчанию
SHOW vacuum_freeze_min_age;      -- 50 000 000
SHOW vacuum_freeze_table_age;    -- 150 000 000

-- Расстояние до wraparound для каждой таблицы
SELECT
  schemaname,
  relname,
  age(relfrozenxid) AS xid_age,
  2000000000 - age(relfrozenxid) AS xids_until_wraparound
FROM pg_class
JOIN pg_namespace ON pg_namespace.oid = relnamespace
WHERE relkind = 'r'
ORDER BY age(relfrozenxid) DESC
LIMIT 20;

-- На уровне базы данных
SELECT datname, age(datfrozenxid) AS db_age
FROM pg_database
ORDER BY age(datfrozenxid) DESC;

Когда age(relfrozenxid) достигает autovacuum_freeze_max_age (200M), PostgreSQL принудительно запускает агрессивный VACUUM, который игнорирует cost_delay и обходит всю таблицу. При достижении 1.6 миллиарда XID PostgreSQL переходит в read-only режим и пишет в журнал:

WARNING: database with OID 12345 must be vacuumed within 177009986 transactions
HINT: To avoid a database shutdown, execute a database-wide VACUUM in that database.

Что такое Transaction ID

Каждая транзакция в PostgreSQL получает уникальный 32-битный номер — Transaction ID (XID). XID присваивается в момент первой DML-операции (SELECT не получает XID, если не затрагивает данные). Все строки в таблицах хранят xmin (XID создавшей транзакции) и xmax (XID удалившей). На основе этих значений MVCC определяет видимость строк.

Проблема wraparound

32-битный счётчик вмещает ~4.2 миллиарда значений. Когда PostgreSQL достигает предела, он начинает новый цикл с нуля. Без специальной обработки «новые» XID оказались бы «меньше» старых, и старые строки стали бы невидимы — то есть все данные исчезли бы. Это катастрофическая авария.

PostgreSQL решает это через freeze: строки, которые «достаточно старые», получают специальный frozen XID (FrozenTransactionId = 2), который считается видимым во всех транзакциях навсегда. VACUUM выполняет заморозку.

Экстренное восстановление

-- Ручной агрессивный vacuum (заморозка)
VACUUM FREEZE VERBOSE mydb;

-- Или через утилиту (лучше не прерывать!)
-- vacuumdb --freeze --analyze --verbose mydb

-- Проверить прогресс
SELECT pid, relid::regclass, phase, heap_blks_scanned,
       heap_blks_vacuumed, index_vacuum_count, num_dead_tuples
FROM pg_stat_progress_vacuum;

Мониторинг и алерты

-- Алерт: таблицы с XID age > 150 миллионов
SELECT relname, age(relfrozenxid) AS xid_age
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE relkind = 'r'
  AND age(c.relfrozenxid) > 150000000
ORDER BY xid_age DESC;

Рекомендация: настройте мониторинг (Prometheus postgres_exporter метрика pg_stat_user_tables_n_dead_tup и pg_database_age) с предупреждением при age > 100M и критическим при > 150M.

Подводные камни

• Долгие транзакции блокируют freeze. VACUUM не может заморозить строки, если есть открытая транзакция с XID меньше vacuum_freeze_min_age. Одна «забытая» транзакция на часы может накапливать XID-долг.
• Агрессивный anti-wraparound vacuum нельзя остановить штатными средствами (он игнорирует autovacuum_vacuum_cost_delay). Он может неожиданно нагрузить I/O в пиковые часы.
• TOAST-таблицы тоже стареют. У каждой таблицы с JSONB/text есть TOAST, у неё свой relfrozenxid. Мониторьте не только основные таблицы.
• Нет мониторинга = внезапный read-only. Без алертов на XID age кластер уходит в read-only без предупреждения в рабочее время.
• Репликация не помогает. Wraparound — проблема каждого кластера независимо. Реплика может уйти в read-only даже раньше primary, если у неё был свой XID счётчик.
• vacuum_freeze_max_age нельзя бесконечно снижать. Уменьшение приводит к более частым агрессивным vacuum, что увеличивает I/O нагрузку и table bloat.

• Отвечать определением без production-сценария.
• Не называть runtime boundary, security boundary или failure mode.
• Игнорировать версию API, observability и тестовую проверку.

• Объясняет механизм своими словами и без выдуманных API.
• Называет реальные риски, диагностику и критерий корректности.
• Связывает ответ с текущей документацией и миграционными ограничениями.