Thread: Enhancing protocol.sgml

In libpq.sgml following is stated:

        Before <productname>PostgreSQL</productname> protocol 3.0, it was necessary
        for the application to explicitly send the two characters
        <literal>\.</literal> as a final line to indicate to the server that it had
        finished sending <command>COPY</command> data.  While this still works, it is deprecated and the
        special meaning of <literal>\.</literal> can be expected to be removed in a
        future release.  It is sufficient to call <function>PQendcopy</function> after
        having sent the actual data.

I think this should be mentioned in protocol.sgml as well. Developers
who wish to develop programs that understands frontend/backend
protocol should be able to focus on protocol.sgml. Attached is a patch
for this.

Best regards,
--
Tatsuo Ishii
SRA OSS, Inc. Japan
English: http://www.sraoss.co.jp/index_en.php
Japanese:http://www.sraoss.co.jp
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 46d7e19..a98e4af 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1154,6 +1154,20 @@ SELCT 1/0;
     (if successful) or ErrorResponse (if not).
    </para>
 
+   <note>
+     <para>
+       Before <productname>PostgreSQL</productname> protocol 3.0, it was necessary
+       for the application to explicitly send the two characters
+       <literal>\.</literal> as a final line to indicate to the server that it
+       had finished sending <command>COPY</command> data.  Programs
+       implementing <command>COPY</command> in protocol 3.0
+       including <productname>PostgreSQL</productname> need to check and
+       ignore
+       <literal>\.</literal> just before COPYDone message for backward
+       compatibility sake. This requirement may be removed in the future.
+     </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

Hi Bradley,

Thank your for your follow up. Your patch looks good to me.

Can you please re-send your message in pgsql-hackers attaching to this thread?
https://www.postgresql.org/message-id/flat/20180730.080748.1152436144966943439.t-ishii@sraoss.co.jp

I have registered the thread in CommitFest:
https://commitfest.postgresql.org/19/1738/

Unfortunately CommitFest app does not allow to handle emails other
than posted to pgsql-hackers. So I decided to post to pgsql-hackers
after posting to pgsql-docs.

Best regards,
--
Tatsuo Ishii
SRA OSS, Inc. Japan
English: http://www.sraoss.co.jp/index_en.php
Japanese:http://www.sraoss.co.jp

From: "Bradley DeJong" <bpd0018@gmail.com>
Subject: Re: Enhancing protocol.sgml
Date: Fri, 24 Aug 2018 15:43:28 +0000
Message-ID: <embf269241-6c21-44d2-8c0e-629656d3b112@dolphin>

> 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.