From 26b237ffad0cba65f9781844d5d9a9c1e67c58a4 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Wed, 16 Apr 2003 20:53:38 +0000 Subject: [PATCH] Various clarifications; add a clear DRAFT marker; minor adjustments in some message types. In particular add text/binary flag to StartCopyIn and StartCopyOut, so that client library can know what is expected or forthcoming. --- doc/src/sgml/protocol.sgml | 100 ++++++++++++++++++++++++++----------- 1 file changed, 70 insertions(+), 30 deletions(-) diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 4906a71501..bb25eb74b1 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1,8 +1,16 @@ - + Frontend/Backend Protocol + + + This is currently a DRAFT description of FE/BE protocol + version 3.0. Details are still subject to change. + In particular, the representation of binary data is still under debate. + + + PostgreSQL uses a message-based protocol for communication between frontends and backends (clients and servers). @@ -504,11 +512,12 @@ - The response to a SELECT or FETCH query + The response to a SELECT, FETCH, or + SHOW query normally consists of RowDescription, zero or more DataRow or BinaryRow messages, and then CommandComplete. COPY to or from the frontend invokes special protocol - as described below. + as described in . All other query types normally produce only a CommandComplete message. @@ -524,7 +533,6 @@ If a completely empty (no contents other than whitespace) query string is received, the response is EmptyQueryResponse followed by ReadyForQuery. - (The need to specially distinguish this case is historical.) @@ -621,7 +629,10 @@ The possible responses to Execute are the same as those described above for queries issued via simple query protocol, except that Execute doesn't cause - ReadyForQuery to be issued. + ReadyForQuery to be issued. Also, the choice between text and binary + output (DataRow or BinaryRow messages) is determined by Execute's + format field, regardless of the command; the BINARY attribute + in cursor declarations is irrelevant when using this protocol. @@ -630,8 +641,11 @@ PortalSuspended message; the appearance of this message tells the frontend that another Execute should be issued against the same portal to complete the operation. The CommandComplete message indicating - completion of the source SELECT or FETCH command is not sent until - the command is completed. + completion of the source SQL command is not sent until + the portal's execution is completed. Therefore, an Execute phase is + always terminated by the appearance of exactly one of these messages: + CommandComplete, EmptyQueryResponse (if the portal was created from + an empty query string), ErrorResponse, or PortalSuspended. @@ -715,7 +729,16 @@ Function Call - + + + The Function Call sub-protocol is a legacy feature that is probably best + avoided in new code. Similar results can be accomplished by setting up + a prepared statement that does SELECT function($1, ...). + The Function Call cycle can then be replaced with Bind/Execute. + + + + A Function Call cycle is initiated by the frontend sending a FunctionCall message to the backend. The backend then sends one or more response messages depending on the results of the function @@ -724,7 +747,7 @@ function call. - + The possible response messages from the backend are: @@ -741,7 +764,9 @@ FunctionResultResponse - The function call was executed and returned a result. + The function call was executed and returned a non-null result. + (Note that the Function Call protocol can only handle a single + scalar result, not a rowtype or set of results.) @@ -750,7 +775,7 @@ FunctionVoidResponse - The function call was executed and returned no result. + The function call was executed and returned a NULL value. @@ -800,8 +825,9 @@ message (allowing successful termination) or a CopyFail message (which will cause the COPY SQL statement to fail with an error). The backend then reverts to the command-processing mode it was - in before the COPY started (which will be either simple or - extended query protocol). + in before the COPY started, which will be either simple or + extended query protocol. It will next send either CommandComplete + (if successful) or ErrorResponse (if not). @@ -826,7 +852,8 @@ zero or more CopyDataRow messages, one per row, followed by CopyDone. (For COPY BINARY, CopyBinaryRow messages are sent instead.) The backend then reverts to the command-processing mode it was - in before the COPY started. The frontend cannot abort + 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. @@ -1668,7 +1695,7 @@ Bind (F) - Int16 + Int32 @@ -2195,7 +2222,7 @@ CopyInResponse (B) - Int32(4) + Int32(5) @@ -2203,6 +2230,17 @@ CopyInResponse (B) + + + Int8 + + + + 0 for textual copy (CopyDataRow is expected), 1 for + binary copy (CopyBinaryRow is expected). + + + @@ -2231,7 +2269,7 @@ CopyOutResponse (B) - Int32(4) + Int32(5) @@ -2239,6 +2277,17 @@ CopyOutResponse (B) + + + Int8 + + + + 0 for textual copy (CopyDataRow will follow), 1 for + binary copy (CopyBinaryRow will follow). + + + @@ -2402,12 +2451,13 @@ EmptyQueryResponse (B) Identifies the message as a response to an empty query string. + (This substitutes for CommandComplete.) - Int32(5) + Int32(4) @@ -2415,16 +2465,6 @@ EmptyQueryResponse (B) - - - String("") - - - - Unused. - - - @@ -3014,7 +3054,7 @@ ParameterDescription (B) - Int16 + Int32 @@ -3147,7 +3187,7 @@ Parse (F) - Int16 + Int32