From 531f499508670b4690aa19b9ced12969e7a8f3f4 Mon Sep 17 00:00:00 2001 From: Fujii Masao Date: Fri, 17 Jul 2026 21:58:16 +0900 Subject: [PATCH v1] doc: Improve pg_stat_recovery documentation Improve the documentation for pg_stat_recovery in several ways: - Mention the view in high-availability.sgml as a way to monitor recovery state and replay progress, alongside the existing recovery information functions. - Clarify that the view returns at most one row, not exactly one row, and no rows to users who lack the pg_read_all_stats privilege. - Correct the description of last_replayed_end_lsn to clarify that it is the end LSN of the last replayed record plus one. - Document that replay_end_tli equals last_replayed_tli when no WAL record is currently being replayed. - Clarify that current_chunk_start_time is NULL until streaming WAL has been received. --- doc/src/sgml/high-availability.sgml | 13 ++++++++---- doc/src/sgml/monitoring.sgml | 33 +++++++++++++++++------------ src/include/access/xlogrecovery.h | 4 ++-- 3 files changed, 30 insertions(+), 20 deletions(-) diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index 6d9636bd125..fd338ab1540 100644 --- a/doc/src/sgml/high-availability.sgml +++ b/doc/src/sgml/high-availability.sgml @@ -920,7 +920,10 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass' pg_stat_wal_receiver view. A large difference between pg_last_wal_replay_lsn and the view's flushed_lsn indicates that WAL is being - received faster than it can be replayed. + received faster than it can be replayed. Recovery state and replay + progress can also be monitored via the + + pg_stat_recovery view. @@ -1801,9 +1804,11 @@ postgres=# WAIT FOR LSN '0/306EE20'; (In server versions before 14, the in_hot_standby parameter did not exist; a workable substitute method for older servers is SHOW transaction_read_only.) In addition, a set of - functions () allow users to - access information about the standby server. These allow you to write - programs that are aware of the current state of the database. These + functions () and the + + pg_stat_recovery view allow users to + access information about the standby server. These facilities allow you to + write programs that are aware of the current state of the database. They can be used to monitor the progress of recovery, or to allow you to write complex programs that restore the database to particular states. diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index d1a20d001e9..802cbe1d8e4 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -340,7 +340,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser pg_stat_recoverypg_stat_recovery - Only one row, showing statistics about the state of recovery. + At most one row, showing statistics about the recovery state. See pg_stat_recovery for details. @@ -1975,9 +1975,11 @@ description | Waiting for a newly initialized WAL file to reach durable storage - The pg_stat_recovery view will contain only + The pg_stat_recovery view will contain at most one row, showing statistics about the recovery state of the startup - process. This view returns no row when the server is not in recovery. + process. This view returns no rows when the server is not in recovery + or the user does not have privileges of the + pg_read_all_stats role. @@ -2019,8 +2021,8 @@ description | Waiting for a newly initialized WAL file to reach durable storage last_replayed_end_lsnpg_lsn - End write-ahead log location of the last successfully replayed - WAL record. + End write-ahead log location, plus one, of the last successfully + replayed WAL record. @@ -2049,18 +2051,20 @@ description | Waiting for a newly initialized WAL file to reach durable storage replay_end_tliinteger - Timeline of the WAL record currently being replayed. + Timeline of the WAL record currently being replayed. When no record + is being actively replayed, equals + last_replayed_tli. - recovery_last_xact_time timestamp with time zone - - - Timestamp of the last transaction commit or abort replayed during - recovery. This is the time at which the commit or abort WAL record - for that transaction was generated on the primary. + recovery_last_xact_time timestamp with time zone + + + Timestamp of the last transaction commit or abort record replayed + during recovery. This is the time at which the commit or abort WAL + record for that transaction was generated on the primary. @@ -2070,8 +2074,9 @@ description | Waiting for a newly initialized WAL file to reach durable storage Time when the startup process observed that replay had caught up - with the latest received WAL chunk. Used in recovery-conflict - timing and replay/apply-lag diagnostics. NULL if not yet + with the latest WAL chunk received from streaming replication. + Used in recovery-conflict timing and replay/apply-lag diagnostics. + NULL if streaming WAL has not yet been received or the time is not available. diff --git a/src/include/access/xlogrecovery.h b/src/include/access/xlogrecovery.h index ba7750dca0b..61877f9c45c 100644 --- a/src/include/access/xlogrecovery.h +++ b/src/include/access/xlogrecovery.h @@ -112,8 +112,8 @@ typedef struct XLogRecoveryCtlData TimestampTz recoveryLastXTime; /* - * timestamp of when we started replaying the current chunk of WAL data, - * only relevant for replication or archive recovery + * timestamp of when we caught up with the latest WAL chunk received from + * streaming replication */ TimestampTz currentChunkStartTime; /* Recovery pause state */ -- 2.55.0