public inbox for [email protected]
help / color / mirror / Atom feedEnhancing protocol.sgml
3+ messages / 2 participants
[nested] [flat]
* Enhancing protocol.sgml
@ 2018-07-28 03:51 Tatsuo Ishii <[email protected]>
0 siblings, 1 reply; 3+ messages in thread
From: Tatsuo Ishii @ 2018-07-28 03:51 UTC (permalink / raw)
To: pgsql-docs
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
Attachments:
[text/x-patch] protocol.diff (1.0K, 2-protocol.diff)
download | inline diff:
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
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Enhancing protocol.sgml
@ 2018-08-24 15:43 Bradley DeJong <[email protected]>
parent: Tatsuo Ishii <[email protected]>
0 siblings, 1 reply; 3+ messages in thread
From: Bradley DeJong @ 2018-08-24 15:43 UTC (permalink / raw)
To: Tatsuo Ishii <[email protected]>; pgsql-docs
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:
[application/octet-stream] protocol.v2.patch (2.1K, 3-protocol.v2.patch)
download | inline diff:
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 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>
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Enhancing protocol.sgml
@ 2018-08-25 22:05 Tatsuo Ishii <[email protected]>
parent: Bradley DeJong <[email protected]>
0 siblings, 0 replies; 3+ messages in thread
From: Tatsuo Ishii @ 2018-08-25 22:05 UTC (permalink / raw)
To: [email protected]; +Cc: pgsql-docs
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/[email protected]
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" <[email protected]>
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.
^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2018-08-25 22:05 UTC | newest]
Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2018-07-28 03:51 Enhancing protocol.sgml Tatsuo Ishii <[email protected]>
2018-08-24 15:43 ` Bradley DeJong <[email protected]>
2018-08-25 22:05 ` Tatsuo Ishii <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox