From bd8d4417757b1f3edd9ef36897cf47fe96b6e37a Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sat, 19 Apr 2003 00:02:30 +0000 Subject: Second round of FE/BE protocol changes. Frontend->backend messages now have length counts, and COPY IN data is packetized into messages. --- doc/src/sgml/libpq.sgml | 9 +-- doc/src/sgml/protocol.sgml | 174 ++++++++++++++++++--------------------------- 2 files changed, 73 insertions(+), 110 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index a1f8d6b5f6b..7a7bb48ff39 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,5 +1,5 @@ @@ -1749,9 +1749,10 @@ state will never end. PQflush -Attempts to flush any data queued to the server, -returns 0 if successful (or if the send queue is empty) or EOF if it failed for -some reason. +Attempts to flush any data queued to the server. +Returns 0 if successful (or if the send queue is empty), -1 if it failed for +some reason, or 1 if it was unable to send all the data in the send queue yet +(this case can only occur if the connection is nonblocking). int PQflush(PGconn *conn); diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index bb25eb74b14..529baa1f31b 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1,4 +1,4 @@ - + Frontend/Backend Protocol @@ -819,8 +819,9 @@ Copy-in mode (data transfer to the server) is initiated when the backend executes a COPY FROM STDIN SQL statement. The backend sends a CopyInResponse message to the frontend. The frontend should - then send zero or more CopyDataRow messages, one per row to be loaded. - (For COPY BINARY, send CopyBinaryRow messages instead.) + then send zero or more CopyData messages, forming a stream of input + data. (The message boundaries are not required to have anything to do + with row boundaries, although that is often a reasonable choice.) The frontend can terminate the copy-in mode by sending either a CopyDone message (allowing successful termination) or a CopyFail message (which will cause the COPY SQL statement to fail with an @@ -833,37 +834,33 @@ In the event of a backend-detected error during copy-in mode (including receipt of a CopyFail message, or indeed any frontend message other than - CopyDataRow, CopyBinaryRow, or CopyDone), the backend will issue an - ErrorResponse + CopyData or CopyDone), the backend will issue an ErrorResponse message. If the COPY command was issued via an extended-query message, the backend will now discard frontend messages until a Sync message is received, then it will issue ReadyForQuery and return to normal processing. If the COPY command was issued in a simple Query message, the rest of that message is discarded and ReadyForQuery - is issued. In either case, any subsequent CopyDataRow, CopyBinaryRow, - CopyDone, or CopyFail messages issued by the frontend will simply be - dropped. + is issued. In either case, any subsequent CopyData, CopyDone, or CopyFail + messages issued by the frontend will simply be dropped. Copy-out mode (data transfer from the server) is initiated when the backend executes a COPY TO STDOUT SQL statement. The backend sends a CopyOutResponse message to the frontend, followed by - zero or more CopyDataRow messages, one per row, followed by CopyDone. - (For COPY BINARY, CopyBinaryRow messages are sent instead.) + zero or more CopyData messages (always one per row), followed by CopyDone. The backend then reverts to the command-processing mode it was in before the COPY started, and sends CommandComplete. - The frontend cannot abort - the transfer (short of closing the connection), but it can discard - unwanted CopyDataRow, CopyBinaryRow, and CopyDone messages. + The frontend cannot abort the transfer (short of closing the connection), + but it can discard unwanted CopyData and CopyDone messages. In the event of a backend-detected error during copy-out mode, the backend will issue an ErrorResponse message and revert to normal processing. The frontend should treat receipt of ErrorResponse (or - indeed any message type other than CopyDataRow, CopyBinaryRow, or - CopyDone) as terminating the copy-out mode. + indeed any message type other than CopyData or CopyDone) as terminating + the copy-out mode. @@ -1157,7 +1154,9 @@ indicate that it may be sent by a frontend (F), a backend (B), or both (F & B). Notice that although each message includes a byte count at the beginning, the message format is defined so that the message end can be found without -reference to the byte count. This aids validity checking. +reference to the byte count. This aids validity checking. (The CopyData +message is an exception, because it forms part of a data stream; the contents +may not be interpretable on their own.) @@ -2002,83 +2001,7 @@ CommandComplete (B) -CopyBinaryRow (F & B) - - - - - - - Byte1('b') - - - - Identifies the message as binary COPY data. - Note that the message body format is identical to the - COPY BINARY file-format representation for - a single row of data. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Int16 - - - - Specifies the number of fields in the row (can be zero). - - - - - Then, for each field, there is the following: - - - - Int16 - - - - Zero if the field is null, otherwise the typlen - for the field datatype. - - - - - - Byten - - - - The value of the field itself in binary format. - Omitted if the field is null. - n is the typlen - value if typlen is positive. If - typlen is -1 then the field value begins with - its own length as an Int32 (the length includes itself). - - - - - - - - - - - - -CopyDataRow (F & B) +CopyData (F & B) @@ -2089,7 +2012,7 @@ CopyDataRow (F & B) - Identifies the message as textual COPY data. + Identifies the message as COPY data. @@ -2105,12 +2028,14 @@ CopyDataRow (F & B) - String + Byten - The textual representation of a single row of table data. - It should end with a newline. + Data that forms part of a COPY datastream. Messages sent + from the backend will always correspond to single data rows, + but messages sent by frontends may divide the datastream + arbitrarily. @@ -2236,8 +2161,7 @@ CopyInResponse (B) - 0 for textual copy (CopyDataRow is expected), 1 for - binary copy (CopyBinaryRow is expected). + 0 for textual copy, 1 for binary copy. @@ -2283,8 +2207,7 @@ CopyOutResponse (B) - 0 for textual copy (CopyDataRow will follow), 1 for - binary copy (CopyBinaryRow will follow). + 0 for textual copy, 1 for binary copy. @@ -3606,8 +3529,9 @@ StartupMessage (F) The protocol version number. The most significant 16 bits are - the major version number (3 for the format described here). - The least 16 significant bits are the minor version number. + the major version number (3 or more for the format described + here). + The least significant 16 bits are the minor version number. @@ -3654,17 +3578,18 @@ StartupMessage (F) Command-line arguments for the backend. (This is - deprecated in favor of setting individual GUC + deprecated in favor of setting individual run-time parameters.) - In addition to the above, any GUC parameter that can be + In addition to the above, any run-time parameter that can be set at backend start time may be listed. Such settings will be applied during backend start (after parsing the - command-line options if any). + command-line options if any). The values will act as + session defaults. @@ -3913,4 +3838,41 @@ not line breaks. + +Summary of Changes since Protocol 2.0 + + +This section provides a quick checklist of changes, for the benefit of +developers trying to update existing client libraries to protocol 3.0. + + + +The initial startup packet uses a flexible list-of-strings format +instead of a fixed format. Notice that session default values for run-time +parameters can now be specified directly in the startup packet. (Actually, +you could do that before using the options field, but given the +limited width of options and the lack of any way to quote +whitespace in the values, it wasn't a very safe technique.) + + + +All messages now have a length count immediately following the message type +byte (except for startup packets, which have no type byte). Also note that +PasswordMessage now has a type byte. + + + +COPY data is now encapsulated into CopyData and CopyDone messages. There +is a well-defined way to recover from errors during COPY. + + + + +Additional changes will be documented as they are implemented. + + + + + + -- cgit v1.2.3