diff options
| -rw-r--r-- | doc/src/sgml/protocol.sgml | 100 |
1 files changed, 70 insertions, 30 deletions
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 4906a715013..bb25eb74b14 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1,8 +1,16 @@ -<!-- $Header: /cvsroot/pgsql/doc/src/sgml/protocol.sgml,v 1.26 2003/04/15 22:51:18 tgl Exp $ --> +<!-- $Header: /cvsroot/pgsql/doc/src/sgml/protocol.sgml,v 1.27 2003/04/16 20:53:38 tgl Exp $ --> <chapter id="protocol"> <title>Frontend/Backend Protocol</title> + <caution> + <para> + This is currently a <emphasis>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. + </para> + </caution> + <para> <application>PostgreSQL</application> uses a message-based protocol for communication between frontends and backends (clients and servers). @@ -504,11 +512,12 @@ </Para> <Para> - The response to a <command>SELECT</> or <command>FETCH</> query + The response to a <command>SELECT</>, <command>FETCH</>, or + <command>SHOW</> query normally consists of RowDescription, zero or more DataRow or BinaryRow messages, and then CommandComplete. <command>COPY</> to or from the frontend invokes special protocol - as described below. + as described in <xref linkend="protocol-copy">. All other query types normally produce only a CommandComplete message. </Para> @@ -524,7 +533,6 @@ <Para> 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.) </Para> <Para> @@ -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 <literal>BINARY</> attribute + in cursor declarations is irrelevant when using this protocol. </para> <para> @@ -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. </para> <para> @@ -715,7 +729,16 @@ <Sect2> <Title>Function Call</Title> - <Para> + <note> + <para> + 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 <literal>SELECT function($1, ...)</>. + The Function Call cycle can then be replaced with Bind/Execute. + </para> + </note> + + <para> 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. </para> - <Para> + <para> The possible response messages from the backend are: <VariableList> @@ -741,7 +764,9 @@ <Term>FunctionResultResponse</Term> <ListItem> <Para> - 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.) </Para> </ListItem> </VarListEntry> @@ -750,7 +775,7 @@ <Term>FunctionVoidResponse</Term> <ListItem> <Para> - The function call was executed and returned no result. + The function call was executed and returned a NULL value. </Para> </ListItem> </VarListEntry> @@ -800,8 +825,9 @@ message (allowing successful termination) or a CopyFail message (which will cause the <command>COPY</> SQL statement to fail with an error). The backend then reverts to the command-processing mode it was - in before the <command>COPY</> started (which will be either simple or - extended query protocol). + in before the <command>COPY</> started, which will be either simple or + extended query protocol. It will next send either CommandComplete + (if successful) or ErrorResponse (if not). </para> <para> @@ -826,7 +852,8 @@ zero or more CopyDataRow messages, one per row, followed by CopyDone. (For <command>COPY BINARY</>, CopyBinaryRow messages are sent instead.) The backend then reverts to the command-processing mode it was - in before the <command>COPY</> started. The frontend cannot abort + in before the <command>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. </para> @@ -1668,7 +1695,7 @@ Bind (F) </VarListEntry> <VarListEntry> <Term> - Int16 + Int32 </Term> <ListItem> <Para> @@ -2195,7 +2222,7 @@ CopyInResponse (B) </VarListEntry> <VarListEntry> <Term> - Int32(4) + Int32(5) </Term> <ListItem> <Para> @@ -2203,6 +2230,17 @@ CopyInResponse (B) </Para> </ListItem> </VarListEntry> +<VarListEntry> +<Term> + Int8 +</Term> +<ListItem> +<Para> + 0 for textual copy (CopyDataRow is expected), 1 for + binary copy (CopyBinaryRow is expected). +</Para> +</ListItem> +</VarListEntry> </VariableList> </Para> @@ -2231,7 +2269,7 @@ CopyOutResponse (B) </VarListEntry> <VarListEntry> <Term> - Int32(4) + Int32(5) </Term> <ListItem> <Para> @@ -2239,6 +2277,17 @@ CopyOutResponse (B) </Para> </ListItem> </VarListEntry> +<VarListEntry> +<Term> + Int8 +</Term> +<ListItem> +<Para> + 0 for textual copy (CopyDataRow will follow), 1 for + binary copy (CopyBinaryRow will follow). +</Para> +</ListItem> +</VarListEntry> </VariableList> </Para> @@ -2402,12 +2451,13 @@ EmptyQueryResponse (B) <ListItem> <Para> Identifies the message as a response to an empty query string. + (This substitutes for CommandComplete.) </Para> </ListItem> </VarListEntry> <VarListEntry> <Term> - Int32(5) + Int32(4) </Term> <ListItem> <Para> @@ -2415,16 +2465,6 @@ EmptyQueryResponse (B) </Para> </ListItem> </VarListEntry> -<VarListEntry> -<Term> - String("") -</Term> -<ListItem> -<Para> - Unused. -</Para> -</ListItem> -</VarListEntry> </VariableList> </Para> @@ -3014,7 +3054,7 @@ ParameterDescription (B) </VarListEntry> <VarListEntry> <Term> - Int16 + Int32 </Term> <ListItem> <Para> @@ -3147,7 +3187,7 @@ Parse (F) </VarListEntry> <VarListEntry> <Term> - Int16 + Int32 </Term> <ListItem> <Para> |