| From: | Ashutosh Sharma <ashu(dot)coek88(at)gmail(dot)com> |
|---|---|
| To: | PostgreSQL Hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org> |
| Subject: | pg_stat_replication docs incomplete for logical replication |
| Date: | 2026-06-11 05:07:56 |
| Message-ID: | CAE9k0Pn+grZ9cgiKdAB-h_AQBD_8Zsob2gD=p3aDV=e2g2Odrw@mail.gmail.com |
| Views: | Whole Thread | Raw Message | Download mbox | Resend email |
| Thread: | |
| Lists: | pgsql-hackers |
Hi,
I noticed that the documentation for the pg_stat_replication view does
not adequately cover logical replication. The current text only
mentions standby servers, leaving the behaviour of the LSN columns
undefined and potentially misleading for users of logical replication.
Specifically:
1. The view description refers only to "connected standby servers",
omitting logical subscribers, which also appear as rows in the view.
2. The LSN columns (sent_lsn, write_lsn, flush_lsn, replay_lsn) have
fundamentally different semantics for logical replication compared to
physical replication, but this is not documented anywhere.
The distinction matters because:
- sent_lsn for logical replication reflects publisher-side decoding
and output progress, not how far data has been delivered to the
subscriber.
- write_lsn, flush_lsn, and replay_lsn reflect progress reported by
the subscriber through replication status messages, and do not
guarantee that committed changes have been received, durably stored,
or made visible on the subscriber.
This can lead users to incorrectly assume that LSN values in this view
confirm end-to-end delivery of changes in a logical replication setup.
Proposed correction:
- Update the view description to mention logical subscribers alongside standbys.
- Add a paragraph clarifying the differing semantics of the LSN
columns for physical vs logical replication.
I have a patch ready for review if the approach looks acceptable.
Please have a look and let me know your thoughts.
--
With Regards,
Ashutosh Sharma.
| Attachment | Content-Type | Size |
|---|---|---|
| 0001-doc-clarify-pg_stat_replication-view-for-logical-rep.patch | application/octet-stream | 5.8 KB |
| From | Date | Subject | |
|---|---|---|---|
| Next Message | Dilip Kumar | 2026-06-11 05:13:51 | Re: Proposal: Conflict log history table for Logical Replication |
| Previous Message | Henson Choi | 2026-06-11 05:05:42 | Re: Row pattern recognition |