Re: replication protocol documentation inconsistencies

Hi,

On 2014-05-21 07:29:53 -0400, Peter Eisentraut wrote:
> Looking at
> http://www.postgresql.org/docs/devel/static/protocol-replication.html
> under START_REPLICATION it goes
>
> """
> The payload of each CopyData message from server to the client contains
> a message of one of the following formats:
>
> If a slot's name is provided via slotname, it will be updated as
> replication progresses so that the server knows which WAL segments - and
> if hot_standby_feedback is on which transactions - are still needed by
> the standby.
>
> XLogData (B)
> ...
>
> Primary keepalive message (B)
> ...
> """
>
> That second paragraph was inserted recently and doesn't make sense
> there. It should be moved somewhere else.

Hm. I am not sure why it doesn't make sense there? It's about the SLOT
$slotname parameter to START_REPLICATION?

> More generally, it is weird that the message formats are described
> there, even though the rest of the protocol documentation only mentions
> the messages by name and then describes the formats later
> (http://www.postgresql.org/docs/devel/static/protocol-message-types.html
> and
> http://www.postgresql.org/docs/devel/static/protocol-message-formats.html).
> For example, the meaning of the "(B)" code isn't described until two
> sections later.
>

I am not sure that makes sense. These messages cannot be sent as
toplevel messages - they're just describing the contents of the CopyBoth
stream after START_REPLICATION has begun. It seems wierd to add these
'subprotocol' messages to the toplevel protocol description.

> I think the description of the details of the these messages should also
> be moved there. The CopyBothResponse, which is also used for
> replication only, is also listed among the "normal" message formats.

I think that's different because CopyBoth is a toplevel protocol issue.

Greetings,

Andres Freund

--
Andres Freund http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services