Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitbd8d441

Browse files
committed
Second round of FE/BE protocol changes. Frontend->backend messages now
have length counts, and COPY IN data is packetized into messages.
1 parent54b38d2 commitbd8d441

File tree

24 files changed

+1321
-966
lines changed

24 files changed

+1321
-966
lines changed

‎doc/src/sgml/libpq.sgml‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.118 2003/04/17 22:26:00 tgl Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.119 2003/04/19 00:02:29 tgl Exp $
33
-->
44

55
<chapter id="libpq">
@@ -1749,9 +1749,10 @@ state will never end.
17491749
<term><function>PQflush</function></term>
17501750
<listitem>
17511751
<para>
1752-
Attempts to flush any data queued to the server,
1753-
returns 0 if successful (or if the send queue is empty) or <symbol>EOF</symbol> if it failed for
1754-
some reason.
1752+
Attempts to flush any data queued to the server.
1753+
Returns 0 if successful (or if the send queue is empty), -1 if it failed for
1754+
some reason, or 1 if it was unable to send all the data in the send queue yet
1755+
(this case can only occur if the connection is nonblocking).
17551756
<synopsis>
17561757
int PQflush(PGconn *conn);
17571758
</synopsis>

‎doc/src/sgml/protocol.sgml‎

Lines changed: 68 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/protocol.sgml,v 1.27 2003/04/16 20:53:38 tgl Exp $ -->
1+
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/protocol.sgml,v 1.28 2003/04/19 00:02:29 tgl Exp $ -->
22

33
<chapter id="protocol">
44
<title>Frontend/Backend Protocol</title>
@@ -819,8 +819,9 @@
819819
Copy-in mode (data transfer to the server) is initiated when the
820820
backend executes a <command>COPY FROM STDIN</> SQL statement. The backend
821821
sends a CopyInResponse message to the frontend. The frontend should
822-
then send zero or more CopyDataRow messages, one per row to be loaded.
823-
(For <command>COPY BINARY</>, send CopyBinaryRow messages instead.)
822+
then send zero or more CopyData messages, forming a stream of input
823+
data. (The message boundaries are not required to have anything to do
824+
with row boundaries, although that is often a reasonable choice.)
824825
The frontend can terminate the copy-in mode by sending either a CopyDone
825826
message (allowing successful termination) or a CopyFail message (which
826827
will cause the <command>COPY</> SQL statement to fail with an
@@ -833,37 +834,33 @@
833834
<para>
834835
In the event of a backend-detected error during copy-in mode (including
835836
receipt of a CopyFail message, or indeed any frontend message other than
836-
CopyDataRow, CopyBinaryRow, or CopyDone), the backend will issue an
837-
ErrorResponse
837+
CopyData or CopyDone), the backend will issue an ErrorResponse
838838
message. If the <command>COPY</> command was issued via an extended-query
839839
message, the backend will now discard frontend messages until a Sync
840840
message is received, then it will issue ReadyForQuery and return to normal
841841
processing. If the <command>COPY</> command was issued in a simple
842842
Query message, the rest of that message is discarded and ReadyForQuery
843-
is issued. In either case, any subsequent CopyDataRow, CopyBinaryRow,
844-
CopyDone, or CopyFail messages issued by the frontend will simply be
845-
dropped.
843+
is issued. In either case, any subsequent CopyData, CopyDone, or CopyFail
844+
messages issued by the frontend will simply be dropped.
846845
</para>
847846

848847
<para>
849848
Copy-out mode (data transfer from the server) is initiated when the
850849
backend executes a <command>COPY TO STDOUT</> SQL statement. The backend
851850
sends a CopyOutResponse message to the frontend, followed by
852-
zero or more CopyDataRow messages, one per row, followed by CopyDone.
853-
(For <command>COPY BINARY</>, CopyBinaryRow messages are sent instead.)
851+
zero or more CopyData messages (always one per row), followed by CopyDone.
854852
The backend then reverts to the command-processing mode it was
855853
in before the <command>COPY</> started, and sends CommandComplete.
856-
The frontend cannot abort
857-
the transfer (short of closing the connection), but it can discard
858-
unwanted CopyDataRow, CopyBinaryRow, and CopyDone messages.
854+
The frontend cannot abort the transfer (short of closing the connection),
855+
but it can discard unwanted CopyData and CopyDone messages.
859856
</para>
860857

861858
<para>
862859
In the event of a backend-detected error during copy-out mode,
863860
the backend will issue an ErrorResponse message and revert to normal
864861
processing. The frontend should treat receipt of ErrorResponse (or
865-
indeed any message type other thanCopyDataRow, CopyBinaryRow, or
866-
CopyDone) as terminatingthe copy-out mode.
862+
indeed any message type other thanCopyData or CopyDone) as terminating
863+
the copy-out mode.
867864
</para>
868865
</sect2>
869866

@@ -1157,7 +1154,9 @@ indicate that it may be sent by a frontend (F), a backend (B), or both
11571154
(F &amp; B).
11581155
Notice that although each message includes a byte count at the beginning,
11591156
the message format is defined so that the message end can be found without
1160-
reference to the byte count. This aids validity checking.
1157+
reference to the byte count. This aids validity checking. (The CopyData
1158+
message is an exception, because it forms part of a data stream; the contents
1159+
may not be interpretable on their own.)
11611160
</para>
11621161

11631162
<VariableList>
@@ -2002,83 +2001,7 @@ CommandComplete (B)
20022001

20032002
<VarListEntry>
20042003
<Term>
2005-
CopyBinaryRow (F &amp; B)
2006-
</Term>
2007-
<ListItem>
2008-
<Para>
2009-
<VariableList>
2010-
<VarListEntry>
2011-
<Term>
2012-
Byte1('b')
2013-
</Term>
2014-
<ListItem>
2015-
<Para>
2016-
Identifies the message as binary COPY data.
2017-
Note that the message body format is identical to the
2018-
<command>COPY BINARY</> file-format representation for
2019-
a single row of data.
2020-
</Para>
2021-
</ListItem>
2022-
</VarListEntry>
2023-
<VarListEntry>
2024-
<Term>
2025-
Int32
2026-
</Term>
2027-
<ListItem>
2028-
<Para>
2029-
Length of message contents in bytes, including self.
2030-
</Para>
2031-
</ListItem>
2032-
</VarListEntry>
2033-
<VarListEntry>
2034-
<Term>
2035-
Int16
2036-
</Term>
2037-
<ListItem>
2038-
<Para>
2039-
Specifies the number of fields in the row (can be zero).
2040-
</Para>
2041-
</ListItem>
2042-
</VarListEntry>
2043-
</VariableList>
2044-
Then, for each field, there is the following:
2045-
<VariableList>
2046-
<VarListEntry>
2047-
<Term>
2048-
Int16
2049-
</Term>
2050-
<ListItem>
2051-
<Para>
2052-
Zero if the field is null, otherwise the <varname>typlen</>
2053-
for the field datatype.
2054-
</Para>
2055-
</ListItem>
2056-
</VarListEntry>
2057-
<VarListEntry>
2058-
<Term>
2059-
Byte<Replaceable>n</Replaceable>
2060-
</Term>
2061-
<ListItem>
2062-
<Para>
2063-
The value of the field itself in binary format.
2064-
Omitted if the field is null.
2065-
<Replaceable>n</Replaceable> is the <varname>typlen</>
2066-
value if <varname>typlen</> is positive. If
2067-
<varname>typlen</> is -1 then the field value begins with
2068-
its own length as an Int32 (the length includes itself).
2069-
</Para>
2070-
</ListItem>
2071-
</VarListEntry>
2072-
</VariableList>
2073-
2074-
</Para>
2075-
</ListItem>
2076-
</VarListEntry>
2077-
2078-
2079-
<VarListEntry>
2080-
<Term>
2081-
CopyDataRow (F &amp; B)
2004+
CopyData (F &amp; B)
20822005
</Term>
20832006
<ListItem>
20842007
<Para>
@@ -2089,7 +2012,7 @@ CopyDataRow (F &amp; B)
20892012
</Term>
20902013
<ListItem>
20912014
<Para>
2092-
Identifies the message astextualCOPY data.
2015+
Identifies the message as COPY data.
20932016
</Para>
20942017
</ListItem>
20952018
</VarListEntry>
@@ -2105,12 +2028,14 @@ CopyDataRow (F &amp; B)
21052028
</VarListEntry>
21062029
<VarListEntry>
21072030
<Term>
2108-
String
2031+
Byte<Replaceable>n</Replaceable>
21092032
</Term>
21102033
<ListItem>
21112034
<Para>
2112-
The textual representation of a single row of table data.
2113-
It should end with a newline.
2035+
Data that forms part of a COPY datastream. Messages sent
2036+
from the backend will always correspond to single data rows,
2037+
but messages sent by frontends may divide the datastream
2038+
arbitrarily.
21142039
</Para>
21152040
</ListItem>
21162041
</VarListEntry>
@@ -2236,8 +2161,7 @@ CopyInResponse (B)
22362161
</Term>
22372162
<ListItem>
22382163
<Para>
2239-
0 for textual copy (CopyDataRow is expected), 1 for
2240-
binary copy (CopyBinaryRow is expected).
2164+
0 for textual copy, 1 for binary copy.
22412165
</Para>
22422166
</ListItem>
22432167
</VarListEntry>
@@ -2283,8 +2207,7 @@ CopyOutResponse (B)
22832207
</Term>
22842208
<ListItem>
22852209
<Para>
2286-
0 for textual copy (CopyDataRow will follow), 1 for
2287-
binary copy (CopyBinaryRow will follow).
2210+
0 for textual copy, 1 for binary copy.
22882211
</Para>
22892212
</ListItem>
22902213
</VarListEntry>
@@ -3606,8 +3529,9 @@ StartupMessage (F)
36063529
<ListItem>
36073530
<Para>
36083531
The protocol version number. The most significant 16 bits are
3609-
the major version number (3 for the format described here).
3610-
The least 16 significant bits are the minor version number.
3532+
the major version number (3 or more for the format described
3533+
here).
3534+
The least significant 16 bits are the minor version number.
36113535
</Para>
36123536
</ListItem>
36133537
</VarListEntry>
@@ -3654,17 +3578,18 @@ StartupMessage (F)
36543578
<ListItem>
36553579
<Para>
36563580
Command-line arguments for the backend. (This is
3657-
deprecated in favor of setting individualGUC
3581+
deprecated in favor of setting individualrun-time
36583582
parameters.)
36593583
</Para>
36603584
</ListItem>
36613585
</VarListEntry>
36623586
</VariableList>
36633587

3664-
In addition to the above, anyGUC parameter that can be
3588+
In addition to the above, anyrun-time parameter that can be
36653589
set at backend start time may be listed. Such settings
36663590
will be applied during backend start (after parsing the
3667-
command-line options if any).
3591+
command-line options if any). The values will act as
3592+
session defaults.
36683593
</Para>
36693594
</ListItem>
36703595
</VarListEntry>
@@ -3913,4 +3838,41 @@ not line breaks.
39133838
</sect1>
39143839

39153840

3841+
<Sect1 id="protocol-changes">
3842+
<Title>Summary of Changes since Protocol 2.0</Title>
3843+
3844+
<para>
3845+
This section provides a quick checklist of changes, for the benefit of
3846+
developers trying to update existing client libraries to protocol 3.0.
3847+
</para>
3848+
3849+
<para>
3850+
The initial startup packet uses a flexible list-of-strings format
3851+
instead of a fixed format. Notice that session default values for run-time
3852+
parameters can now be specified directly in the startup packet. (Actually,
3853+
you could do that before using the <literal>options</> field, but given the
3854+
limited width of <literal>options</> and the lack of any way to quote
3855+
whitespace in the values, it wasn't a very safe technique.)
3856+
</para>
3857+
3858+
<para>
3859+
All messages now have a length count immediately following the message type
3860+
byte (except for startup packets, which have no type byte). Also note that
3861+
PasswordMessage now has a type byte.
3862+
</para>
3863+
3864+
<para>
3865+
COPY data is now encapsulated into CopyData and CopyDone messages. There
3866+
is a well-defined way to recover from errors during COPY.
3867+
</para>
3868+
3869+
<note>
3870+
<para>
3871+
Additional changes will be documented as they are implemented.
3872+
</para>
3873+
</note>
3874+
3875+
</sect1>
3876+
3877+
39163878
</Chapter>

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp