Thread: Enhancing protocol.sgml

Enhancing protocol.sgml

From
Tatsuo Ishii
Date:
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

Re: Enhancing protocol.sgml

From
"Bradley DeJong"
Date:
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.
Attachment

Re: Enhancing protocol.sgml

From
Tatsuo Ishii
Date:
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.