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.

diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 4906a715013f0a45d25fe9c31f731ad15f664b56..bb25eb74b144210d6a9542665bce4a2d2e310940 100644 (file)
--- 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.
    
 
-   <Para>
+   <para>
     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