Preventing Transaction ID Wraparound
Understand how PostgreSQL's 32-bit transaction IDs can wrap around, why aggressive vacuuming prevents it, and how to monitor and avoid the dreaded wraparound shutdown.
Preventing Transaction ID Wraparound is a free PostgreSQL Performance & Query Optimization lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the PostgreSQL Performance & Query Optimization learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
What is Transaction ID Wraparound?
PostgreSQL labels every row version with the transaction ID (XID) that created it. XIDs are 32-bit, so there are only about 4 billion of them. They are compared in a circular fashion, and if old rows are not frozen, the comparison can break.
Why It is Dangerous
If XIDs wrap before old rows are frozen, recent rows could appear to be in the future and become invisible. To protect your data, PostgreSQL will refuse new writes before that happens.
Freezing Rows
VACUUM marks very old, still-visible rows as frozen, meaning they are visible to all transactions forever. Frozen rows no longer depend on their original XID, so they are safe from wraparound.
The vacuum_freeze_min_age Setting
This controls how old a row's XID must be before VACUUM freezes it. Lower values freeze sooner; higher values defer work but increase wraparound risk.
SHOW vacuum_freeze_min_age;Autovacuum to the Rescue
When a table's oldest XID exceeds autovacuum_freeze_max_age, autovacuum triggers an anti-wraparound vacuum automatically, even if the table is otherwise idle.
SHOW autovacuum_freeze_max_age;Monitoring Database Age
Check how close each database is to wraparound by reading the age of its oldest unfrozen XID.
SELECT datname, age(datfrozenxid)
FROM pg_database
ORDER BY age(datfrozenxid) DESC;Monitoring Per-Table Age
Drill down to find the specific tables driving the age up. The one with the highest age is the next anti-wraparound target.
SELECT relname, age(relfrozenxid)
FROM pg_class
WHERE relkind = 'r'
ORDER BY age(relfrozenxid) DESC
LIMIT 10;The Warning Signs
The server log warns as you approach the limit:
- database must be vacuumed within N transactions
- Eventually the database goes read-only to protect itself
Never ignore these messages.
Manual Freeze
If a table is far behind, run a vacuum that freezes everything immediately rather than waiting for autovacuum.
VACUUM (FREEZE, VERBOSE) big_table;Best Practices
To stay safe:
- Keep autovacuum enabled and well-tuned
- Avoid extremely long-running transactions that pin the oldest XID
- Monitor
age(datfrozenxid)with alerts - Investigate any table that resists freezing
Estimating Time Until Trouble
You can roughly gauge headroom by comparing the oldest XID age against the ~2 billion safe limit. If a database is consistently climbing toward it, investigate what blocks freezing before alerts fire.
SELECT datname,
2000000000 - age(datfrozenxid) AS xids_left
FROM pg_database
ORDER BY xids_left ASC;Quick Check
Test your wraparound knowledge.
Recap
You learned wraparound prevention:
- 32-bit XIDs can wrap after ~4 billion transactions
- VACUUM freezes old rows to make them permanently visible
- Autovacuum runs anti-wraparound vacuums automatically
- Monitor
age(datfrozenxid)at database and table level - Avoid long transactions and heed the log warnings
Frequently asked questions
Is the “Preventing Transaction ID Wraparound” lesson free?
Yes — the full text of “Preventing Transaction ID Wraparound” is free to read here on the web, and the PostgreSQL Performance & Query Optimization course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the PostgreSQL Performance & Query Optimization course, upgrade to CoddyKit PRO.
What will I learn in “Preventing Transaction ID Wraparound”?
Understand how PostgreSQL's 32-bit transaction IDs can wrap around, why aggressive vacuuming prevents it, and how to monitor and avoid the dreaded wraparound shutdown. You practise PostgreSQL Performance & Query Optimization with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start PostgreSQL Performance & Query Optimization?
No prior experience is required. PostgreSQL Performance & Query Optimization on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Preventing Transaction ID Wraparound” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this PostgreSQL Performance & Query Optimization lesson?
Yes. Every PostgreSQL Performance & Query Optimization lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Understanding MVCC and VACUUM
- Autovacuum Configuration and Tuning
- Transaction Isolation Levels Impact
- Preventing Transaction ID Wraparound