Minor documentation error regarding streaming replication protocol

From: Brar Piening <brar(at)gmx(dot)de>
To: pgsql-hackers(at)lists(dot)postgresql(dot)org
Subject: Minor documentation error regarding streaming replication protocol
Date: 2020-09-13 20:25:01
Message-ID: 6a1b9cd9-17e3-df67-be55-86102af6bdf5@gmx.de
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

While implementing streaming replication client functionality for Npgsql
I stumbled upon a minor documentation error at
https://www.postgresql.org/docs/current/protocol-replication.html

The "content" return value for the TIMELINE_HISTORYcommand is advertised
as bytea while it is in fact raw ASCII bytes.

How did I find out?
Since the value I get doesn't start with a "\x" and contains ascii text,
although I've bytea_outputset to hex, I first thought that the streaming
replication protocol simply doesn't honor bytea_output, but then I
realized that I also get unencoded tabs and newlines which wouldn't be
possible if the value woud be passed through byteaout.

This is certainly a minor problem since the timeline history file only
contains generated strings that are ASCII-only, so just using the
unencoded bytes is actually easier than decoding bytea.
OTOH it did cost me a few hours (writing a bytea decoder and figuring
out why it doesn't work by looking at varlena.c and proving the docs
wrong) so I want to point this out here since it is possibly an
unintended behavior or at least a documentation error.
Also I'm wary of taking dependency on an undocumented implementation
detail that could possibly change at any point.

Regards,
Brar

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Brar Piening 2020-09-13 20:33:36 Re: Minor documentation error regarding streaming replication protocol
Previous Message Tom Lane 2020-09-13 19:47:51 Gripes about walsender command processing