Improve pg_stat_recovery documentation
Hi,
While trying the new pg_stat_recovery view in v19, I found that it can return
no rows even while recovery is in progress. This happened because the user
querying the view lacked the pg_read_all_stats privilege.
That behavior seems fine to me, but it isn't documented. So I'd like to propose
the attached patch, which documents that behavior and also makes a few other
documentation improvements:
- 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.
Thought?
Regards,
--
Fujii Masao
Attachments:
v1-0001-doc-Improve-pg_stat_recovery-documentation.patchapplication/octet-stream; name=v1-0001-doc-Improve-pg_stat_recovery-documentation.patchDownload+30-26
On Fri, Jul 17, 2026 at 11:10:08PM +0900, Fujii Masao wrote:
That behavior seems fine to me, but it isn't documented. So I'd like to propose
the attached patch, which documents that behavior and also makes a few other
documentation improvements:- Mention the view in high-availability.sgml as a way to monitor
recovery state and replay progress, alongside the existing recovery
information functions.
Why not.
- 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.
Yep, that's incorrect.
- 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.
Okay.
- Clarify that current_chunk_start_time is NULL until streaming WAL
has been received.
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.
[...]
- * 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
*/
True that this does not work under archive recovery, so specifying
that only only gets updated due to streaming replication sounds good
here.Looks good to me overall after reading the patch, thanks for the
suggestions.
--
Michael