From: Bradley DeJong <bpd0018@gmail.com>
To: Tatsuo Ishii <ishii@sraoss.co.jp>
To: pgsql-docs@postgresql.org
Subject: Re: Enhancing protocol.sgml
Date: Fri, 24 Aug 2018 15:43:28 +0000
Message-ID: <embf269241-6c21-44d2-8c0e-629656d3b112@dolphin> (raw)
In-Reply-To: <20180728.125153.1487613390757751788.t-ishii@sraoss.co.jp>
References: <20180728.125153.1487613390757751788.t-ishii@sraoss.co.jp>
On 2018-07-27, Tatsuo Ishii wrote ...
> ... I think this should be mentioned in protocol.sgml as well. ...
I agree. It is already mentioned as one of the differences between v2
and v3 but an implementer should not need to read that section if they
are only implementing v3. (I know I've never looked at it before.)
Using protocol.diff as a base, I changed the phrasing to be more
prescriptive for v3 protocol implementers (don't send a final line, be
prepared to receive a final line), changed passive voice to active voice
and fixed one COPYData -> CopyData capitalization.
I also called this out in the description of the CopyData message format
because that is where the termination line would be transmitted.
Attachments:protocol.v2.patch (application/octet-stream, 2.1K) downloaddiff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgmlindex f0b2145208..fdd9c5cf0c 100644--- a/doc/src/sgml/protocol.sgml+++ b/doc/src/sgml/protocol.sgml@@ -1154,6 +1154,22 @@ SELCT 1/0;
(if successful) or ErrorResponse (if not).
</para>
+ <note>+ <para>+ Version 2.0 of the <productname>PostgreSQL</productname> protocol+ requires the sender to terminate the <command>COPY</command> data stream+ with a final <literal>\.</literal> line. In the v3.0 protocol, use of+ the terminating line is deprecated and made optional. The 3.0+ protocol now encapsulates the data into CopyData messages and terminates+ the data stream with a CopyDone message. If the terminating line is+ present, it must appear immediately before the CopyDone message.+ Any code that fully implements version 3.0 of the copy-in/copy-out+ sub-protocol should not send the terminating line but must allow+ for the terminating line when receiving <command>COPY</command>+ data. The terminating line will be removed from a future protocol version.+ </para>+ </note>+
<para>
In the event of a backend-detected error during copy-in mode (including
receipt of a CopyFail message), the backend will issue an ErrorResponse
@@ -3928,7 +3944,11 @@ CopyData (F & B)
Data that forms part of a <command>COPY</command> data stream. Messages sent
from the backend will always correspond to single data rows,
but messages sent by frontends might divide the data stream
- arbitrarily.+ arbitrarily. The last CopyData message before CopyDone may contain an optional+ termination line containing <literal>\.</literal>. This termination line is+ a holdover from the V2.0 protocol. It is not part of the data stream and should+ be ignored. See the description of the <command>COPY</command> sub-protocol+ message flow for more detail.
</para>
</listitem>
</varlistentry>
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: bpd0018@gmail.com, ishii@sraoss.co.jp
Subject: Re: Enhancing protocol.sgml
In-Reply-To: <embf269241-6c21-44d2-8c0e-629656d3b112@dolphin>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox