From d43760b624b7cebc35e5f9c60d2e1439cbe9b220 Mon Sep 17 00:00:00 2001 From: Robert Haas Date: Mon, 23 Dec 2013 20:32:29 -0500 Subject: [PATCH] Revise documentation for new freezing method. Commit 37484ad2aacef5ec794f4dd3d5cf814475180a78 invalidated a good chunk of documentation, so patch it up to reflect the new state of play. Along the way, patch remaining documentation references to FrozenXID to say instead FrozenTransactionId, so that they match the way we actually spell it in the code. --- doc/src/sgml/config.sgml | 4 +- doc/src/sgml/maintenance.sgml | 56 +++++++++++++------------- src/backend/access/common/reloptions.c | 2 +- 3 files changed, 30 insertions(+), 32 deletions(-) diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 8f9f61d157..0f2f2bf925 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -5264,8 +5264,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; Specifies the cutoff age (in transactions) that VACUUM - should use to decide whether to replace transaction IDs with - FrozenXID while scanning a table. + should use to decide whether to freeze row versions + while scanning a table. The default is 50 million transactions. Although users can set this value anywhere from zero to one billion, VACUUM will silently limit the effective value to half diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml index fb94596224..324ed0e760 100644 --- a/doc/src/sgml/maintenance.sgml +++ b/doc/src/sgml/maintenance.sgml @@ -397,8 +397,12 @@ The reason that periodic vacuuming solves the problem is that - PostgreSQL reserves a special XID - as FrozenXID. This XID does not follow the normal XID + VACUUM will mark rows as frozen, indicating that + they were inserted by a transaction which committed sufficiently far in + the past that the effects of the inserting transaction is certain to be + visible, from an MVCC perspective, to all current and future transactions. + PostgreSQL reserves a special XID, + FrozenTransactionId, which does not follow the normal XID comparison rules and is always considered older than every normal XID. Normal XIDs are compared using modulo-232 arithmetic. This means @@ -410,20 +414,19 @@ the next two billion transactions, no matter which normal XID we are talking about. If the row version still exists after more than two billion transactions, it will suddenly appear to be in the future. To - prevent this, old row versions must be reassigned the XID - FrozenXID sometime before they reach the - two-billion-transactions-old mark. Once they are assigned this - special XID, they will appear to be in the past to all - normal transactions regardless of wraparound issues, and so such - row versions will be valid until deleted, no matter how long that is. - This reassignment of old XIDs is handled by VACUUM. + prevent this, frozen row versions are treated as if the inserting XID were + FrozenTransactionId, so that they will appear to be + in the past to all normal transactions regardless of wraparound + issues, and so such row versions will be valid until deleted, no matter + how long that is. - controls how old an XID value has to be before it's replaced with - FrozenXID. Larger values of this setting - preserve transactional information longer, while smaller values increase + controls how old an XID value has to be before its row version will be + frozen. Increasing this setting may avoid unnecessary work if the + rows that would otherwise be frozen will soon be modified again, + but decreasing this setting increases the number of transactions that can elapse before the table must be vacuumed again. @@ -431,8 +434,8 @@ VACUUM normally skips pages that don't have any dead row versions, but those pages might still have row versions with old XID - values. To ensure all old XIDs have been replaced by - FrozenXID, a scan of the whole table is needed. + values. To ensure all old row versions have been frozen, a + scan of the whole table is needed. controls when VACUUM does that: a whole table sweep is forced if the table hasn't been fully scanned for vacuum_freeze_table_age @@ -447,8 +450,8 @@ the time VACUUM last scanned the whole table. If it were to go unvacuumed for longer than that, data loss could result. To ensure that this does not happen, - autovacuum is invoked on any table that might contain XIDs older than the - age specified by the configuration parameter . (This will happen even if autovacuum is disabled.) @@ -504,30 +507,25 @@ One disadvantage of decreasing vacuum_freeze_min_age is that - it might cause VACUUM to do useless work: changing a table row's - XID to FrozenXID is a waste of time if the row is modified + it might cause VACUUM to do useless work: freezing a row + version is a waste of time if the row is modified soon thereafter (causing it to acquire a new XID). So the setting should be large enough that rows are not frozen until they are unlikely to change - any more. Another disadvantage of decreasing this setting is - that details about exactly which transaction inserted or modified a - row will be lost sooner. This information sometimes comes in handy, - particularly when trying to analyze what went wrong after a database - failure. For these two reasons, decreasing this setting is not - recommended except for completely static tables. + any more. - To track the age of the oldest XIDs in a database, + To track the age of the oldest unfrozen XIDs in a database, VACUUM stores XID statistics in the system tables pg_class and pg_database. In particular, the relfrozenxid column of a table's pg_class row contains the freeze cutoff XID that was used - by the last whole-table VACUUM for that table. All normal - XIDs older than this cutoff XID are guaranteed to have been replaced by - FrozenXID within the table. Similarly, + by the last whole-table VACUUM for that table. All rows + inserted by transactions with XIDs XIDs older than this cutoff XID are + guaranteed to have been frozen. Similarly, the datfrozenxid column of a database's - pg_database row is a lower bound on the normal XIDs + pg_database row is a lower bound on the unfrozen XIDs appearing in that database — it is just the minimum of the per-table relfrozenxid values within the database. A convenient way to diff --git a/src/backend/access/common/reloptions.c b/src/backend/access/common/reloptions.c index 31941e99ed..6530d71649 100644 --- a/src/backend/access/common/reloptions.c +++ b/src/backend/access/common/reloptions.c @@ -182,7 +182,7 @@ static relopt_int intRelOpts[] = { { "autovacuum_freeze_table_age", - "Age at which VACUUM should perform a full table sweep to replace old Xid values with FrozenXID", + "Age at which VACUUM should perform a full table sweep to freeze row versions", RELOPT_KIND_HEAP | RELOPT_KIND_TOAST }, -1, 0, 2000000000 }, -- 2.40.0