From fa025401a5bc487384b628099ca2c03e4962459d Mon Sep 17 00:00:00 2001 From: Thomas Munro Date: Fri, 25 May 2018 09:43:17 +1200 Subject: [PATCH 5/6] Add user-facing documentation for undo logs. Document the pg_stat_undo_log view, the wait events, and the storage layout on disk for undo logs. Author: Thomas Munro --- doc/src/sgml/config.sgml | 35 ++++++++++++ doc/src/sgml/monitoring.sgml | 107 ++++++++++++++++++++++++++++++++++- doc/src/sgml/storage.sgml | 56 ++++++++++++++++++ 3 files changed, 197 insertions(+), 1 deletion(-) diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index b60240ecfe7..3c6886c7f98 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -6687,6 +6687,41 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; + + undo_tablespaces (string) + + undo_tablespaces configuration parameter + + tablespacetemporary + + + + This variable specifies tablespaces in which to store undo data, when + undo-aware storage managers (initially "zheap") perform writes. + + + + The value is a list of names of tablespaces. When there is more than + one name in the list, PostgreSQL chooses an + arbitrary one. If the name doesn't correspond to an existing + tablespace, the next name is tried, and so on until all names have + been tried. If no valid tablespace is specified, an error is raised. + The validation of the name doesn't happen until the first attempt to + write undo data. + + + + The variable can only be changed before the first statement is + executed in a transaction. + + + + The default value is an empty string, which results in all temporary + objects being created in the default tablespace. + + + + check_function_bodies (boolean) diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index c278076e68d..8039b57c253 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -332,6 +332,14 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser + + pg_stat_undo_logspg_stat_undo_logs + One row for each undo log, showing current pointers, + transactions and backends. + See for details. + + + @@ -549,7 +557,6 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser into the kernel's handling of I/O. - <structname>pg_stat_activity</structname> View @@ -1638,6 +1645,30 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser TwophaseFileWriteWaiting for a write of a two phase state file. + + UndoCheckpointRead + Waiting for a read from an undo checkpoint file. + + + UndoCheckpointSync + Waiting for changes to an undo checkpoint file to reach stable storage. + + + UndoCheckpointWrite + Waiting for a write to an undo checkpoint file. + + + UndoFileRead + Waiting for a read from an undo data file. + + + UndoFileSync + Waiting for changes to an undo data file to reach stable storage. + + + UndoFileWrite + Waiting for a write to an undo data file. + WALBootstrapSync Waiting for WAL to reach stable storage during bootstrapping. @@ -1710,6 +1741,80 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i +
+ <structname>pg_stat_undo_logs</structname> View + + + + + Column + Type + Description + + + + + + log_number + oid + Identifier of this undo log + + + persistence + text + Persistence level of data stored in this undo log; one of + permanent, unlogged or + temporary. + + + tablespace + text + Tablespace that holds physical storage of this undo log. + + + discard + text + Location of the oldest data in this undo log. + + + insert + text + Location where the next data will be written in this undo + log. + + + end + text + Location one byte past the end of the allocated physical storage + backing this undo log. + + + xid + xid + Transaction currently attached to this undo log + for writing. + + + pid + integer + Process ID of the backend currently attached to this undo log + for writing. + + + +
+ + + The pg_stat_undo_logs view will have one row for + each undo log that exists. Undo logs are extents within a contiguous + addressing space that have their own head and tail pointers. + Each backend that has written undo data is associated with one or more undo + log, and is the only backend that is allowed to write data to those undo + logs. Backends can be associated with up to three undo logs at a time, + because different undo logs are used for the undo data associated with + permanent, unlogged and temporary relations. + + <structname>pg_stat_replication</structname> View diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml index 8ef2ac80106..a693182f72e 100644 --- a/doc/src/sgml/storage.sgml +++ b/doc/src/sgml/storage.sgml @@ -141,6 +141,11 @@ Item Subdirectory containing state files for prepared transactions + + pg_undo + Subdirectory containing undo log meta-data files + + pg_wal Subdirectory containing WAL (Write Ahead Log) files @@ -686,6 +691,57 @@ erased (they will be recreated automatically as needed). + + +Undo Logs + + + Undo Logs + + + +Undo logs hold data that is used for rolling back and for implementing +MVCC in access managers that are undo-aware (currently "zheap"). The storage +format of undo logs is optimized for reusing existing files. + + + +Undo data exists in a 64 bit address space broken up into numbered undo logs +that represent 1TB extents, for efficient management. The space is further +broken up into 1MB segment files, for physical storage. The name of each file +is the address of of the first byte in the file, with a period inserted after +the part that indicates the undo log number. + + + +Each undo log is created in a particular tablespace and stores data for a +particular persistence level. +Undo logs are global in the sense that they don't belong to any particular +database and may contain undo data from relations in any database. +Undo files backing undo logs in the default tablespace are stored under +PGDATA/base/undo, and for other +tablespaces under undo in the appropriate tablespace +directory. The system view can be +used to see the cluster's current list of undo logs along with their +tablespaces and persistence levels. + + + +Just as relations can have one of the three persistence levels permanent, +unlogged or temporary, the undo data that is generated by modifying them must +be stored in an undo log of the same persistence level. This enables the +undo data to be discarded at appropriate times along with the relations that +reference it. + + + +Undo log files contain standard page headers as described in the next section, +but the format of the rest of the page is determined by the undo-aware +access method that reads and writes it. + + + + Database Page Layout -- 2.17.0