From 16503e6fa4a13051debe09698b6db9ce0d509af8 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Mon, 5 May 2003 00:44:56 +0000 Subject: Extended query protocol: parse, bind, execute, describe FE/BE messages. Only lightly tested as yet, since libpq doesn't know anything about 'em. --- doc/src/sgml/protocol.sgml | 94 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 74 insertions(+), 20 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 4a01e310b30..48ba74edb54 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1,4 +1,4 @@ - + Frontend/Backend Protocol @@ -595,7 +595,11 @@ If successfully created, a named prepared-statement object lasts till the end of the current session, unless explicitly destroyed. An unnamed - prepared statement lasts only until the next Parse message is issued. + prepared statement lasts only until the next Parse statement specifying + the unnamed statement as destination is issued. (Note that a simple + Query message also destroys the unnamed statement.) Named prepared + statements must be explicitly closed before they can be redefined by + a Parse message, but this is not required for the unnamed statement. Named prepared statements can also be created and accessed at the SQL command level, using PREPARE and EXECUTE. @@ -611,10 +615,13 @@ - If successfully created, a named portal object lasts till - the end of the current transaction, unless explicitly destroyed. An - unnamed portal is destroyed at the end of the transaction, or as soon - as the next Parse or Bind message is executed. + If successfully created, a named portal object lasts till the end of the + current transaction, unless explicitly destroyed. An unnamed portal is + destroyed at the end of the transaction, or as soon as the next Bind + statement specifying the unnamed portal as destination is issued. (Note + that a simple Query message also destroys the unnamed portal.) Named + portals must be explicitly closed before they can be redefined by a Bind + message, but this is not required for the unnamed portal. Named portals can also be created and accessed at the SQL command level, using DECLARE CURSOR and FETCH. @@ -691,17 +698,19 @@ The Describe message (statement variant) specifies the name of an existing prepared statement (or an empty string for the unnamed prepared statement). The response is a ParameterDescription message describing the - parameters needed by the statement (if any), followed by a RowDescription - message describing the rows that will be returned when the statement is - eventually executed (or NoData if there is no SELECT-type query in the - prepared statement). ErrorResponse is issued if there is no such prepared - statement. This message may be useful if the client library is - uncertain about the parameters needed by a prepared statement. + parameters needed by the statement. ErrorResponse is issued if there is + no such prepared statement. This message may be useful if the client + library is uncertain about the parameters needed by a prepared statement. The Close message closes an existing prepared statement or portal - and releases resources. + and releases resources. It is not an error to issue Close against + a nonexistent statement or portal name. The response is normally + CloseComplete, but could be ErrorResponse if some difficulty is + encountered while releasing resources. Note that closing a prepared + statement implicitly closes any open portals that were constructed + from that statement. @@ -709,19 +718,20 @@ but forces the backend to deliver any data pending in its output buffers. A Flush must be sent after any extended-query command except Sync, if the frontend wishes to examine the results of that command before - issuing more commands. Without Flush, returning data will be combined - into the minimum possible number of packets to minimize network overhead. + issuing more commands. Without Flush, messages returned by the backend + will be combined into the minimum possible number of packets to minimize + network overhead. The simple Query message is approximately equivalent to the series Parse, - Bind, portal Describe, Execute, Sync, using the unnamed prepared statement - and portal objects and no parameters. One difference is that it - will accept multiple SQL statements in the query string, automatically + Bind, portal Describe, Execute, Close, Sync, using the unnamed prepared + statement and portal objects and no parameters. One difference is that + it will accept multiple SQL statements in the query string, automatically performing the bind/describe/execute sequence for each one in succession. - Another is that it will not return ParseComplete, BindComplete, or - NoData messages. + Another difference is that it will not return ParseComplete, BindComplete, + CloseComplete, or NoData messages. @@ -1917,6 +1927,41 @@ Close (F) + + +CloseComplete (B) + + + + + + + + Byte1('3') + + + + Identifies the message as a Close-complete indicator. + + + + + + Int32(4) + + + + Length of message contents in bytes, including self. + + + + + + + + + + CommandComplete (B) @@ -3875,6 +3920,15 @@ The ReadyForQuery ('Z') message includes a transaction status indicator. + +There is a new extended query sub-protocol, which adds the frontend +message types Parse, Bind, Execute, Describe, Close, Flush, and Sync, and the +backend message types ParseComplete, BindComplete, PortalSuspended, +ParameterDescription, NoData, and CloseComplete. Existing clients do not +have to concern themselves with this sub-protocol, but making use of it +may allow improvements in performance or functionality. + + COPY data is now encapsulated into CopyData and CopyDone messages. There is a well-defined way to recover from errors during COPY. The special -- cgit v1.2.3