doc/src/sgml/protocol.sgml

   1 <!-- $PostgreSQL$ -->
   2
   3 <chapter id="protocol">
   4  <title>Frontend/Backend Protocol</title>
   5
   6  <indexterm zone="protocol">
   7   <primary>protocol</primary>
   8   <secondary>frontend-backend</secondary>
   9  </indexterm>
  10
  11  <para>
  12   <productname>PostgreSQL</productname> uses a message-based protocol
  13   for communication between frontends and backends (clients and servers).
  14   The protocol is supported over <acronym>TCP/IP</acronym> and also over
  15   Unix-domain sockets.  Port number 5432 has been registered with IANA as
  16   the customary TCP port number for servers supporting this protocol, but
  17   in practice any non-privileged port number can be used.
  18  </para>
  19
  20  <para>
  21   This document describes version 3.0 of the protocol, implemented in
  22   <productname>PostgreSQL</productname> 7.4 and later.  For descriptions
  23   of the earlier protocol versions, see previous releases of the
  24   <productname>PostgreSQL</productname> documentation.  A single server
  25   can support multiple protocol versions.  The initial
  26   startup-request message tells the server which protocol version the
  27   client is attempting to use, and then the server follows that protocol
  28   if it is able.
  29  </para>
  30
  31  <para>
  32   Higher level features built on this protocol (for example, how
  33   <application>libpq</application> passes certain environment
  34   variables when the connection is established) are covered elsewhere.
  35  </para>
  36
  37   <para>
  38    In order to serve multiple clients efficiently, the server launches
  39    a new <quote>backend</> process for each client.
  40    In the current implementation, a new child
  41    process is created immediately after an incoming connection is detected.
  42    This is transparent to the protocol, however.  For purposes of the
  43    protocol, the terms <quote>backend</> and <quote>server</> are
  44    interchangeable; likewise <quote>frontend</> and <quote>client</>
  45    are interchangeable.
  46   </para>
  47
  48  <sect1 id="protocol-overview">
  49   <title>Overview</title>
  50
  51   <para>
  52    The protocol has separate phases for startup and normal operation.
  53    In the startup phase, the frontend opens a connection to the server
  54    and authenticates itself to the satisfaction of the server.  (This might
  55    involve a single message, or multiple messages depending on the
  56    authentication method being used.)  If all goes well, the server then sends
  57    status information to the frontend, and finally enters normal operation.
  58    Except for the initial startup-request message, this part of the
  59    protocol is driven by the server.
  60   </para>
  61
  62   <para>
  63    During normal operation, the frontend sends queries and
  64    other commands to the backend, and the backend sends back query results
  65    and other responses.  There are a few cases (such as <command>NOTIFY</>)
  66    wherein the
  67    backend will send unsolicited messages, but for the most part this portion
  68    of a session is driven by frontend requests.
  69   </para>
  70
  71   <para>
  72    Termination of the session is normally by frontend choice, but can be
  73    forced by the backend in certain cases.  In any case, when the backend
  74    closes the connection, it will roll back any open (incomplete) transaction
  75    before exiting.
  76   </para>
  77
  78   <para>
  79    Within normal operation, SQL commands can be executed through either of
  80    two sub-protocols.  In the <quote>simple query</> protocol, the frontend
  81    just sends a textual query string, which is parsed and immediately
  82    executed by the backend.  In the <quote>extended query</> protocol,
  83    processing of queries is separated into multiple steps: parsing,
  84    binding of parameter values, and execution.  This offers flexibility
  85    and performance benefits, at the cost of extra complexity.
  86   </para>
  87
  88   <para>
  89    Normal operation has additional sub-protocols for special operations
  90    such as <command>COPY</>.
  91   </para>
  92
  93  <sect2 id="protocol-message-concepts">
  94   <title>Messaging Overview</title>
  95
  96   <para>
  97    All communication is through a stream of messages.  The first byte of a
  98    message identifies the message type, and the next four bytes specify the
  99    length of the rest of the message (this length count includes itself, but
 100    not the message-type byte).  The remaining contents of the message are
 101    determined by the message type.  For historical reasons, the very first
 102    message sent by the client (the startup message) has no initial
 103    message-type byte.
 104   </para>
 105
 106   <para>
 107    To avoid losing synchronization with the message stream, both servers and
 108    clients typically read an entire message into a buffer (using the byte
 109    count) before attempting to process its contents.  This allows easy
 110    recovery if an error is detected while processing the contents.  In
 111    extreme situations (such as not having enough memory to buffer the
 112    message), the receiver can use the byte count to determine how much
 113    input to skip before it resumes reading messages.
 114   </para>
 115
 116   <para>
 117    Conversely, both servers and clients must take care never to send an
 118    incomplete message.  This is commonly done by marshaling the entire message
 119    in a buffer before beginning to send it.  If a communications failure
 120    occurs partway through sending or receiving a message, the only sensible
 121    response is to abandon the connection, since there is little hope of
 122    recovering message-boundary synchronization.
 123   </para>
 124  </sect2>
 125
 126   <sect2 id="protocol-query-concepts">
 127    <title>Extended Query Overview</title>
 128
 129    <para>
 130     In the extended-query protocol, execution of SQL commands is divided
 131     into multiple steps.  The state retained between steps is represented
 132     by two types of objects: <firstterm>prepared statements</> and
 133     <firstterm>portals</>.  A prepared statement represents the result of
 134     parsing, semantic analysis, and (optionally) planning of a textual query
 135     string.
 136     A prepared statement is not necessarily ready to execute, because it might
 137     lack specific values for <firstterm>parameters</>.  A portal represents
 138     a ready-to-execute or already-partially-executed statement, with any
 139     missing parameter values filled in.  (For <command>SELECT</> statements,
 140     a portal is equivalent to an open cursor, but we choose to use a different
 141     term since cursors don't handle non-<command>SELECT</> statements.)
 142    </para>
 143
 144    <para>
 145     The overall execution cycle consists of a <firstterm>parse</> step,
 146     which creates a prepared statement from a textual query string; a
 147     <firstterm>bind</> step, which creates a portal given a prepared
 148     statement and values for any needed parameters; and an
 149     <firstterm>execute</> step that runs a portal's query.  In the case of
 150     a query that returns rows (<command>SELECT</>, <command>SHOW</>, etc),
 151     the execute step can be told to fetch only
 152     a limited number of rows, so that multiple execute steps might be needed
 153     to complete the operation.
 154    </para>
 155
 156    <para>
 157     The backend can keep track of multiple prepared statements and portals
 158     (but note that these exist only within a session, and are never shared
 159     across sessions).  Existing prepared statements and portals are
 160     referenced by names assigned when they were created.  In addition,
 161     an <quote>unnamed</> prepared statement and portal exist.  Although these
 162     behave largely the same as named objects, operations on them are optimized
 163     for the case of executing a query only once and then discarding it,
 164     whereas operations on named objects are optimized on the expectation
 165     of multiple uses.
 166    </para>
 167   </sect2>
 168
 169   <sect2 id="protocol-format-codes">
 170    <title>Formats and Format Codes</title>
 171
 172    <para>
 173     Data of a particular data type might be transmitted in any of several
 174     different <firstterm>formats</>.  As of <productname>PostgreSQL</> 7.4
 175     the only supported formats are <quote>text</> and <quote>binary</>,
 176     but the protocol makes provision for future extensions.  The desired
 177     format for any value is specified by a <firstterm>format code</>.
 178     Clients can specify a format code for each transmitted parameter value
 179     and for each column of a query result.  Text has format code zero,
 180     binary has format code one, and all other format codes are reserved
 181     for future definition.
 182    </para>
 183
 184    <para>
 185     The text representation of values is whatever strings are produced
 186     and accepted by the input/output conversion functions for the
 187     particular data type.  In the transmitted representation, there is
 188     no trailing null character; the frontend must add one to received
 189     values if it wants to process them as C strings.
 190     (The text format does not allow embedded nulls, by the way.)
 191    </para>
 192
 193    <para>
 194     Binary representations for integers use network byte order (most
 195     significant byte first).  For other data types consult the documentation
 196     or source code to learn about the binary representation.  Keep in mind
 197     that binary representations for complex data types might change across
 198     server versions; the text format is usually the more portable choice.
 199    </para>
 200   </sect2>
 201  </sect1>
 202
 203  <sect1 id="protocol-flow">
 204   <title>Message Flow</title>
 205
 206   <para>
 207    This section describes the message flow and the semantics of each
 208    message type.  (Details of the exact representation of each message
 209    appear in <xref linkend="protocol-message-formats">.)  There are
 210    several different sub-protocols depending on the state of the
 211    connection: start-up, query, function call,
 212    <command>COPY</command>, and termination.  There are also special
 213    provisions for asynchronous operations (including notification
 214    responses and command cancellation), which can occur at any time
 215    after the start-up phase.
 216   </para>
 217
 218   <sect2>
 219    <title>Start-Up</title>
 220
 221    <para>
 222     To begin a session, a frontend opens a connection to the server and sends
 223     a startup message.  This message includes the names of the user and of the
 224     database the user wants to connect to; it also identifies the particular
 225     protocol version to be used.  (Optionally, the startup message can include
 226     additional settings for run-time parameters.)
 227     The server then uses this information and
 228     the contents of its configuration files (such as
 229     <filename>pg_hba.conf</filename>) to determine
 230     whether the connection is provisionally acceptable, and what additional
 231     authentication is required (if any).
 232    </para>
 233
 234    <para>
 235     The server then sends an appropriate authentication request message,
 236     to which the frontend must reply with an appropriate authentication
 237     response message (such as a password).
 238     For all authentication methods except GSSAPI and SSPI, there is at most
 239     one request and one response. In some methods, no response
 240     at all is needed from the frontend, and so no authentication request
 241     occurs. For GSSAPI and SSPI, multiple exchanges of packets may be needed
 242     to complete the authentication.
 243    </para>
 244
 245    <para>
 246     The authentication cycle ends with the server either rejecting the
 247     connection attempt (ErrorResponse), or sending AuthenticationOk.
 248    </para>
 249
 250    <para>
 251     The possible messages from the server in this phase are:
 252
 253     <variablelist>
 254      <varlistentry>
 255       <term>ErrorResponse</term>
 256       <listitem>
 257        <para>
 258         The connection attempt has been rejected.
 259         The server then immediately closes the connection.
 260        </para>
 261       </listitem>
 262      </varlistentry>
 263
 264      <varlistentry>
 265       <term>AuthenticationOk</term>
 266       <listitem>
 267        <para>
 268         The authentication exchange is successfully completed.
 269        </para>
 270       </listitem>
 271      </varlistentry>
 272
 273      <varlistentry>
 274       <term>AuthenticationKerberosV5</term>
 275       <listitem>
 276        <para>
 277         The frontend must now take part in a Kerberos V5
 278         authentication dialog (not described here, part of the
 279         Kerberos specification) with the server.  If this is
 280         successful, the server responds with an AuthenticationOk,
 281         otherwise it responds with an ErrorResponse.
 282        </para>
 283       </listitem>
 284      </varlistentry>
 285
 286      <varlistentry>
 287       <term>AuthenticationCleartextPassword</term>
 288       <listitem>
 289        <para>
 290         The frontend must now send a PasswordMessage containing the
 291         password in clear-text form.  If
 292         this is the correct password, the server responds with an
 293         AuthenticationOk, otherwise it responds with an ErrorResponse.
 294        </para>
 295       </listitem>
 296      </varlistentry>
 297
 298      <varlistentry>
 299       <term>AuthenticationMD5Password</term>
 300       <listitem>
 301        <para>
 302         The frontend must now send a PasswordMessage containing the
 303         password encrypted via MD5, using the 4-character salt
 304         specified in the AuthenticationMD5Password message.  If
 305         this is the correct password, the server responds with an
 306         AuthenticationOk, otherwise it responds with an ErrorResponse.
 307        </para>
 308       </listitem>
 309      </varlistentry>
 310
 311      <varlistentry>
 312       <term>AuthenticationSCMCredential</term>
 313       <listitem>
 314        <para>
 315         This response is only possible for local Unix-domain connections
 316         on platforms that support SCM credential messages.  The frontend
 317         must issue an SCM credential message and then send a single data
 318         byte.  (The contents of the data byte are uninteresting; it's
 319         only used to ensure that the server waits long enough to receive
 320         the credential message.)  If the credential is acceptable,
 321         the server responds with an
 322         AuthenticationOk, otherwise it responds with an ErrorResponse.
 323        </para>
 324       </listitem>
 325      </varlistentry>
 326
 327      <varlistentry>
 328       <term>AuthenticationGSS</term>
 329       <listitem>
 330        <para>
 331         The frontend must now initiate a GSSAPI negotiation. The frontend
 332         will send a PasswordMessage with the first part of the GSSAPI
 333         data stream in response to this. If further messages are needed,
 334         the server will respond with AuthenticationGSSContinue.
 335        </para>
 336       </listitem>
 337      </varlistentry>
 338
 339      <varlistentry>
 340       <term>AuthenticationSSPI</term>
 341       <listitem>
 342        <para>
 343         The frontend must now initiate a SSPI negotiation. The frontend
 344         will send a PasswordMessage with the first part of the SSPI
 345         data stream in response to this. If further messages are needed,
 346         the server will respond with AuthenticationGSSContinue.
 347        </para>
 348       </listitem>
 349
 350      </varlistentry>
 351      <varlistentry>
 352       <term>AuthenticationGSSContinue</term>
 353       <listitem>
 354        <para>
 355         This message contains the response data from the previous step
 356         of GSSAPI or SSPI negotiation (AuthenticationGSS, AuthenticationSSPI
 357         or a previous AuthenticationGSSContinue). If the GSSAPI
 358         or SSPI data in this message
 359         indicates more data is needed to complete the authentication,
 360         the frontend must send that data as another PasswordMessage. If
 361         GSSAPI or SSPI authentication is completed by this message, the server
 362         will next send AuthenticationOk to indicate successful authentication
 363         or ErrorResponse to indicate failure.
 364        </para>
 365       </listitem>
 366      </varlistentry>
 367
 368     </variablelist>
 369    </para>
 370
 371    <para>
 372     If the frontend does not support the authentication method
 373     requested by the server, then it should immediately close the
 374     connection.
 375    </para>
 376
 377    <para>
 378     After having received AuthenticationOk, the frontend must wait
 379     for further messages from the server.  In this phase a backend process
 380     is being started, and the frontend is just an interested bystander.
 381     It is still possible for the startup attempt
 382     to fail (ErrorResponse), but in the normal case the backend will send
 383     some ParameterStatus messages, BackendKeyData, and finally ReadyForQuery.
 384    </para>
 385
 386    <para>
 387     During this phase the backend will attempt to apply any additional
 388     run-time parameter settings that were given in the startup message.
 389     If successful, these values become session defaults.  An error causes
 390     ErrorResponse and exit.
 391    </para>
 392
 393    <para>
 394     The possible messages from the backend in this phase are:
 395
 396     <variablelist>
 397      <varlistentry>
 398       <term>BackendKeyData</term>
 399       <listitem>
 400        <para>
 401         This message provides secret-key data that the frontend must
 402         save if it wants to be able to issue cancel requests later.
 403         The frontend should not respond to this message, but should
 404         continue listening for a ReadyForQuery message.
 405        </para>
 406       </listitem>
 407      </varlistentry>
 408
 409      <varlistentry>
 410       <term>ParameterStatus</term>
 411       <listitem>
 412        <para>
 413         This message informs the frontend about the current (initial)
 414          setting of backend parameters, such as <xref
 415          linkend="guc-client-encoding"> or <xref linkend="guc-datestyle">.
 416          The frontend can ignore this message, or record the settings
 417          for its future use; see <xref linkend="protocol-async"> for
 418          more details.  The frontend should not respond to this
 419          message, but should continue listening for a ReadyForQuery
 420          message.
 421        </para>
 422       </listitem>
 423      </varlistentry>
 424
 425      <varlistentry>
 426       <term>ReadyForQuery</term>
 427       <listitem>
 428        <para>
 429         Start-up is completed.  The frontend can now issue commands.
 430        </para>
 431       </listitem>
 432      </varlistentry>
 433
 434      <varlistentry>
 435       <term>ErrorResponse</term>
 436       <listitem>
 437        <para>
 438         Start-up failed.  The connection is closed after sending this
 439         message.
 440        </para>
 441       </listitem>
 442      </varlistentry>
 443
 444      <varlistentry>
 445       <term>NoticeResponse</term>
 446       <listitem>
 447        <para>
 448         A warning message has been issued.  The frontend should
 449         display the message but continue listening for ReadyForQuery
 450         or ErrorResponse.
 451        </para>
 452       </listitem>
 453      </varlistentry>
 454     </variablelist>
 455    </para>
 456
 457    <para>
 458     The ReadyForQuery message is the same one that the backend will
 459     issue after each command cycle.  Depending on the coding needs of
 460     the frontend, it is reasonable to consider ReadyForQuery as
 461     starting a command cycle, or to consider ReadyForQuery as ending the
 462     start-up phase and each subsequent command cycle.
 463    </para>
 464   </sect2>
 465
 466   <sect2>
 467    <title>Simple Query</title>
 468
 469    <para>
 470     A simple query cycle is initiated by the frontend sending a Query message
 471     to the backend.  The message includes an SQL command (or commands)
 472     expressed as a text string.
 473     The backend then sends one or more response
 474     messages depending on the contents of the query command string,
 475     and finally a ReadyForQuery response message.  ReadyForQuery
 476     informs the frontend that it can safely send a new command.
 477     (It is not actually necessary for the frontend to wait for
 478     ReadyForQuery before issuing another command, but the frontend must
 479     then take responsibility for figuring out what happens if the earlier
 480     command fails and already-issued later commands succeed.)
 481    </para>
 482
 483    <para>
 484     The possible response messages from the backend are:
 485
 486     <variablelist>
 487      <varlistentry>
 488       <term>CommandComplete</term>
 489       <listitem>
 490        <para>
 491         An SQL command completed normally.
 492        </para>
 493       </listitem>
 494      </varlistentry>
 495
 496      <varlistentry>
 497       <term>CopyInResponse</term>
 498       <listitem>
 499        <para>
 500         The backend is ready to copy data from the frontend to a
 501         table; see <xref linkend="protocol-copy">.
 502        </para>
 503       </listitem>
 504      </varlistentry>
 505
 506      <varlistentry>
 507       <term>CopyOutResponse</term>
 508       <listitem>
 509        <para>
 510         The backend is ready to copy data from a table to the
 511         frontend; see <xref linkend="protocol-copy">.
 512        </para>
 513       </listitem>
 514      </varlistentry>
 515
 516      <varlistentry>
 517       <term>RowDescription</term>
 518       <listitem>
 519        <para>
 520         Indicates that rows are about to be returned in response to
 521         a <command>SELECT</command>, <command>FETCH</command>, etc query.
 522         The contents of this message describe the column layout of the rows.
 523         This will be followed by a DataRow message for each row being returned
 524         to the frontend.
 525        </para>
 526       </listitem>
 527      </varlistentry>
 528
 529      <varlistentry>
 530       <term>DataRow</term>
 531       <listitem>
 532        <para>
 533         One of the set of rows returned by
 534         a <command>SELECT</command>, <command>FETCH</command>, etc query.
 535        </para>
 536       </listitem>
 537      </varlistentry>
 538
 539      <varlistentry>
 540       <term>EmptyQueryResponse</term>
 541       <listitem>
 542        <para>
 543         An empty query string was recognized.
 544        </para>
 545       </listitem>
 546      </varlistentry>
 547
 548      <varlistentry>
 549       <term>ErrorResponse</term>
 550       <listitem>
 551        <para>
 552         An error has occurred.
 553        </para>
 554       </listitem>
 555      </varlistentry>
 556
 557      <varlistentry>
 558       <term>ReadyForQuery</term>
 559       <listitem>
 560        <para>
 561         Processing of the query string is complete.  A separate
 562         message is sent to indicate this because the query string might
 563         contain multiple SQL commands.  (CommandComplete marks the
 564         end of processing one SQL command, not the whole string.)
 565         ReadyForQuery will always be sent, whether processing
 566         terminates successfully or with an error.
 567        </para>
 568       </listitem>
 569      </varlistentry>
 570
 571      <varlistentry>
 572       <term>NoticeResponse</term>
 573       <listitem>
 574        <para>
 575         A warning message has been issued in relation to the query.
 576         Notices are in addition to other responses, i.e., the backend
 577         will continue processing the command.
 578        </para>
 579       </listitem>
 580      </varlistentry>
 581
 582     </variablelist>
 583    </para>
 584
 585    <para>
 586     The response to a <command>SELECT</> query (or other queries that
 587     return row sets, such as <command>EXPLAIN</> or <command>SHOW</>)
 588     normally consists of RowDescription, zero or more
 589     DataRow messages, and then CommandComplete.
 590     <command>COPY</> to or from the frontend invokes special protocol
 591     as described in <xref linkend="protocol-copy">.
 592     All other query types normally produce only
 593     a CommandComplete message.
 594    </para>
 595
 596    <para>
 597     Since a query string could contain several queries (separated by
 598     semicolons), there might be several such response sequences before the
 599     backend finishes processing the query string.  ReadyForQuery is issued
 600     when the entire string has been processed and the backend is ready to
 601     accept a new query string.
 602    </para>
 603
 604    <para>
 605     If a completely empty (no contents other than whitespace) query string
 606     is received, the response is EmptyQueryResponse followed by ReadyForQuery.
 607    </para>
 608
 609    <para>
 610     In the event of an error, ErrorResponse is issued followed by
 611     ReadyForQuery.  All further processing of the query string is aborted by
 612     ErrorResponse (even if more queries remained in it).  Note that this
 613     might occur partway through the sequence of messages generated by an
 614     individual query.
 615    </para>
 616
 617    <para>
 618     In simple Query mode, the format of retrieved values is always text,
 619     except when the given command is a <command>FETCH</> from a cursor
 620     declared with the <literal>BINARY</> option.  In that case, the
 621     retrieved values are in binary format.  The format codes given in
 622     the RowDescription message tell which format is being used.
 623    </para>
 624
 625    <para>
 626     A frontend must be prepared to accept ErrorResponse and
 627     NoticeResponse messages whenever it is expecting any other type of
 628     message.  See also <xref linkend="protocol-async"> concerning messages
 629     that the backend might generate due to outside events.
 630    </para>
 631
 632    <para>
 633     Recommended practice is to code frontends in a state-machine style
 634     that will accept any message type at any time that it could make sense,
 635     rather than wiring in assumptions about the exact sequence of messages.
 636    </para>
 637   </sect2>
 638
 639   <sect2 id="protocol-flow-ext-query">
 640    <title>Extended Query</title>
 641
 642    <para>
 643     The extended query protocol breaks down the above-described simple
 644     query protocol into multiple steps.  The results of preparatory
 645     steps can be re-used multiple times for improved efficiency.
 646     Furthermore, additional features are available, such as the possibility
 647     of supplying data values as separate parameters instead of having to
 648     insert them directly into a query string.
 649    </para>
 650
 651    <para>
 652     In the extended protocol, the frontend first sends a Parse message,
 653     which contains a textual query string, optionally some information
 654     about data types of parameter placeholders, and the
 655     name of a destination prepared-statement object (an empty string
 656     selects the unnamed prepared statement).  The response is
 657     either ParseComplete or ErrorResponse.  Parameter data types can be
 658     specified by OID; if not given, the parser attempts to infer the
 659     data types in the same way as it would do for untyped literal string
 660     constants.
 661    </para>
 662
 663    <note>
 664     <para>
 665      A parameter data type can be left unspecified by setting it to zero,
 666      or by making the array of parameter type OIDs shorter than the
 667      number of parameter symbols (<literal>$</><replaceable>n</>)
 668      used in the query string.  Another special case is that a parameter's
 669      type can be specified as <type>void</> (that is, the OID of the
 670      <type>void</> pseudotype).  This is meant to allow parameter symbols
 671      to be used for function parameters that are actually OUT parameters.
 672      Ordinarily there is no context in which a <type>void</> parameter
 673      could be used, but if such a parameter symbol appears in a function's
 674      parameter list, it is effectively ignored.  For example, a function
 675      call such as <literal>foo($1,$2,$3,$4)</> could match a function with
 676      two IN and two OUT arguments, if <literal>$3</> and <literal>$4</>
 677      are specified as having type <type>void</>.
 678     </para>
 679    </note>
 680
 681    <note>
 682     <para>
 683      The query string contained in a Parse message cannot include more
 684      than one SQL statement; else a syntax error is reported.  This
 685      restriction does not exist in the simple-query protocol, but it
 686      does exist in the extended protocol, because allowing prepared
 687      statements or portals to contain multiple commands would complicate
 688      the protocol unduly.
 689     </para>
 690    </note>
 691
 692    <para>
 693     If successfully created, a named prepared-statement object lasts till
 694     the end of the current session, unless explicitly destroyed.  An unnamed
 695     prepared statement lasts only until the next Parse statement specifying
 696     the unnamed statement as destination is issued.  (Note that a simple
 697     Query message also destroys the unnamed statement.)  Named prepared
 698     statements must be explicitly closed before they can be redefined by
 699     a Parse message, but this is not required for the unnamed statement.
 700     Named prepared statements can also be created and accessed at the SQL
 701     command level, using <command>PREPARE</> and <command>EXECUTE</>.
 702    </para>
 703
 704    <para>
 705     Once a prepared statement exists, it can be readied for execution using a
 706     Bind message.  The Bind message gives the name of the source prepared
 707     statement (empty string denotes the unnamed prepared statement), the name
 708     of the destination portal (empty string denotes the unnamed portal), and
 709     the values to use for any parameter placeholders present in the prepared
 710     statement.  The
 711     supplied parameter set must match those needed by the prepared statement.
 712     (If you declared any <type>void</> parameters in the Parse message,
 713     pass NULL values for them in the Bind message.)
 714     Bind also specifies the format to use for any data returned
 715     by the query; the format can be specified overall, or per-column.
 716     The response is either BindComplete or ErrorResponse.
 717    </para>
 718
 719    <note>
 720     <para>
 721      The choice between text and binary output is determined by the format
 722      codes given in Bind, regardless of the SQL command involved.  The
 723      <literal>BINARY</> attribute in cursor declarations is irrelevant when
 724      using extended query protocol.
 725     </para>
 726    </note>
 727
 728    <para>
 729     Query planning for named prepared-statement objects occurs when the Parse
 730     message is processed. If a query will be repeatedly executed with
 731     different parameters, it might be beneficial to send a single Parse message
 732     containing a parameterized query, followed by multiple Bind
 733     and Execute messages. This will avoid replanning the query on each
 734     execution.
 735    </para>
 736
 737    <para>
 738     The unnamed prepared statement is likewise planned during Parse processing
 739     if the Parse message defines no parameters.  But if there are parameters,
 740     query planning occurs during Bind processing instead.  This allows the
 741     planner to make use of the actual values of the parameters provided in
 742     the Bind message when planning the query.
 743    </para>
 744
 745    <note>
 746     <para>
 747      Query plans generated from a parameterized query might be less
 748      efficient than query plans generated from an equivalent query with actual
 749      parameter values substituted. The query planner cannot make decisions
 750      based on actual parameter values (for example, index selectivity) when
 751      planning a parameterized query assigned to a named prepared-statement
 752      object.  This possible penalty is avoided when using the unnamed
 753      statement, since it is not planned until actual parameter values are
 754      available.  The cost is that planning must occur afresh for each Bind,
 755      even if the query stays the same.
 756     </para>
 757    </note>
 758
 759    <para>
 760     If successfully created, a named portal object lasts till the end of the
 761     current transaction, unless explicitly destroyed.  An unnamed portal is
 762     destroyed at the end of the transaction, or as soon as the next Bind
 763     statement specifying the unnamed portal as destination is issued.  (Note
 764     that a simple Query message also destroys the unnamed portal.)  Named
 765     portals must be explicitly closed before they can be redefined by a Bind
 766     message, but this is not required for the unnamed portal.
 767     Named portals can also be created and accessed at the SQL
 768     command level, using <command>DECLARE CURSOR</> and <command>FETCH</>.
 769    </para>
 770
 771    <para>
 772     Once a portal exists, it can be executed using an Execute message.
 773     The Execute message specifies the portal name (empty string denotes the
 774     unnamed portal) and
 775     a maximum result-row count (zero meaning <quote>fetch all rows</>).
 776     The result-row count is only meaningful for portals
 777     containing commands that return row sets; in other cases the command is
 778     always executed to completion, and the row count is ignored.
 779     The possible
 780     responses to Execute are the same as those described above for queries
 781     issued via simple query protocol, except that Execute doesn't cause
 782     ReadyForQuery or RowDescription to be issued.
 783    </para>
 784
 785    <para>
 786     If Execute terminates before completing the execution of a portal
 787     (due to reaching a nonzero result-row count), it will send a
 788     PortalSuspended message; the appearance of this message tells the frontend
 789     that another Execute should be issued against the same portal to
 790     complete the operation.  The CommandComplete message indicating
 791     completion of the source SQL command is not sent until
 792     the portal's execution is completed.  Therefore, an Execute phase is
 793     always terminated by the appearance of exactly one of these messages:
 794     CommandComplete, EmptyQueryResponse (if the portal was created from
 795     an empty query string), ErrorResponse, or PortalSuspended.
 796    </para>
 797
 798    <para>
 799     At completion of each series of extended-query messages, the frontend
 800     should issue a Sync message.  This parameterless message causes the
 801     backend to close the current transaction if it's not inside a
 802     <command>BEGIN</>/<command>COMMIT</> transaction block (<quote>close</>
 803     meaning to commit if no error, or roll back if error).  Then a
 804     ReadyForQuery response is issued.  The purpose of Sync is to provide
 805     a resynchronization point for error recovery.  When an error is detected
 806     while processing any extended-query message, the backend issues
 807     ErrorResponse, then reads and discards messages until a Sync is reached,
 808     then issues ReadyForQuery and returns to normal message processing.
 809     (But note that no skipping occurs if an error is detected
 810     <emphasis>while</> processing Sync &mdash; this ensures that there is one
 811     and only one ReadyForQuery sent for each Sync.)
 812    </para>
 813
 814    <note>
 815     <para>
 816      Sync does not cause a transaction block opened with <command>BEGIN</>
 817      to be closed.  It is possible to detect this situation since the
 818      ReadyForQuery message includes transaction status information.
 819     </para>
 820    </note>
 821
 822    <para>
 823     In addition to these fundamental, required operations, there are several
 824     optional operations that can be used with extended-query protocol.
 825    </para>
 826
 827    <para>
 828     The Describe message (portal variant) specifies the name of an existing
 829     portal (or an empty string for the unnamed portal).  The response is a
 830     RowDescription message describing the rows that will be returned by
 831     executing the portal; or a NoData message if the portal does not contain a
 832     query that will return rows; or ErrorResponse if there is no such portal.
 833    </para>
 834
 835    <para>
 836     The Describe message (statement variant) specifies the name of an existing
 837     prepared statement (or an empty string for the unnamed prepared
 838     statement).  The response is a ParameterDescription message describing the
 839     parameters needed by the statement, followed by a RowDescription message
 840     describing the rows that will be returned when the statement is eventually
 841     executed (or a NoData message if the statement will not return rows).
 842     ErrorResponse is issued if there is no such prepared statement.  Note that
 843     since Bind has not yet been issued, the formats to be used for returned
 844     columns are not yet known to the backend; the format code fields in the
 845     RowDescription message will be zeroes in this case.
 846    </para>
 847
 848    <tip>
 849     <para>
 850      In most scenarios the frontend should issue one or the other variant
 851      of Describe before issuing Execute, to ensure that it knows how to
 852      interpret the results it will get back.
 853     </para>
 854    </tip>
 855
 856    <para>
 857     The Close message closes an existing prepared statement or portal
 858     and releases resources.  It is not an error to issue Close against
 859     a nonexistent statement or portal name.  The response is normally
 860     CloseComplete, but could be ErrorResponse if some difficulty is
 861     encountered while releasing resources.  Note that closing a prepared
 862     statement implicitly closes any open portals that were constructed
 863     from that statement.
 864    </para>
 865
 866    <para>
 867     The Flush message does not cause any specific output to be generated,
 868     but forces the backend to deliver any data pending in its output
 869     buffers.  A Flush must be sent after any extended-query command except
 870     Sync, if the frontend wishes to examine the results of that command before
 871     issuing more commands.  Without Flush, messages returned by the backend
 872     will be combined into the minimum possible number of packets to minimize
 873     network overhead.
 874    </para>
 875
 876    <note>
 877     <para>
 878      The simple Query message is approximately equivalent to the series Parse,
 879      Bind, portal Describe, Execute, Close, Sync, using the unnamed prepared
 880      statement and portal objects and no parameters.  One difference is that
 881      it will accept multiple SQL statements in the query string, automatically
 882      performing the bind/describe/execute sequence for each one in succession.
 883      Another difference is that it will not return ParseComplete, BindComplete,
 884      CloseComplete, or NoData messages.
 885     </para>
 886    </note>
 887   </sect2>
 888
 889   <sect2>
 890    <title>Function Call</title>
 891
 892    <para>
 893     The Function Call sub-protocol allows the client to request a direct
 894     call of any function that exists in the database's
 895     <structname>pg_proc</structname> system catalog.  The client must have
 896     execute permission for the function.
 897    </para>
 898
 899    <note>
 900     <para>
 901      The Function Call sub-protocol is a legacy feature that is probably best
 902      avoided in new code.  Similar results can be accomplished by setting up
 903      a prepared statement that does <literal>SELECT function($1, ...)</>.
 904      The Function Call cycle can then be replaced with Bind/Execute.
 905     </para>
 906    </note>
 907
 908    <para>
 909     A Function Call cycle is initiated by the frontend sending a
 910     FunctionCall message to the backend.  The backend then sends one
 911     or more response messages depending on the results of the function
 912     call, and finally a ReadyForQuery response message.  ReadyForQuery
 913     informs the frontend that it can safely send a new query or
 914     function call.
 915    </para>
 916
 917    <para>
 918     The possible response messages from the backend are:
 919
 920     <variablelist>
 921      <varlistentry>
 922       <term>ErrorResponse</term>
 923       <listitem>
 924        <para>
 925         An error has occurred.
 926        </para>
 927       </listitem>
 928      </varlistentry>
 929
 930      <varlistentry>
 931       <term>FunctionCallResponse</term>
 932       <listitem>
 933        <para>
 934         The function call was completed and returned the result given
 935         in the message.
 936         (Note that the Function Call protocol can only handle a single
 937         scalar result, not a row type or set of results.)
 938        </para>
 939       </listitem>
 940      </varlistentry>
 941
 942      <varlistentry>
 943       <term>ReadyForQuery</term>
 944       <listitem>
 945        <para>
 946         Processing of the function call is complete.  ReadyForQuery
 947         will always be sent, whether processing terminates
 948         successfully or with an error.
 949        </para>
 950       </listitem>
 951      </varlistentry>
 952
 953      <varlistentry>
 954       <term>NoticeResponse</term>
 955       <listitem>
 956        <para>
 957         A warning message has been issued in relation to the function
 958         call.  Notices are in addition to other responses, i.e., the
 959         backend will continue processing the command.
 960        </para>
 961       </listitem>
 962      </varlistentry>
 963     </variablelist>
 964    </para>
 965   </sect2>
 966
 967   <sect2 id="protocol-copy">
 968    <title>COPY Operations</title>
 969
 970    <para>
 971     The <command>COPY</> command allows high-speed bulk data transfer
 972     to or from the server.  Copy-in and copy-out operations each switch
 973     the connection into a distinct sub-protocol, which lasts until the
 974     operation is completed.
 975    </para>
 976
 977    <para>
 978     Copy-in mode (data transfer to the server) is initiated when the
 979     backend executes a <command>COPY FROM STDIN</> SQL statement.  The backend
 980     sends a CopyInResponse message to the frontend.  The frontend should
 981     then send zero or more CopyData messages, forming a stream of input
 982     data.  (The message boundaries are not required to have anything to do
 983     with row boundaries, although that is often a reasonable choice.)
 984     The frontend can terminate the copy-in mode by sending either a CopyDone
 985     message (allowing successful termination) or a CopyFail message (which
 986     will cause the <command>COPY</> SQL statement to fail with an
 987     error).  The backend then reverts to the command-processing mode it was
 988     in before the <command>COPY</> started, which will be either simple or
 989     extended query protocol.  It will next send either CommandComplete
 990     (if successful) or ErrorResponse (if not).
 991    </para>
 992
 993    <para>
 994     In the event of a backend-detected error during copy-in mode (including
 995     receipt of a CopyFail message), the backend will issue an ErrorResponse
 996     message.  If the <command>COPY</> command was issued via an extended-query
 997     message, the backend will now discard frontend messages until a Sync
 998     message is received, then it will issue ReadyForQuery and return to normal
 999     processing.  If the <command>COPY</> command was issued in a simple
1000     Query message, the rest of that message is discarded and ReadyForQuery
1001     is issued.  In either case, any subsequent CopyData, CopyDone, or CopyFail
1002     messages issued by the frontend will simply be dropped.
1003    </para>
1004
1005    <para>
1006     The backend will ignore Flush and Sync messages received during copy-in
1007     mode.  Receipt of any other non-copy message type constitutes an error
1008     that will abort the copy-in state as described above.  (The exception for
1009     Flush and Sync is for the convenience of client libraries that always
1010     send Flush or Sync after an Execute message, without checking whether
1011     the command to be executed is a <command>COPY FROM STDIN</>.)
1012    </para>
1013
1014    <para>
1015     Copy-out mode (data transfer from the server) is initiated when the
1016     backend executes a <command>COPY TO STDOUT</> SQL statement.  The backend
1017     sends a CopyOutResponse message to the frontend, followed by
1018     zero or more CopyData messages (always one per row), followed by CopyDone.
1019     The backend then reverts to the command-processing mode it was
1020     in before the <command>COPY</> started, and sends CommandComplete.
1021     The frontend cannot abort the transfer (except by closing the connection
1022     or issuing a Cancel request),
1023     but it can discard unwanted CopyData and CopyDone messages.
1024    </para>
1025
1026    <para>
1027     In the event of a backend-detected error during copy-out mode,
1028     the backend will issue an ErrorResponse message and revert to normal
1029     processing.  The frontend should treat receipt of ErrorResponse as
1030     terminating the copy-out mode.
1031    </para>
1032
1033    <para>
1034     It is possible for NoticeResponse and ParameterStatus messages to be
1035     interspersed between CopyData messages; frontends must handle these cases,
1036     and should be prepared for other asynchronous message types as well (see
1037     <xref linkend="protocol-async">).  Otherwise, any message type other than
1038     CopyData or CopyDone may be treated as terminating copy-out mode.
1039    </para>
1040
1041    <para>
1042     The CopyInResponse and CopyOutResponse messages include fields that
1043     inform the frontend of the number of columns per row and the format
1044     codes being used for each column.  (As of the present implementation,
1045     all columns in a given <command>COPY</> operation will use the same
1046     format, but the message design does not assume this.)
1047    </para>
1048   </sect2>
1049
1050   <sect2 id="protocol-async">
1051    <title>Asynchronous Operations</title>
1052
1053    <para>
1054     There are several cases in which the backend will send messages that
1055     are not specifically prompted by the frontend's command stream.
1056     Frontends must be prepared to deal with these messages at any time,
1057     even when not engaged in a query.
1058     At minimum, one should check for these cases before beginning to
1059     read a query response.
1060    </para>
1061
1062    <para>
1063     It is possible for NoticeResponse messages to be generated due to
1064     outside activity; for example, if the database administrator commands
1065     a <quote>fast</> database shutdown, the backend will send a NoticeResponse
1066     indicating this fact before closing the connection.  Accordingly,
1067     frontends should always be prepared to accept and display NoticeResponse
1068     messages, even when the connection is nominally idle.
1069    </para>
1070
1071    <para>
1072     ParameterStatus messages will be generated whenever the active
1073     value changes for any of the parameters the backend believes the
1074     frontend should know about.  Most commonly this occurs in response
1075     to a <command>SET</> SQL command executed by the frontend, and
1076     this case is effectively synchronous &mdash; but it is also possible
1077     for parameter status changes to occur because the administrator
1078     changed a configuration file and then sent the
1079     <systemitem>SIGHUP</systemitem> signal to the server.  Also,
1080     if a <command>SET</command> command is rolled back, an appropriate
1081     ParameterStatus message will be generated to report the current
1082     effective value.
1083    </para>
1084
1085    <para>
1086     At present there is a hard-wired set of parameters for which
1087     ParameterStatus will be generated: they are
1088     <literal>server_version</>,
1089     <literal>server_encoding</>,
1090     <literal>client_encoding</>,
1091     <literal>is_superuser</>,
1092     <literal>session_authorization</>,
1093     <literal>DateStyle</>,
1094     <literal>IntervalStyle</>,
1095     <literal>TimeZone</>,
1096     <literal>integer_datetimes</>, and
1097     <literal>standard_conforming_strings</>.
1098     (<literal>server_encoding</>, <literal>TimeZone</>, and
1099     <literal>integer_datetimes</> were not reported by releases before 8.0;
1100     <literal>standard_conforming_strings</> was not reported by releases
1101     before 8.1; <literal>IntervalStyle</> was not reported by releases
1102     before 8.4.)
1103     Note that
1104     <literal>server_version</>,
1105     <literal>server_encoding</> and
1106     <literal>integer_datetimes</>
1107     are pseudo-parameters that cannot change after startup.
1108     This set might change in the future, or even become configurable.
1109     Accordingly, a frontend should simply ignore ParameterStatus for
1110     parameters that it does not understand or care about.
1111    </para>
1112
1113    <para>
1114     If a frontend issues a <command>LISTEN</command> command, then the
1115     backend will send a NotificationResponse message (not to be
1116     confused with NoticeResponse!)  whenever a
1117     <command>NOTIFY</command> command is executed for the same
1118     notification name.
1119    </para>
1120
1121    <note>
1122     <para>
1123      At present, NotificationResponse can only be sent outside a
1124      transaction, and thus it will not occur in the middle of a
1125      command-response series, though it might occur just before ReadyForQuery.
1126      It is unwise to design frontend logic that assumes that, however.
1127      Good practice is to be able to accept NotificationResponse at any
1128      point in the protocol.
1129     </para>
1130    </note>
1131   </sect2>
1132
1133   <sect2>
1134    <title>Cancelling Requests in Progress</title>
1135
1136    <para>
1137     During the processing of a query, the frontend might request
1138     cancellation of the query.  The cancel request is not sent
1139     directly on the open connection to the backend for reasons of
1140     implementation efficiency: we don't want to have the backend
1141     constantly checking for new input from the frontend during query
1142     processing.  Cancel requests should be relatively infrequent, so
1143     we make them slightly cumbersome in order to avoid a penalty in
1144     the normal case.
1145    </para>
1146
1147    <para>
1148     To issue a cancel request, the frontend opens a new connection to
1149     the server and sends a CancelRequest message, rather than the
1150     StartupMessage message that would ordinarily be sent across a new
1151     connection.  The server will process this request and then close
1152     the connection.  For security reasons, no direct reply is made to
1153     the cancel request message.
1154    </para>
1155
1156    <para>
1157     A CancelRequest message will be ignored unless it contains the
1158     same key data (PID and secret key) passed to the frontend during
1159     connection start-up.  If the request matches the PID and secret
1160     key for a currently executing backend, the processing of the
1161     current query is aborted.  (In the existing implementation, this is
1162     done by sending a special signal to the backend process that is
1163     processing the query.)
1164    </para>
1165
1166    <para>
1167     The cancellation signal might or might not have any effect &mdash; for
1168     example, if it arrives after the backend has finished processing
1169     the query, then it will have no effect.  If the cancellation is
1170     effective, it results in the current command being terminated
1171     early with an error message.
1172    </para>
1173
1174    <para>
1175     The upshot of all this is that for reasons of both security and
1176     efficiency, the frontend has no direct way to tell whether a
1177     cancel request has succeeded.  It must continue to wait for the
1178     backend to respond to the query.  Issuing a cancel simply improves
1179     the odds that the current query will finish soon, and improves the
1180     odds that it will fail with an error message instead of
1181     succeeding.
1182    </para>
1183
1184    <para>
1185     Since the cancel request is sent across a new connection to the
1186     server and not across the regular frontend/backend communication
1187     link, it is possible for the cancel request to be issued by any
1188     process, not just the frontend whose query is to be canceled.
1189     This might provide additional flexibility when building
1190     multiple-process applications.  It also introduces a security
1191     risk, in that unauthorized persons might try to cancel queries.
1192     The security risk is addressed by requiring a dynamically
1193     generated secret key to be supplied in cancel requests.
1194    </para>
1195   </sect2>
1196
1197   <sect2>
1198    <title>Termination</title>
1199
1200    <para>
1201     The normal, graceful termination procedure is that the frontend
1202     sends a Terminate message and immediately closes the connection.
1203     On receipt of this message, the backend closes the connection and
1204     terminates.
1205    </para>
1206
1207    <para>
1208     In rare cases (such as an administrator-commanded database shutdown)
1209     the backend might disconnect without any frontend request to do so.
1210     In such cases the backend will attempt to send an error or notice message
1211     giving the reason for the disconnection before it closes the connection.
1212    </para>
1213
1214    <para>
1215     Other termination scenarios arise from various failure cases, such as core
1216     dump at one end or the other, loss of the communications link, loss of
1217     message-boundary synchronization, etc.  If either frontend or backend sees
1218     an unexpected closure of the connection, it should clean
1219     up and terminate.  The frontend has the option of launching a new backend
1220     by recontacting the server if it doesn't want to terminate itself.
1221     Closing the connection is also advisable if an unrecognizable message type
1222     is received, since this probably indicates loss of message-boundary sync.
1223    </para>
1224
1225    <para>
1226     For either normal or abnormal termination, any open transaction is
1227     rolled back, not committed.  One should note however that if a
1228     frontend disconnects while a non-<command>SELECT</command> query
1229     is being processed, the backend will probably finish the query
1230     before noticing the disconnection.  If the query is outside any
1231     transaction block (<command>BEGIN</> ... <command>COMMIT</>
1232     sequence) then its results might be committed before the
1233     disconnection is recognized.
1234    </para>
1235   </sect2>
1236
1237   <sect2>
1238    <title><acronym>SSL</acronym> Session Encryption</title>
1239
1240    <para>
1241     If <productname>PostgreSQL</> was built with
1242     <acronym>SSL</acronym> support, frontend/backend communications
1243     can be encrypted using <acronym>SSL</acronym>.  This provides
1244     communication security in environments where attackers might be
1245     able to capture the session traffic. For more information on
1246     encrypting <productname>PostgreSQL</productname> sessions with
1247     <acronym>SSL</acronym>, see <xref linkend="ssl-tcp">.
1248    </para>
1249
1250    <para>
1251     To initiate an <acronym>SSL</acronym>-encrypted connection, the
1252     frontend initially sends an SSLRequest message rather than a
1253     StartupMessage.  The server then responds with a single byte
1254     containing <literal>S</> or <literal>N</>, indicating that it is
1255     willing or unwilling to perform <acronym>SSL</acronym>,
1256     respectively.  The frontend might close the connection at this point
1257     if it is dissatisfied with the response.  To continue after
1258     <literal>S</>, perform an <acronym>SSL</acronym> startup handshake
1259     (not described here, part of the <acronym>SSL</acronym>
1260     specification) with the server.  If this is successful, continue
1261     with sending the usual StartupMessage.  In this case the
1262     StartupMessage and all subsequent data will be
1263     <acronym>SSL</acronym>-encrypted.  To continue after
1264     <literal>N</>, send the usual StartupMessage and proceed without
1265     encryption.
1266    </para>
1267
1268    <para>
1269     The frontend should also be prepared to handle an ErrorMessage
1270     response to SSLRequest from the server.  This would only occur if
1271     the server predates the addition of <acronym>SSL</acronym> support
1272     to <productname>PostgreSQL</>.  In this case the connection must
1273     be closed, but the frontend might choose to open a fresh connection
1274     and proceed without requesting <acronym>SSL</acronym>.
1275    </para>
1276
1277    <para>
1278     An initial SSLRequest can also be used in a connection that is being
1279     opened to send a CancelRequest message.
1280    </para>
1281
1282    <para>
1283     While the protocol itself does not provide a way for the server to
1284     force <acronym>SSL</acronym> encryption, the administrator can
1285     configure the server to reject unencrypted sessions as a byproduct
1286     of authentication checking.
1287    </para>
1288   </sect2>
1289  </sect1>
1290
1291 <sect1 id="protocol-message-types">
1292 <title>Message Data Types</title>
1293
1294 <para>
1295 This section describes the base data types used in messages.
1296
1297 <variablelist>
1298
1299 <varlistentry>
1300 <term>
1301         Int<replaceable>n</replaceable>(<replaceable>i</replaceable>)
1302 </term>
1303 <listitem>
1304 <para>
1305                 An <replaceable>n</replaceable>-bit integer in network byte
1306                 order (most significant byte first).
1307                 If <replaceable>i</replaceable> is specified it
1308                 is the exact value that will appear, otherwise the value
1309                 is variable.  Eg. Int16, Int32(42).
1310 </para>
1311 </listitem>
1312 </varlistentry>
1313
1314 <varlistentry>
1315 <term>
1316         Int<replaceable>n</replaceable>[<replaceable>k</replaceable>]
1317 </term>
1318 <listitem>
1319 <para>
1320                 An array of <replaceable>k</replaceable>
1321                 <replaceable>n</replaceable>-bit integers, each in network
1322                 byte order.  The array length <replaceable>k</replaceable>
1323                 is always determined by an earlier field in the message.
1324                 Eg. Int16[M].
1325 </para>
1326 </listitem>
1327 </varlistentry>
1328
1329 <varlistentry>
1330 <term>
1331         String(<replaceable>s</replaceable>)
1332 </term>
1333 <listitem>
1334 <para>
1335                 A null-terminated string (C-style string).  There is no
1336                 specific length limitation on strings.
1337                 If <replaceable>s</replaceable> is specified it is the exact
1338                 value that will appear, otherwise the value is variable.
1339                 Eg. String, String("user").
1340 </para>
1341
1342 <note>
1343 <para>
1344 <emphasis>There is no predefined limit</emphasis> on the length of a string
1345 that can be returned by the backend.  Good coding strategy for a frontend
1346 is to use an expandable buffer so that anything that fits in memory can be
1347 accepted.  If that's not feasible, read the full string and discard trailing
1348 characters that don't fit into your fixed-size buffer.
1349 </para>
1350 </note>
1351 </listitem>
1352 </varlistentry>
1353
1354 <varlistentry>
1355 <term>
1356         Byte<replaceable>n</replaceable>(<replaceable>c</replaceable>)
1357 </term>
1358 <listitem>
1359 <para>
1360                 Exactly <replaceable>n</replaceable> bytes.  If the field
1361                 width <replaceable>n</replaceable> is not a constant, it is
1362                 always determinable from an earlier field in the message.
1363                 If <replaceable>c</replaceable> is specified it is the exact
1364                 value.  Eg. Byte2, Byte1('\n').
1365 </para>
1366 </listitem>
1367 </varlistentry>
1368
1369 </variablelist>
1370 </para>
1371 </sect1>
1372
1373 <sect1 id="protocol-message-formats">
1374 <title>Message Formats</title>
1375
1376 <para>
1377 This section describes the detailed format of each message.  Each is marked to
1378 indicate that it can be sent by a frontend (F), a backend (B), or both
1379 (F &amp; B).
1380 Notice that although each message includes a byte count at the beginning,
1381 the message format is defined so that the message end can be found without
1382 reference to the byte count.  This aids validity checking.  (The CopyData
1383 message is an exception, because it forms part of a data stream; the contents
1384 of any individual CopyData message cannot be interpretable on their own.)
1385 </para>
1386
1387 <variablelist>
1388
1389
1390 <varlistentry>
1391 <term>
1392 AuthenticationOk (B)
1393 </term>
1394 <listitem>
1395 <para>
1396
1397 <variablelist>
1398 <varlistentry>
1399 <term>
1400         Byte1('R')
1401 </term>
1402 <listitem>
1403 <para>
1404                 Identifies the message as an authentication request.
1405 </para>
1406 </listitem>
1407 </varlistentry>
1408 <varlistentry>
1409 <term>
1410         Int32(8)
1411 </term>
1412 <listitem>
1413 <para>
1414                 Length of message contents in bytes, including self.
1415 </para>
1416 </listitem>
1417 </varlistentry>
1418 <varlistentry>
1419 <term>
1420         Int32(0)
1421 </term>
1422 <listitem>
1423 <para>
1424                 Specifies that the authentication was successful.
1425 </para>
1426 </listitem>
1427 </varlistentry>
1428 </variablelist>
1429
1430 </para>
1431 </listitem>
1432 </varlistentry>
1433
1434
1435 <varlistentry>
1436 <term>
1437 AuthenticationKerberosV5 (B)
1438 </term>
1439 <listitem>
1440 <para>
1441
1442 <variablelist>
1443 <varlistentry>
1444 <term>
1445         Byte1('R')
1446 </term>
1447 <listitem>
1448 <para>
1449                 Identifies the message as an authentication request.
1450 </para>
1451 </listitem>
1452 </varlistentry>
1453 <varlistentry>
1454 <term>
1455         Int32(8)
1456 </term>
1457 <listitem>
1458 <para>
1459                 Length of message contents in bytes, including self.
1460 </para>
1461 </listitem>
1462 </varlistentry>
1463 <varlistentry>
1464 <term>
1465         Int32(2)
1466 </term>
1467 <listitem>
1468 <para>
1469                 Specifies that Kerberos V5 authentication is required.
1470 </para>
1471 </listitem>
1472 </varlistentry>
1473 </variablelist>
1474 </para>
1475 </listitem>
1476 </varlistentry>
1477
1478
1479 <varlistentry>
1480 <term>
1481 AuthenticationCleartextPassword (B)
1482 </term>
1483 <listitem>
1484 <para>
1485
1486 <variablelist>
1487 <varlistentry>
1488 <term>
1489         Byte1('R')
1490 </term>
1491 <listitem>
1492 <para>
1493                 Identifies the message as an authentication request.
1494 </para>
1495 </listitem>
1496 </varlistentry>
1497 <varlistentry>
1498 <term>
1499         Int32(8)
1500 </term>
1501 <listitem>
1502 <para>
1503                 Length of message contents in bytes, including self.
1504 </para>
1505 </listitem>
1506 </varlistentry>
1507 <varlistentry>
1508 <term>
1509         Int32(3)
1510 </term>
1511 <listitem>
1512 <para>
1513                 Specifies that a clear-text password is required.
1514 </para>
1515 </listitem>
1516 </varlistentry>
1517 </variablelist>
1518 </para>
1519 </listitem>
1520 </varlistentry>
1521
1522
1523 <varlistentry>
1524 <term>
1525 AuthenticationMD5Password (B)
1526 </term>
1527 <listitem>
1528 <para>
1529
1530 <variablelist>
1531 <varlistentry>
1532 <term>
1533         Byte1('R')
1534 </term>
1535 <listitem>
1536 <para>
1537                 Identifies the message as an authentication request.
1538 </para>
1539 </listitem>
1540 </varlistentry>
1541 <varlistentry>
1542 <term>
1543         Int32(12)
1544 </term>
1545 <listitem>
1546 <para>
1547                 Length of message contents in bytes, including self.
1548 </para>
1549 </listitem>
1550 </varlistentry>
1551 <varlistentry>
1552 <term>
1553         Int32(5)
1554 </term>
1555 <listitem>
1556 <para>
1557                 Specifies that an MD5-encrypted password is required.
1558 </para>
1559 </listitem>
1560 </varlistentry>
1561 <varlistentry>
1562 <term>
1563         Byte4
1564 </term>
1565 <listitem>
1566 <para>
1567                 The salt to use when encrypting the password.
1568 </para>
1569 </listitem>
1570 </varlistentry>
1571 </variablelist>
1572
1573 </para>
1574 </listitem>
1575 </varlistentry>
1576
1577
1578 <varlistentry>
1579 <term>
1580 AuthenticationSCMCredential (B)
1581 </term>
1582 <listitem>
1583 <para>
1584
1585 <variablelist>
1586 <varlistentry>
1587 <term>
1588         Byte1('R')
1589 </term>
1590 <listitem>
1591 <para>
1592                 Identifies the message as an authentication request.
1593 </para>
1594 </listitem>
1595 </varlistentry>
1596 <varlistentry>
1597 <term>
1598         Int32(8)
1599 </term>
1600 <listitem>
1601 <para>
1602                 Length of message contents in bytes, including self.
1603 </para>
1604 </listitem>
1605 </varlistentry>
1606 <varlistentry>
1607 <term>
1608         Int32(6)
1609 </term>
1610 <listitem>
1611 <para>
1612                 Specifies that an SCM credentials message is required.
1613 </para>
1614 </listitem>
1615 </varlistentry>
1616 </variablelist>
1617
1618 </para>
1619 </listitem>
1620 </varlistentry>
1621
1622
1623 <varlistentry>
1624 <term>
1625 AuthenticationGSS (B)
1626 </term>
1627 <listitem>
1628 <para>
1629
1630 <variablelist>
1631 <varlistentry>
1632 <term>
1633         Byte1('R')
1634 </term>
1635 <listitem>
1636 <para>
1637                 Identifies the message as an authentication request.
1638 </para>
1639 </listitem>
1640 </varlistentry>
1641 <varlistentry>
1642 <term>
1643         Int32(8)
1644 </term>
1645 <listitem>
1646 <para>
1647                 Length of message contents in bytes, including self.
1648 </para>
1649 </listitem>
1650 </varlistentry>
1651 <varlistentry>
1652 <term>
1653         Int32(7)
1654 </term>
1655 <listitem>
1656 <para>
1657                 Specifies that GSSAPI authentication is required.
1658 </para>
1659 </listitem>
1660 </varlistentry>
1661 </variablelist>
1662
1663 </para>
1664 </listitem>
1665 </varlistentry>
1666
1667
1668 <varlistentry>
1669 <term>
1670 AuthenticationSSPI (B)
1671 </term>
1672 <listitem>
1673 <para>
1674
1675 <variablelist>
1676 <varlistentry>
1677 <term>
1678         Byte1('R')
1679 </term>
1680 <listitem>
1681 <para>
1682                 Identifies the message as an authentication request.
1683 </para>
1684 </listitem>
1685 </varlistentry>
1686 <varlistentry>
1687 <term>
1688         Int32(8)
1689 </term>
1690 <listitem>
1691 <para>
1692                 Length of message contents in bytes, including self.
1693 </para>
1694 </listitem>
1695 </varlistentry>
1696 <varlistentry>
1697 <term>
1698         Int32(9)
1699 </term>
1700 <listitem>
1701 <para>
1702                 Specifies that SSPI authentication is required.
1703 </para>
1704 </listitem>
1705 </varlistentry>
1706 </variablelist>
1707
1708 </para>
1709 </listitem>
1710 </varlistentry>
1711 <varlistentry>
1712 <term>
1713 AuthenticationGSSContinue (B)
1714 </term>
1715 <listitem>
1716 <para>
1717
1718 <variablelist>
1719 <varlistentry>
1720 <term>
1721         Byte1('R')
1722 </term>
1723 <listitem>
1724 <para>
1725                 Identifies the message as an authentication request.
1726 </para>
1727 </listitem>
1728 </varlistentry>
1729 <varlistentry>
1730 <term>
1731         Int32
1732 </term>
1733 <listitem>
1734 <para>
1735                 Length of message contents in bytes, including self.
1736 </para>
1737 </listitem>
1738 </varlistentry>
1739 <varlistentry>
1740 <term>
1741         Int32(8)
1742 </term>
1743 <listitem>
1744 <para>
1745                 Specifies that this message contains GSSAPI or SSPI data.
1746 </para>
1747 </listitem>
1748 </varlistentry>
1749 <varlistentry>
1750 <term>
1751         Byte<replaceable>n</replaceable>
1752 </term>
1753 <listitem>
1754 <para>
1755                 GSSAPI or SSPI authentication data.
1756 </para>
1757 </listitem>
1758 </varlistentry>
1759 </variablelist>
1760
1761 </para>
1762 </listitem>
1763 </varlistentry>
1764
1765
1766 <varlistentry>
1767 <term>
1768 BackendKeyData (B)
1769 </term>
1770 <listitem>
1771 <para>
1772
1773 <variablelist>
1774 <varlistentry>
1775 <term>
1776         Byte1('K')
1777 </term>
1778 <listitem>
1779 <para>
1780                 Identifies the message as cancellation key data.
1781                 The frontend must save these values if it wishes to be
1782                 able to issue CancelRequest messages later.
1783 </para>
1784 </listitem>
1785 </varlistentry>
1786 <varlistentry>
1787 <term>
1788         Int32(12)
1789 </term>
1790 <listitem>
1791 <para>
1792                 Length of message contents in bytes, including self.
1793 </para>
1794 </listitem>
1795 </varlistentry>
1796 <varlistentry>
1797 <term>
1798         Int32
1799 </term>
1800 <listitem>
1801 <para>
1802                 The process ID of this backend.
1803 </para>
1804 </listitem>
1805 </varlistentry>
1806 <varlistentry>
1807 <term>
1808         Int32
1809 </term>
1810 <listitem>
1811 <para>
1812                 The secret key of this backend.
1813 </para>
1814 </listitem>
1815 </varlistentry>
1816 </variablelist>
1817
1818 </para>
1819 </listitem>
1820 </varlistentry>
1821
1822
1823 <varlistentry>
1824 <term>
1825 Bind (F)
1826 </term>
1827 <listitem>
1828 <para>
1829
1830 <variablelist>
1831 <varlistentry>
1832 <term>
1833         Byte1('B')
1834 </term>
1835 <listitem>
1836 <para>
1837                 Identifies the message as a Bind command.
1838 </para>
1839 </listitem>
1840 </varlistentry>
1841 <varlistentry>
1842 <term>
1843         Int32
1844 </term>
1845 <listitem>
1846 <para>
1847                 Length of message contents in bytes, including self.
1848 </para>
1849 </listitem>
1850 </varlistentry>
1851 <varlistentry>
1852 <term>
1853         String
1854 </term>
1855 <listitem>
1856 <para>
1857                 The name of the destination portal
1858                 (an empty string selects the unnamed portal).
1859 </para>
1860 </listitem>
1861 </varlistentry>
1862 <varlistentry>
1863 <term>
1864         String
1865 </term>
1866 <listitem>
1867 <para>
1868                 The name of the source prepared statement
1869                 (an empty string selects the unnamed prepared statement).
1870 </para>
1871 </listitem>
1872 </varlistentry>
1873 <varlistentry>
1874 <term>
1875         Int16
1876 </term>
1877 <listitem>
1878 <para>
1879                 The number of parameter format codes that follow
1880                 (denoted <replaceable>C</> below).
1881                 This can be zero to indicate that there are no parameters
1882                 or that the parameters all use the default format (text);
1883                 or one, in which case the specified format code is applied
1884                 to all parameters; or it can equal the actual number of
1885                 parameters.
1886 </para>
1887 </listitem>
1888 </varlistentry>
1889 <varlistentry>
1890 <term>
1891         Int16[<replaceable>C</>]
1892 </term>
1893 <listitem>
1894 <para>
1895                 The parameter format codes.  Each must presently be
1896                 zero (text) or one (binary).
1897 </para>
1898 </listitem>
1899 </varlistentry>
1900 <varlistentry>
1901 <term>
1902         Int16
1903 </term>
1904 <listitem>
1905 <para>
1906                 The number of parameter values that follow (possibly zero).
1907                 This must match the number of parameters needed by the query.
1908 </para>
1909 </listitem>
1910 </varlistentry>
1911 </variablelist>
1912         Next, the following pair of fields appear for each parameter:
1913 <variablelist>
1914 <varlistentry>
1915 <term>
1916         Int32
1917 </term>
1918 <listitem>
1919 <para>
1920                 The length of the parameter value, in bytes (this count
1921                 does not include itself).  Can be zero.
1922                 As a special case, -1 indicates a NULL parameter value.
1923                 No value bytes follow in the NULL case.
1924 </para>
1925 </listitem>
1926 </varlistentry>
1927 <varlistentry>
1928 <term>
1929         Byte<replaceable>n</replaceable>
1930 </term>
1931 <listitem>
1932 <para>
1933                 The value of the parameter, in the format indicated by the
1934                 associated format code.
1935                 <replaceable>n</replaceable> is the above length.
1936 </para>
1937 </listitem>
1938 </varlistentry>
1939 </variablelist>
1940         After the last parameter, the following fields appear:
1941 <variablelist>
1942 <varlistentry>
1943 <term>
1944         Int16
1945 </term>
1946 <listitem>
1947 <para>
1948                 The number of result-column format codes that follow
1949                 (denoted <replaceable>R</> below).
1950                 This can be zero to indicate that there are no result columns
1951                 or that the result columns should all use the default format
1952                 (text);
1953                 or one, in which case the specified format code is applied
1954                 to all result columns (if any); or it can equal the actual
1955                 number of result columns of the query.
1956 </para>
1957 </listitem>
1958 </varlistentry>
1959 <varlistentry>
1960 <term>
1961         Int16[<replaceable>R</>]
1962 </term>
1963 <listitem>
1964 <para>
1965                 The result-column format codes.  Each must presently be
1966                 zero (text) or one (binary).
1967 </para>
1968 </listitem>
1969 </varlistentry>
1970 </variablelist>
1971 </para>
1972 </listitem>
1973 </varlistentry>
1974
1975
1976 <varlistentry>
1977 <term>
1978 BindComplete (B)
1979 </term>
1980 <listitem>
1981 <para>
1982
1983 <variablelist>
1984 <varlistentry>
1985 <term>
1986         Byte1('2')
1987 </term>
1988 <listitem>
1989 <para>
1990                 Identifies the message as a Bind-complete indicator.
1991 </para>
1992 </listitem>
1993 </varlistentry>
1994 <varlistentry>
1995 <term>
1996         Int32(4)
1997 </term>
1998 <listitem>
1999 <para>
2000                 Length of message contents in bytes, including self.
2001 </para>
2002 </listitem>
2003 </varlistentry>
2004 </variablelist>
2005
2006 </para>
2007 </listitem>
2008 </varlistentry>
2009
2010
2011 <varlistentry>
2012 <term>
2013 CancelRequest (F)
2014 </term>
2015 <listitem>
2016 <para>
2017
2018 <variablelist>
2019 <varlistentry>
2020 <term>
2021         Int32(16)
2022 </term>
2023 <listitem>
2024 <para>
2025                 Length of message contents in bytes, including self.
2026 </para>
2027 </listitem>
2028 </varlistentry>
2029 <varlistentry>
2030 <term>
2031         Int32(80877102)
2032 </term>
2033 <listitem>
2034 <para>
2035                 The cancel request code.  The value is chosen to contain
2036                 <literal>1234</> in the most significant 16 bits, and <literal>5678</> in the
2037                 least 16 significant bits.  (To avoid confusion, this code
2038                 must not be the same as any protocol version number.)
2039 </para>
2040 </listitem>
2041 </varlistentry>
2042 <varlistentry>
2043 <term>
2044         Int32
2045 </term>
2046 <listitem>
2047 <para>
2048                 The process ID of the target backend.
2049 </para>
2050 </listitem>
2051 </varlistentry>
2052 <varlistentry>
2053 <term>
2054         Int32
2055 </term>
2056 <listitem>
2057 <para>
2058                 The secret key for the target backend.
2059 </para>
2060 </listitem>
2061 </varlistentry>
2062 </variablelist>
2063
2064 </para>
2065 </listitem>
2066 </varlistentry>
2067
2068
2069 <varlistentry>
2070 <term>
2071 Close (F)
2072 </term>
2073 <listitem>
2074 <para>
2075
2076 <variablelist>
2077 <varlistentry>
2078 <term>
2079         Byte1('C')
2080 </term>
2081 <listitem>
2082 <para>
2083                 Identifies the message as a Close command.
2084 </para>
2085 </listitem>
2086 </varlistentry>
2087 <varlistentry>
2088 <term>
2089         Int32
2090 </term>
2091 <listitem>
2092 <para>
2093                 Length of message contents in bytes, including self.
2094 </para>
2095 </listitem>
2096 </varlistentry>
2097 <varlistentry>
2098 <term>
2099         Byte1
2100 </term>
2101 <listitem>
2102 <para>
2103                 '<literal>S</>' to close a prepared statement; or
2104                 '<literal>P</>' to close a portal.
2105 </para>
2106 </listitem>
2107 </varlistentry>
2108 <varlistentry>
2109 <term>
2110         String
2111 </term>
2112 <listitem>
2113 <para>
2114                 The name of the prepared statement or portal to close
2115                 (an empty string selects the unnamed prepared statement
2116                 or portal).
2117 </para>
2118 </listitem>
2119 </varlistentry>
2120 </variablelist>
2121 </para>
2122 </listitem>
2123 </varlistentry>
2124
2125
2126 <varlistentry>
2127 <term>
2128 CloseComplete (B)
2129 </term>
2130 <listitem>
2131 <para>
2132
2133 <variablelist>
2134 <varlistentry>
2135 <term>
2136         Byte1('3')
2137 </term>
2138 <listitem>
2139 <para>
2140                 Identifies the message as a Close-complete indicator.
2141 </para>
2142 </listitem>
2143 </varlistentry>
2144 <varlistentry>
2145 <term>
2146         Int32(4)
2147 </term>
2148 <listitem>
2149 <para>
2150                 Length of message contents in bytes, including self.
2151 </para>
2152 </listitem>
2153 </varlistentry>
2154 </variablelist>
2155
2156 </para>
2157 </listitem>
2158 </varlistentry>
2159
2160
2161 <varlistentry>
2162 <term>
2163 CommandComplete (B)
2164 </term>
2165 <listitem>
2166 <para>
2167
2168 <variablelist>
2169 <varlistentry>
2170 <term>
2171         Byte1('C')
2172 </term>
2173 <listitem>
2174 <para>
2175                 Identifies the message as a command-completed response.
2176 </para>
2177 </listitem>
2178 </varlistentry>
2179 <varlistentry>
2180 <term>
2181         Int32
2182 </term>
2183 <listitem>
2184 <para>
2185                 Length of message contents in bytes, including self.
2186 </para>
2187 </listitem>
2188 </varlistentry>
2189 <varlistentry>
2190 <term>
2191         String
2192 </term>
2193 <listitem>
2194        <para>
2195         The command tag.  This is usually a single
2196         word that identifies which SQL command was completed.
2197        </para>
2198
2199        <para>
2200         For an <command>INSERT</command> command, the tag is
2201         <literal>INSERT <replaceable>oid</replaceable>
2202         <replaceable>rows</replaceable></literal>, where
2203         <replaceable>rows</replaceable> is the number of rows
2204         inserted. <replaceable>oid</replaceable> is the object ID
2205         of the inserted row if <replaceable>rows</replaceable> is 1
2206         and the target table has OIDs;
2207         otherwise <replaceable>oid</replaceable> is 0.
2208        </para>
2209
2210        <para>
2211         For a <command>DELETE</command> command, the tag is
2212         <literal>DELETE <replaceable>rows</replaceable></literal> where
2213         <replaceable>rows</replaceable> is the number of rows deleted.
2214        </para>
2215
2216        <para>
2217         For an <command>UPDATE</command> command, the tag is
2218         <literal>UPDATE <replaceable>rows</replaceable></literal> where
2219         <replaceable>rows</replaceable> is the number of rows updated.
2220        </para>
2221
2222        <para>
2223         For a <command>MOVE</command> command, the tag is
2224         <literal>MOVE <replaceable>rows</replaceable></literal> where
2225         <replaceable>rows</replaceable> is the number of rows the
2226         cursor's position has been changed by.
2227        </para>
2228
2229        <para>
2230         For a <command>FETCH</command> command, the tag is
2231         <literal>FETCH <replaceable>rows</replaceable></literal> where
2232         <replaceable>rows</replaceable> is the number of rows that
2233         have been retrieved from the cursor.
2234        </para>
2235
2236        <para>
2237         For a <command>COPY</command> command, the tag is
2238         <literal>COPY <replaceable>rows</replaceable></literal> where
2239         <replaceable>rows</replaceable> is the number of rows copied.
2240         (Note: the row count appears only in
2241         <productname>PostgreSQL</productname> 8.2 and later.)
2242        </para>
2243
2244 </listitem>
2245 </varlistentry>
2246 </variablelist>
2247
2248 </para>
2249 </listitem>
2250 </varlistentry>
2251
2252
2253 <varlistentry>
2254 <term>
2255 CopyData (F &amp; B)
2256 </term>
2257 <listitem>
2258 <para>
2259 <variablelist>
2260 <varlistentry>
2261 <term>
2262         Byte1('d')
2263 </term>
2264 <listitem>
2265 <para>
2266                 Identifies the message as <command>COPY</command> data.
2267 </para>
2268 </listitem>
2269 </varlistentry>
2270 <varlistentry>
2271 <term>
2272         Int32
2273 </term>
2274 <listitem>
2275 <para>
2276                 Length of message contents in bytes, including self.
2277 </para>
2278 </listitem>
2279 </varlistentry>
2280 <varlistentry>
2281 <term>
2282         Byte<replaceable>n</replaceable>
2283 </term>
2284 <listitem>
2285 <para>
2286                 Data that forms part of a <command>COPY</command> data stream.  Messages sent
2287                 from the backend will always correspond to single data rows,
2288                 but messages sent by frontends might divide the data stream
2289                 arbitrarily.
2290 </para>
2291 </listitem>
2292 </varlistentry>
2293 </variablelist>
2294 </para>
2295 </listitem>
2296 </varlistentry>
2297
2298
2299 <varlistentry>
2300 <term>
2301 CopyDone (F &amp; B)
2302 </term>
2303 <listitem>
2304 <para>
2305
2306 <variablelist>
2307 <varlistentry>
2308 <term>
2309         Byte1('c')
2310 </term>
2311 <listitem>
2312 <para>
2313                 Identifies the message as a <command>COPY</command>-complete indicator.
2314 </para>
2315 </listitem>
2316 </varlistentry>
2317 <varlistentry>
2318 <term>
2319         Int32(4)
2320 </term>
2321 <listitem>
2322 <para>
2323                 Length of message contents in bytes, including self.
2324 </para>
2325 </listitem>
2326 </varlistentry>
2327 </variablelist>
2328
2329 </para>
2330 </listitem>
2331 </varlistentry>
2332
2333
2334 <varlistentry>
2335 <term>
2336 CopyFail (F)
2337 </term>
2338 <listitem>
2339 <para>
2340
2341 <variablelist>
2342 <varlistentry>
2343 <term>
2344         Byte1('f')
2345 </term>
2346 <listitem>
2347 <para>
2348                 Identifies the message as a <command>COPY</command>-failure indicator.
2349 </para>
2350 </listitem>
2351 </varlistentry>
2352 <varlistentry>
2353 <term>
2354         Int32
2355 </term>
2356 <listitem>
2357 <para>
2358                 Length of message contents in bytes, including self.
2359 </para>
2360 </listitem>
2361 </varlistentry>
2362 <varlistentry>
2363 <term>
2364         String
2365 </term>
2366 <listitem>
2367 <para>
2368                 An error message to report as the cause of failure.
2369 </para>
2370 </listitem>
2371 </varlistentry>
2372 </variablelist>
2373
2374 </para>
2375 </listitem>
2376 </varlistentry>
2377
2378
2379 <varlistentry>
2380 <term>
2381 CopyInResponse (B)
2382 </term>
2383 <listitem>
2384 <para>
2385
2386 <variablelist>
2387 <varlistentry>
2388 <term>
2389         Byte1('G')
2390 </term>
2391 <listitem>
2392 <para>
2393                 Identifies the message as a Start Copy In response.
2394                 The frontend must now send copy-in data (if not
2395                 prepared to do so, send a CopyFail message).
2396 </para>
2397 </listitem>
2398 </varlistentry>
2399 <varlistentry>
2400 <term>
2401         Int32
2402 </term>
2403 <listitem>
2404 <para>
2405                 Length of message contents in bytes, including self.
2406 </para>
2407 </listitem>
2408 </varlistentry>
2409 <varlistentry>
2410 <term>
2411         Int8
2412 </term>
2413 <listitem>
2414 <para>
2415                 0 indicates the overall <command>COPY</command> format is textual (rows
2416                 separated by newlines, columns separated by separator
2417                 characters, etc).
2418                 1 indicates the overall copy format is binary (similar
2419                 to DataRow format).
2420                 See <xref linkend="sql-copy" endterm="sql-copy-title">
2421                 for more information.
2422 </para>
2423 </listitem>
2424 </varlistentry>
2425 <varlistentry>
2426 <term>
2427         Int16
2428 </term>
2429 <listitem>
2430 <para>
2431                 The number of columns in the data to be copied
2432                 (denoted <replaceable>N</> below).
2433 </para>
2434 </listitem>
2435 </varlistentry>
2436 <varlistentry>
2437 <term>
2438         Int16[<replaceable>N</>]
2439 </term>
2440 <listitem>
2441 <para>
2442                 The format codes to be used for each column.
2443                 Each must presently be zero (text) or one (binary).
2444                 All must be zero if the overall copy format is textual.
2445 </para>
2446 </listitem>
2447 </varlistentry>
2448 </variablelist>
2449
2450 </para>
2451 </listitem>
2452 </varlistentry>
2453
2454
2455 <varlistentry>
2456 <term>
2457 CopyOutResponse (B)
2458 </term>
2459 <listitem>
2460 <para>
2461
2462 <variablelist>
2463 <varlistentry>
2464 <term>
2465         Byte1('H')
2466 </term>
2467 <listitem>
2468 <para>
2469                 Identifies the message as a Start Copy Out response.
2470                 This message will be followed by copy-out data.
2471 </para>
2472 </listitem>
2473 </varlistentry>
2474 <varlistentry>
2475 <term>
2476         Int32
2477 </term>
2478 <listitem>
2479 <para>
2480                 Length of message contents in bytes, including self.
2481 </para>
2482 </listitem>
2483 </varlistentry>
2484 <varlistentry>
2485 <term>
2486         Int8
2487 </term>
2488 <listitem>
2489 <para>
2490                 0 indicates the overall <command>COPY</command> format
2491                 is textual (rows separated by newlines, columns
2492                 separated by separator characters, etc). 1 indicates
2493                 the overall copy format is binary (similar to DataRow
2494                 format). See <xref linkend="sql-copy"
2495                 endterm="sql-copy-title"> for more information.
2496 </para>
2497 </listitem>
2498 </varlistentry>
2499 <varlistentry>
2500 <term>
2501         Int16
2502 </term>
2503 <listitem>
2504 <para>
2505                 The number of columns in the data to be copied
2506                 (denoted <replaceable>N</> below).
2507 </para>
2508 </listitem>
2509 </varlistentry>
2510 <varlistentry>
2511 <term>
2512         Int16[<replaceable>N</>]
2513 </term>
2514 <listitem>
2515 <para>
2516                 The format codes to be used for each column.
2517                 Each must presently be zero (text) or one (binary).
2518                 All must be zero if the overall copy format is textual.
2519 </para>
2520 </listitem>
2521 </varlistentry>
2522 </variablelist>
2523
2524 </para>
2525 </listitem>
2526 </varlistentry>
2527
2528
2529 <varlistentry>
2530 <term>
2531 DataRow (B)
2532 </term>
2533 <listitem>
2534 <para>
2535 <variablelist>
2536 <varlistentry>
2537 <term>
2538         Byte1('D')
2539 </term>
2540 <listitem>
2541 <para>
2542                 Identifies the message as a data row.
2543 </para>
2544 </listitem>
2545 </varlistentry>
2546 <varlistentry>
2547 <term>
2548         Int32
2549 </term>
2550 <listitem>
2551 <para>
2552                 Length of message contents in bytes, including self.
2553 </para>
2554 </listitem>
2555 </varlistentry>
2556 <varlistentry>
2557 <term>
2558         Int16
2559 </term>
2560 <listitem>
2561 <para>
2562                 The number of column values that follow (possibly zero).
2563 </para>
2564 </listitem>
2565 </varlistentry>
2566 </variablelist>
2567         Next, the following pair of fields appear for each column:
2568 <variablelist>
2569 <varlistentry>
2570 <term>
2571         Int32
2572 </term>
2573 <listitem>
2574 <para>
2575                 The length of the column value, in bytes (this count
2576                 does not include itself).  Can be zero.
2577                 As a special case, -1 indicates a NULL column value.
2578                 No value bytes follow in the NULL case.
2579 </para>
2580 </listitem>
2581 </varlistentry>
2582 <varlistentry>
2583 <term>
2584         Byte<replaceable>n</replaceable>
2585 </term>
2586 <listitem>
2587 <para>
2588                 The value of the column, in the format indicated by the
2589                 associated format code.
2590                 <replaceable>n</replaceable> is the above length.
2591 </para>
2592 </listitem>
2593 </varlistentry>
2594 </variablelist>
2595
2596 </para>
2597 </listitem>
2598 </varlistentry>
2599
2600
2601 <varlistentry>
2602 <term>
2603 Describe (F)
2604 </term>
2605 <listitem>
2606 <para>
2607
2608 <variablelist>
2609 <varlistentry>
2610 <term>
2611         Byte1('D')
2612 </term>
2613 <listitem>
2614 <para>
2615                 Identifies the message as a Describe command.
2616 </para>
2617 </listitem>
2618 </varlistentry>
2619 <varlistentry>
2620 <term>
2621         Int32
2622 </term>
2623 <listitem>
2624 <para>
2625                 Length of message contents in bytes, including self.
2626 </para>
2627 </listitem>
2628 </varlistentry>
2629 <varlistentry>
2630 <term>
2631         Byte1
2632 </term>
2633 <listitem>
2634 <para>
2635                 '<literal>S</>' to describe a prepared statement; or
2636                 '<literal>P</>' to describe a portal.
2637 </para>
2638 </listitem>
2639 </varlistentry>
2640 <varlistentry>
2641 <term>
2642         String
2643 </term>
2644 <listitem>
2645 <para>
2646                 The name of the prepared statement or portal to describe
2647                 (an empty string selects the unnamed prepared statement
2648                 or portal).
2649 </para>
2650 </listitem>
2651 </varlistentry>
2652 </variablelist>
2653 </para>
2654 </listitem>
2655 </varlistentry>
2656
2657
2658 <varlistentry>
2659 <term>
2660 EmptyQueryResponse (B)
2661 </term>
2662 <listitem>
2663 <para>
2664
2665 <variablelist>
2666 <varlistentry>
2667 <term>
2668         Byte1('I')
2669 </term>
2670 <listitem>
2671 <para>
2672                 Identifies the message as a response to an empty query string.
2673                 (This substitutes for CommandComplete.)
2674 </para>
2675 </listitem>
2676 </varlistentry>
2677 <varlistentry>
2678 <term>
2679         Int32(4)
2680 </term>
2681 <listitem>
2682 <para>
2683                 Length of message contents in bytes, including self.
2684 </para>
2685 </listitem>
2686 </varlistentry>
2687 </variablelist>
2688
2689 </para>
2690 </listitem>
2691 </varlistentry>
2692
2693
2694 <varlistentry>
2695 <term>
2696 ErrorResponse (B)
2697 </term>
2698 <listitem>
2699 <para>
2700
2701 <variablelist>
2702 <varlistentry>
2703 <term>
2704         Byte1('E')
2705 </term>
2706 <listitem>
2707 <para>
2708                 Identifies the message as an error.
2709 </para>
2710 </listitem>
2711 </varlistentry>
2712 <varlistentry>
2713 <term>
2714         Int32
2715 </term>
2716 <listitem>
2717 <para>
2718                 Length of message contents in bytes, including self.
2719 </para>
2720 </listitem>
2721 </varlistentry>
2722 </variablelist>
2723         The message body consists of one or more identified fields,
2724         followed by a zero byte as a terminator.  Fields can appear in
2725         any order.  For each field there is the following:
2726 <variablelist>
2727 <varlistentry>
2728 <term>
2729         Byte1
2730 </term>
2731 <listitem>
2732 <para>
2733                 A code identifying the field type; if zero, this is
2734                 the message terminator and no string follows.
2735                 The presently defined field types are listed in
2736                 <xref linkend="protocol-error-fields">.
2737                 Since more field types might be added in future,
2738                 frontends should silently ignore fields of unrecognized
2739                 type.
2740 </para>
2741 </listitem>
2742 </varlistentry>
2743 <varlistentry>
2744 <term>
2745         String
2746 </term>
2747 <listitem>
2748 <para>
2749                 The field value.
2750 </para>
2751 </listitem>
2752 </varlistentry>
2753 </variablelist>
2754
2755 </para>
2756 </listitem>
2757 </varlistentry>
2758
2759
2760 <varlistentry>
2761 <term>
2762 Execute (F)
2763 </term>
2764 <listitem>
2765 <para>
2766
2767 <variablelist>
2768 <varlistentry>
2769 <term>
2770         Byte1('E')
2771 </term>
2772 <listitem>
2773 <para>
2774                 Identifies the message as an Execute command.
2775 </para>
2776 </listitem>
2777 </varlistentry>
2778 <varlistentry>
2779 <term>
2780         Int32
2781 </term>
2782 <listitem>
2783 <para>
2784                 Length of message contents in bytes, including self.
2785 </para>
2786 </listitem>
2787 </varlistentry>
2788 <varlistentry>
2789 <term>
2790         String
2791 </term>
2792 <listitem>
2793 <para>
2794                 The name of the portal to execute
2795                 (an empty string selects the unnamed portal).
2796 </para>
2797 </listitem>
2798 </varlistentry>
2799 <varlistentry>
2800 <term>
2801         Int32
2802 </term>
2803 <listitem>
2804 <para>
2805                 Maximum number of rows to return, if portal contains
2806                 a query that returns rows (ignored otherwise).  Zero
2807                 denotes <quote>no limit</>.
2808 </para>
2809 </listitem>
2810 </varlistentry>
2811 </variablelist>
2812 </para>
2813 </listitem>
2814 </varlistentry>
2815
2816
2817 <varlistentry>
2818 <term>
2819 Flush (F)
2820 </term>
2821 <listitem>
2822 <para>
2823
2824 <variablelist>
2825 <varlistentry>
2826 <term>
2827         Byte1('H')
2828 </term>
2829 <listitem>
2830 <para>
2831                 Identifies the message as a Flush command.
2832 </para>
2833 </listitem>
2834 </varlistentry>
2835 <varlistentry>
2836 <term>
2837         Int32(4)
2838 </term>
2839 <listitem>
2840 <para>
2841                 Length of message contents in bytes, including self.
2842 </para>
2843 </listitem>
2844 </varlistentry>
2845 </variablelist>
2846
2847 </para>
2848 </listitem>
2849 </varlistentry>
2850
2851
2852 <varlistentry>
2853 <term>
2854 FunctionCall (F)
2855 </term>
2856 <listitem>
2857 <para>
2858
2859 <variablelist>
2860 <varlistentry>
2861 <term>
2862         Byte1('F')
2863 </term>
2864 <listitem>
2865 <para>
2866                 Identifies the message as a function call.
2867 </para>
2868 </listitem>
2869 </varlistentry>
2870 <varlistentry>
2871 <term>
2872         Int32
2873 </term>
2874 <listitem>
2875 <para>
2876                 Length of message contents in bytes, including self.
2877 </para>
2878 </listitem>
2879 </varlistentry>
2880 <varlistentry>
2881 <term>
2882         Int32
2883 </term>
2884 <listitem>
2885 <para>
2886                 Specifies the object ID of the function to call.
2887 </para>
2888 </listitem>
2889 </varlistentry>
2890 <varlistentry>
2891 <term>
2892         Int16
2893 </term>
2894 <listitem>
2895 <para>
2896                 The number of argument format codes that follow
2897                 (denoted <replaceable>C</> below).
2898                 This can be zero to indicate that there are no arguments
2899                 or that the arguments all use the default format (text);
2900                 or one, in which case the specified format code is applied
2901                 to all arguments; or it can equal the actual number of
2902                 arguments.
2903 </para>
2904 </listitem>
2905 </varlistentry>
2906 <varlistentry>
2907 <term>
2908         Int16[<replaceable>C</>]
2909 </term>
2910 <listitem>
2911 <para>
2912                 The argument format codes.  Each must presently be
2913                 zero (text) or one (binary).
2914 </para>
2915 </listitem>
2916 </varlistentry>
2917 <varlistentry>
2918 <term>
2919         Int16
2920 </term>
2921 <listitem>
2922 <para>
2923                 Specifies the number of arguments being supplied to the
2924                 function.
2925 </para>
2926 </listitem>
2927 </varlistentry>
2928 </variablelist>
2929         Next, the following pair of fields appear for each argument:
2930 <variablelist>
2931 <varlistentry>
2932 <term>
2933         Int32
2934 </term>
2935 <listitem>
2936 <para>
2937                 The length of the argument value, in bytes (this count
2938                 does not include itself).  Can be zero.
2939                 As a special case, -1 indicates a NULL argument value.
2940                 No value bytes follow in the NULL case.
2941 </para>
2942 </listitem>
2943 </varlistentry>
2944 <varlistentry>
2945 <term>
2946         Byte<replaceable>n</replaceable>
2947 </term>
2948 <listitem>
2949 <para>
2950                 The value of the argument, in the format indicated by the
2951                 associated format code.
2952                 <replaceable>n</replaceable> is the above length.
2953 </para>
2954 </listitem>
2955 </varlistentry>
2956 </variablelist>
2957         After the last argument, the following field appears:
2958 <variablelist>
2959 <varlistentry>
2960 <term>
2961         Int16
2962 </term>
2963 <listitem>
2964 <para>
2965                 The format code for the function result. Must presently be
2966                 zero (text) or one (binary).
2967 </para>
2968 </listitem>
2969 </varlistentry>
2970 </variablelist>
2971
2972 </para>
2973 </listitem>
2974 </varlistentry>
2975
2976
2977 <varlistentry>
2978 <term>
2979 FunctionCallResponse (B)
2980 </term>
2981 <listitem>
2982 <para>
2983
2984 <variablelist>
2985 <varlistentry>
2986 <term>
2987         Byte1('V')
2988 </term>
2989 <listitem>
2990 <para>
2991                 Identifies the message as a function call result.
2992 </para>
2993 </listitem>
2994 </varlistentry>
2995 <varlistentry>
2996 <term>
2997         Int32
2998 </term>
2999 <listitem>
3000 <para>
3001                 Length of message contents in bytes, including self.
3002 </para>
3003 </listitem>
3004 </varlistentry>
3005 <varlistentry>
3006 <term>
3007         Int32
3008 </term>
3009 <listitem>
3010 <para>
3011                 The length of the function result value, in bytes (this count
3012                 does not include itself).  Can be zero.
3013                 As a special case, -1 indicates a NULL function result.
3014                 No value bytes follow in the NULL case.
3015 </para>
3016 </listitem>
3017 </varlistentry>
3018 <varlistentry>
3019 <term>
3020         Byte<replaceable>n</replaceable>
3021 </term>
3022 <listitem>
3023 <para>
3024                 The value of the function result, in the format indicated by
3025                 the associated format code.
3026                 <replaceable>n</replaceable> is the above length.
3027 </para>
3028 </listitem>
3029 </varlistentry>
3030 </variablelist>
3031
3032 </para>
3033 </listitem>
3034 </varlistentry>
3035
3036
3037 <varlistentry>
3038 <term>
3039 NoData (B)
3040 </term>
3041 <listitem>
3042 <para>
3043
3044 <variablelist>
3045 <varlistentry>
3046 <term>
3047         Byte1('n')
3048 </term>
3049 <listitem>
3050 <para>
3051                 Identifies the message as a no-data indicator.
3052 </para>
3053 </listitem>
3054 </varlistentry>
3055 <varlistentry>
3056 <term>
3057         Int32(4)
3058 </term>
3059 <listitem>
3060 <para>
3061                 Length of message contents in bytes, including self.
3062 </para>
3063 </listitem>
3064 </varlistentry>
3065 </variablelist>
3066
3067 </para>
3068 </listitem>
3069 </varlistentry>
3070
3071
3072 <varlistentry>
3073 <term>
3074 NoticeResponse (B)
3075 </term>
3076 <listitem>
3077 <para>
3078
3079 <variablelist>
3080 <varlistentry>
3081 <term>
3082         Byte1('N')
3083 </term>
3084 <listitem>
3085 <para>
3086                 Identifies the message as a notice.
3087 </para>
3088 </listitem>
3089 </varlistentry>
3090 <varlistentry>
3091 <term>
3092         Int32
3093 </term>
3094 <listitem>
3095 <para>
3096                 Length of message contents in bytes, including self.
3097 </para>
3098 </listitem>
3099 </varlistentry>
3100 </variablelist>
3101         The message body consists of one or more identified fields,
3102         followed by a zero byte as a terminator.  Fields can appear in
3103         any order.  For each field there is the following:
3104 <variablelist>
3105 <varlistentry>
3106 <term>
3107         Byte1
3108 </term>
3109 <listitem>
3110 <para>
3111                 A code identifying the field type; if zero, this is
3112                 the message terminator and no string follows.
3113                 The presently defined field types are listed in
3114                 <xref linkend="protocol-error-fields">.
3115                 Since more field types might be added in future,
3116                 frontends should silently ignore fields of unrecognized
3117                 type.
3118 </para>
3119 </listitem>
3120 </varlistentry>
3121 <varlistentry>
3122 <term>
3123         String
3124 </term>
3125 <listitem>
3126 <para>
3127                 The field value.
3128 </para>
3129 </listitem>
3130 </varlistentry>
3131 </variablelist>
3132
3133 </para>
3134 </listitem>
3135 </varlistentry>
3136
3137
3138 <varlistentry>
3139 <term>
3140 NotificationResponse (B)
3141 </term>
3142 <listitem>
3143 <para>
3144
3145 <variablelist>
3146 <varlistentry>
3147 <term>
3148         Byte1('A')
3149 </term>
3150 <listitem>
3151 <para>
3152                 Identifies the message as a notification response.
3153 </para>
3154 </listitem>
3155 </varlistentry>
3156 <varlistentry>
3157 <term>
3158         Int32
3159 </term>
3160 <listitem>
3161 <para>
3162                 Length of message contents in bytes, including self.
3163 </para>
3164 </listitem>
3165 </varlistentry>
3166 <varlistentry>
3167 <term>
3168         Int32
3169 </term>
3170 <listitem>
3171 <para>
3172                 The process ID of the notifying backend process.
3173 </para>
3174 </listitem>
3175 </varlistentry>
3176 <varlistentry>
3177 <term>
3178         String
3179 </term>
3180 <listitem>
3181 <para>
3182                 The name of the condition that the notify has been raised on.
3183 </para>
3184 </listitem>
3185 </varlistentry>
3186 <varlistentry>
3187 <term>
3188         String
3189 </term>
3190 <listitem>
3191 <para>
3192                 Additional information passed from the notifying process.
3193                 (Currently, this feature is unimplemented so the field
3194                 is always an empty string.)
3195 </para>
3196 </listitem>
3197 </varlistentry>
3198 </variablelist>
3199
3200 </para>
3201 </listitem>
3202 </varlistentry>
3203
3204
3205 <varlistentry>
3206 <term>
3207 ParameterDescription (B)
3208 </term>
3209 <listitem>
3210 <para>
3211
3212 <variablelist>
3213 <varlistentry>
3214 <term>
3215         Byte1('t')
3216 </term>
3217 <listitem>
3218 <para>
3219                 Identifies the message as a parameter description.
3220 </para>
3221 </listitem>
3222 </varlistentry>
3223 <varlistentry>
3224 <term>
3225         Int32
3226 </term>
3227 <listitem>
3228 <para>
3229                 Length of message contents in bytes, including self.
3230 </para>
3231 </listitem>
3232 </varlistentry>
3233 <varlistentry>
3234 <term>
3235         Int16
3236 </term>
3237 <listitem>
3238 <para>
3239                 The number of parameters used by the statement
3240                 (can be zero).
3241 </para>
3242 </listitem>
3243 </varlistentry>
3244 </variablelist>
3245         Then, for each parameter, there is the following:
3246 <variablelist>
3247 <varlistentry>
3248 <term>
3249         Int32
3250 </term>
3251 <listitem>
3252 <para>
3253                 Specifies the object ID of the parameter data type.
3254 </para>
3255 </listitem>
3256 </varlistentry>
3257 </variablelist>
3258 </para>
3259 </listitem>
3260 </varlistentry>
3261
3262
3263 <varlistentry>
3264 <term>
3265 ParameterStatus (B)
3266 </term>
3267 <listitem>
3268 <para>
3269
3270 <variablelist>
3271 <varlistentry>
3272 <term>
3273         Byte1('S')
3274 </term>
3275 <listitem>
3276 <para>
3277                 Identifies the message as a run-time parameter status report.
3278 </para>
3279 </listitem>
3280 </varlistentry>
3281 <varlistentry>
3282 <term>
3283         Int32
3284 </term>
3285 <listitem>
3286 <para>
3287                 Length of message contents in bytes, including self.
3288 </para>
3289 </listitem>
3290 </varlistentry>
3291 <varlistentry>
3292 <term>
3293         String
3294 </term>
3295 <listitem>
3296 <para>
3297                 The name of the run-time parameter being reported.
3298 </para>
3299 </listitem>
3300 </varlistentry>
3301 <varlistentry>
3302 <term>
3303         String
3304 </term>
3305 <listitem>
3306 <para>
3307                 The current value of the parameter.
3308 </para>
3309 </listitem>
3310 </varlistentry>
3311 </variablelist>
3312 </para>
3313 </listitem>
3314 </varlistentry>
3315
3316
3317 <varlistentry>
3318 <term>
3319 Parse (F)
3320 </term>
3321 <listitem>
3322 <para>
3323
3324 <variablelist>
3325 <varlistentry>
3326 <term>
3327         Byte1('P')
3328 </term>
3329 <listitem>
3330 <para>
3331                 Identifies the message as a Parse command.
3332 </para>
3333 </listitem>
3334 </varlistentry>
3335 <varlistentry>
3336 <term>
3337         Int32
3338 </term>
3339 <listitem>
3340 <para>
3341                 Length of message contents in bytes, including self.
3342 </para>
3343 </listitem>
3344 </varlistentry>
3345 <varlistentry>
3346 <term>
3347         String
3348 </term>
3349 <listitem>
3350 <para>
3351                 The name of the destination prepared statement
3352                 (an empty string selects the unnamed prepared statement).
3353 </para>
3354 </listitem>
3355 </varlistentry>
3356 <varlistentry>
3357 <term>
3358         String
3359 </term>
3360 <listitem>
3361 <para>
3362                 The query string to be parsed.
3363 </para>
3364 </listitem>
3365 </varlistentry>
3366 <varlistentry>
3367 <term>
3368         Int16
3369 </term>
3370 <listitem>
3371 <para>
3372                 The number of parameter data types specified
3373                 (can be zero).  Note that this is not an indication of
3374                 the number of parameters that might appear in the
3375                 query string, only the number that the frontend wants to
3376                 prespecify types for.
3377 </para>
3378 </listitem>
3379 </varlistentry>
3380 </variablelist>
3381         Then, for each parameter, there is the following:
3382 <variablelist>
3383 <varlistentry>
3384 <term>
3385         Int32
3386 </term>
3387 <listitem>
3388 <para>
3389                 Specifies the object ID of the parameter data type.
3390                 Placing a zero here is equivalent to leaving the type
3391                 unspecified.
3392 </para>
3393 </listitem>
3394 </varlistentry>
3395 </variablelist>
3396 </para>
3397 </listitem>
3398 </varlistentry>
3399
3400
3401 <varlistentry>
3402 <term>
3403 ParseComplete (B)
3404 </term>
3405 <listitem>
3406 <para>
3407
3408 <variablelist>
3409 <varlistentry>
3410 <term>
3411         Byte1('1')
3412 </term>
3413 <listitem>
3414 <para>
3415                 Identifies the message as a Parse-complete indicator.
3416 </para>
3417 </listitem>
3418 </varlistentry>
3419 <varlistentry>
3420 <term>
3421         Int32(4)
3422 </term>
3423 <listitem>
3424 <para>
3425                 Length of message contents in bytes, including self.
3426 </para>
3427 </listitem>
3428 </varlistentry>
3429 </variablelist>
3430
3431 </para>
3432 </listitem>
3433 </varlistentry>
3434
3435
3436 <varlistentry>
3437 <term>
3438 PasswordMessage (F)
3439 </term>
3440 <listitem>
3441 <para>
3442
3443 <variablelist>
3444 <varlistentry>
3445 <term>
3446         Byte1('p')
3447 </term>
3448 <listitem>
3449 <para>
3450                 Identifies the message as a password response. Note that
3451                 this is also used for GSSAPI and SSPI response messages
3452                 (which is really a design error, since the contained data
3453                 is not a null-terminated string in that case, but can be
3454                 arbitrary binary data).
3455 </para>
3456 </listitem>
3457 </varlistentry>
3458 <varlistentry>
3459 <term>
3460         Int32
3461 </term>
3462 <listitem>
3463 <para>
3464                 Length of message contents in bytes, including self.
3465 </para>
3466 </listitem>
3467 </varlistentry>
3468 <varlistentry>
3469 <term>
3470         String
3471 </term>
3472 <listitem>
3473 <para>
3474                 The password (encrypted, if requested).
3475 </para>
3476 </listitem>
3477 </varlistentry>
3478 </variablelist>
3479 </para>
3480 </listitem>
3481 </varlistentry>
3482
3483
3484 <varlistentry>
3485 <term>
3486 PortalSuspended (B)
3487 </term>
3488 <listitem>
3489 <para>
3490
3491 <variablelist>
3492 <varlistentry>
3493 <term>
3494         Byte1('s')
3495 </term>
3496 <listitem>
3497 <para>
3498                 Identifies the message as a portal-suspended indicator.
3499                 Note this only appears if an Execute message's row-count limit
3500                 was reached.
3501 </para>
3502 </listitem>
3503 </varlistentry>
3504 <varlistentry>
3505 <term>
3506         Int32(4)
3507 </term>
3508 <listitem>
3509 <para>
3510                 Length of message contents in bytes, including self.
3511 </para>
3512 </listitem>
3513 </varlistentry>
3514 </variablelist>
3515
3516 </para>
3517 </listitem>
3518 </varlistentry>
3519
3520
3521 <varlistentry>
3522 <term>
3523 Query (F)
3524 </term>
3525 <listitem>
3526 <para>
3527
3528 <variablelist>
3529 <varlistentry>
3530 <term>
3531         Byte1('Q')
3532 </term>
3533 <listitem>
3534 <para>
3535                 Identifies the message as a simple query.
3536 </para>
3537 </listitem>
3538 </varlistentry>
3539 <varlistentry>
3540 <term>
3541         Int32
3542 </term>
3543 <listitem>
3544 <para>
3545                 Length of message contents in bytes, including self.
3546 </para>
3547 </listitem>
3548 </varlistentry>
3549 <varlistentry>
3550 <term>
3551         String
3552 </term>
3553 <listitem>
3554 <para>
3555                 The query string itself.
3556 </para>
3557 </listitem>
3558 </varlistentry>
3559 </variablelist>
3560
3561 </para>
3562 </listitem>
3563 </varlistentry>
3564
3565
3566 <varlistentry>
3567 <term>
3568 ReadyForQuery (B)
3569 </term>
3570 <listitem>
3571 <para>
3572
3573 <variablelist>
3574 <varlistentry>
3575 <term>
3576         Byte1('Z')
3577 </term>
3578 <listitem>
3579 <para>
3580                 Identifies the message type.  ReadyForQuery is sent
3581                 whenever the backend is ready for a new query cycle.
3582 </para>
3583 </listitem>
3584 </varlistentry>
3585 <varlistentry>
3586 <term>
3587         Int32(5)
3588 </term>
3589 <listitem>
3590 <para>
3591                 Length of message contents in bytes, including self.
3592 </para>
3593 </listitem>
3594 </varlistentry>
3595 <varlistentry>
3596 <term>
3597         Byte1
3598 </term>
3599 <listitem>
3600 <para>
3601                 Current backend transaction status indicator.
3602                 Possible values are '<literal>I</>' if idle (not in
3603                 a transaction block); '<literal>T</>' if in a transaction
3604                 block; or '<literal>E</>' if in a failed transaction
3605                 block (queries will be rejected until block is ended).
3606 </para>
3607 </listitem>
3608 </varlistentry>
3609 </variablelist>
3610
3611 </para>
3612 </listitem>
3613 </varlistentry>
3614
3615
3616 <varlistentry>
3617 <term>
3618 RowDescription (B)
3619 </term>
3620 <listitem>
3621 <para>
3622
3623 <variablelist>
3624 <varlistentry>
3625 <term>
3626         Byte1('T')
3627 </term>
3628 <listitem>
3629 <para>
3630                 Identifies the message as a row description.
3631 </para>
3632 </listitem>
3633 </varlistentry>
3634 <varlistentry>
3635 <term>
3636         Int32
3637 </term>
3638 <listitem>
3639 <para>
3640                 Length of message contents in bytes, including self.
3641 </para>
3642 </listitem>
3643 </varlistentry>
3644 <varlistentry>
3645 <term>
3646         Int16
3647 </term>
3648 <listitem>
3649 <para>
3650                 Specifies the number of fields in a row (can be zero).
3651 </para>
3652 </listitem>
3653 </varlistentry>
3654 </variablelist>
3655         Then, for each field, there is the following:
3656 <variablelist>
3657 <varlistentry>
3658 <term>
3659         String
3660 </term>
3661 <listitem>
3662 <para>
3663                 The field name.
3664 </para>
3665 </listitem>
3666 </varlistentry>
3667 <varlistentry>
3668 <term>
3669         Int32
3670 </term>
3671 <listitem>
3672 <para>
3673                 If the field can be identified as a column of a specific
3674                 table, the object ID of the table; otherwise zero.
3675 </para>
3676 </listitem>
3677 </varlistentry>
3678 <varlistentry>
3679 <term>
3680         Int16
3681 </term>
3682 <listitem>
3683 <para>
3684                 If the field can be identified as a column of a specific
3685                 table, the attribute number of the column; otherwise zero.
3686 </para>
3687 </listitem>
3688 </varlistentry>
3689 <varlistentry>
3690 <term>
3691         Int32
3692 </term>
3693 <listitem>
3694 <para>
3695                 The object ID of the field's data type.
3696 </para>
3697 </listitem>
3698 </varlistentry>
3699 <varlistentry>
3700 <term>
3701         Int16
3702 </term>
3703 <listitem>
3704 <para>
3705                 The data type size (see <varname>pg_type.typlen</>).
3706                 Note that negative values denote variable-width types.
3707 </para>
3708 </listitem>
3709 </varlistentry>
3710 <varlistentry>
3711 <term>
3712         Int32
3713 </term>
3714 <listitem>
3715 <para>
3716                 The type modifier (see <varname>pg_attribute.atttypmod</>).
3717                 The meaning of the modifier is type-specific.
3718 </para>
3719 </listitem>
3720 </varlistentry>
3721 <varlistentry>
3722 <term>
3723         Int16
3724 </term>
3725 <listitem>
3726 <para>
3727                 The format code being used for the field.  Currently will
3728                 be zero (text) or one (binary).  In a RowDescription
3729                 returned from the statement variant of Describe, the
3730                 format code is not yet known and will always be zero.
3731 </para>
3732 </listitem>
3733 </varlistentry>
3734 </variablelist>
3735
3736 </para>
3737 </listitem>
3738 </varlistentry>
3739
3740
3741 <varlistentry>
3742 <term>
3743 SSLRequest (F)
3744 </term>
3745 <listitem>
3746 <para>
3747
3748 <variablelist>
3749 <varlistentry>
3750 <term>
3751         Int32(8)
3752 </term>
3753 <listitem>
3754 <para>
3755                 Length of message contents in bytes, including self.
3756 </para>
3757 </listitem>
3758 </varlistentry>
3759 <varlistentry>
3760 <term>
3761         Int32(80877103)
3762 </term>
3763 <listitem>
3764 <para>
3765                 The <acronym>SSL</acronym> request code.  The value is chosen to contain
3766                 <literal>1234</> in the most significant 16 bits, and <literal>5679</> in the
3767                 least 16 significant bits.  (To avoid confusion, this code
3768                 must not be the same as any protocol version number.)
3769 </para>
3770 </listitem>
3771 </varlistentry>
3772 </variablelist>
3773
3774 </para>
3775 </listitem>
3776 </varlistentry>
3777
3778
3779 <varlistentry>
3780 <term>
3781 StartupMessage (F)
3782 </term>
3783 <listitem>
3784 <para>
3785
3786 <variablelist>
3787 <varlistentry>
3788 <term>
3789         Int32
3790 </term>
3791 <listitem>
3792 <para>
3793                 Length of message contents in bytes, including self.
3794 </para>
3795 </listitem>
3796 </varlistentry>
3797 <varlistentry>
3798 <term>
3799         Int32(196608)
3800 </term>
3801 <listitem>
3802 <para>
3803                 The protocol version number.  The most significant 16 bits are
3804                 the major version number (3 for the protocol described here).
3805                 The least significant 16 bits are the minor version number
3806                 (0 for the protocol described here).
3807 </para>
3808 </listitem>
3809 </varlistentry>
3810 </variablelist>
3811         The protocol version number is followed by one or more pairs of
3812         parameter name and value strings.  A zero byte is required as a
3813         terminator after the last name/value pair.
3814         Parameters can appear in any
3815         order.  <literal>user</> is required, others are optional.
3816         Each parameter is specified as:
3817 <variablelist>
3818 <varlistentry>
3819 <term>
3820         String
3821 </term>
3822 <listitem>
3823 <para>
3824                 The parameter name.  Currently recognized names are:
3825
3826 <variablelist>
3827 <varlistentry>
3828 <term>
3829                 <literal>user</>
3830 </term>
3831 <listitem>
3832 <para>
3833                         The database user name to connect as.  Required;
3834                         there is no default.
3835 </para>
3836 </listitem>
3837 </varlistentry>
3838 <varlistentry>
3839 <term>
3840                 <literal>database</>
3841 </term>
3842 <listitem>
3843 <para>
3844                         The database to connect to.  Defaults to the user name.
3845 </para>
3846 </listitem>
3847 </varlistentry>
3848 <varlistentry>
3849 <term>
3850                 <literal>options</>
3851 </term>
3852 <listitem>
3853 <para>
3854                         Command-line arguments for the backend.  (This is
3855                         deprecated in favor of setting individual run-time
3856                         parameters.)
3857 </para>
3858 </listitem>
3859 </varlistentry>
3860 </variablelist>
3861
3862                 In addition to the above, any run-time parameter that can be
3863                 set at backend start time might be listed.  Such settings
3864                 will be applied during backend start (after parsing the
3865                 command-line options if any).  The values will act as
3866                 session defaults.
3867 </para>
3868 </listitem>
3869 </varlistentry>
3870 <varlistentry>
3871 <term>
3872         String
3873 </term>
3874 <listitem>
3875 <para>
3876                 The parameter value.
3877 </para>
3878 </listitem>
3879 </varlistentry>
3880 </variablelist>
3881
3882 </para>
3883 </listitem>
3884 </varlistentry>
3885
3886
3887 <varlistentry>
3888 <term>
3889 Sync (F)
3890 </term>
3891 <listitem>
3892 <para>
3893
3894 <variablelist>
3895 <varlistentry>
3896 <term>
3897         Byte1('S')
3898 </term>
3899 <listitem>
3900 <para>
3901                 Identifies the message as a Sync command.
3902 </para>
3903 </listitem>
3904 </varlistentry>
3905 <varlistentry>
3906 <term>
3907         Int32(4)
3908 </term>
3909 <listitem>
3910 <para>
3911                 Length of message contents in bytes, including self.
3912 </para>
3913 </listitem>
3914 </varlistentry>
3915 </variablelist>
3916
3917 </para>
3918 </listitem>
3919 </varlistentry>
3920
3921
3922 <varlistentry>
3923 <term>
3924 Terminate (F)
3925 </term>
3926 <listitem>
3927 <para>
3928
3929 <variablelist>
3930 <varlistentry>
3931 <term>
3932         Byte1('X')
3933 </term>
3934 <listitem>
3935 <para>
3936                 Identifies the message as a termination.
3937 </para>
3938 </listitem>
3939 </varlistentry>
3940 <varlistentry>
3941 <term>
3942         Int32(4)
3943 </term>
3944 <listitem>
3945 <para>
3946                 Length of message contents in bytes, including self.
3947 </para>
3948 </listitem>
3949 </varlistentry>
3950 </variablelist>
3951
3952 </para>
3953 </listitem>
3954 </varlistentry>
3955
3956
3957 </variablelist>
3958
3959 </sect1>
3960
3961
3962 <sect1 id="protocol-error-fields">
3963 <title>Error and Notice Message Fields</title>
3964
3965 <para>
3966 This section describes the fields that can appear in ErrorResponse and
3967 NoticeResponse messages.  Each field type has a single-byte identification
3968 token.  Note that any given field type should appear at most once per
3969 message.
3970 </para>
3971
3972 <variablelist>
3973
3974 <varlistentry>
3975 <term>
3976 <literal>S</>
3977 </term>
3978 <listitem>
3979 <para>
3980         Severity: the field contents are
3981         <literal>ERROR</>, <literal>FATAL</>, or
3982         <literal>PANIC</> (in an error message), or
3983         <literal>WARNING</>, <literal>NOTICE</>, <literal>DEBUG</>,
3984         <literal>INFO</>, or <literal>LOG</> (in a notice message),
3985         or a localized translation of one of these.  Always present.
3986 </para>
3987 </listitem>
3988 </varlistentry>
3989
3990 <varlistentry>
3991 <term>
3992 <literal>C</>
3993 </term>
3994 <listitem>
3995 <para>
3996         Code: the SQLSTATE code for the error (see <xref
3997         linkend="errcodes-appendix">).  Not localizable.  Always present.
3998 </para>
3999 </listitem>
4000 </varlistentry>
4001
4002 <varlistentry>
4003 <term>
4004 <literal>M</>
4005 </term>
4006 <listitem>
4007 <para>
4008         Message: the primary human-readable error message.
4009         This should be accurate but terse (typically one line).
4010         Always present.
4011 </para>
4012 </listitem>
4013 </varlistentry>
4014
4015 <varlistentry>
4016 <term>
4017 <literal>D</>
4018 </term>
4019 <listitem>
4020 <para>
4021         Detail: an optional secondary error message carrying more
4022         detail about the problem.  Might run to multiple lines.
4023 </para>
4024 </listitem>
4025 </varlistentry>
4026
4027 <varlistentry>
4028 <term>
4029 <literal>H</>
4030 </term>
4031 <listitem>
4032 <para>
4033         Hint: an optional suggestion what to do about the problem.
4034         This is intended to differ from Detail in that it offers advice
4035         (potentially inappropriate) rather than hard facts.
4036         Might run to multiple lines.
4037 </para>
4038 </listitem>
4039 </varlistentry>
4040
4041 <varlistentry>
4042 <term>
4043 <literal>P</>
4044 </term>
4045 <listitem>
4046 <para>
4047         Position: the field value is a decimal ASCII integer, indicating
4048         an error cursor position as an index into the original query string.
4049         The first character has index 1, and positions are measured in
4050         characters not bytes.
4051 </para>
4052 </listitem>
4053 </varlistentry>
4054
4055 <varlistentry>
4056 <term>
4057 <literal>p</>
4058 </term>
4059 <listitem>
4060 <para>
4061         Internal position: this is defined the same as the <literal>P</>
4062         field, but it is used when the cursor position refers to an internally
4063         generated command rather than the one submitted by the client.
4064         The <literal>q</> field will always appear when this field appears.
4065 </para>
4066 </listitem>
4067 </varlistentry>
4068
4069 <varlistentry>
4070 <term>
4071 <literal>q</>
4072 </term>
4073 <listitem>
4074 <para>
4075         Internal query: the text of a failed internally-generated command.
4076         This could be, for example, a SQL query issued by a PL/pgSQL function.
4077 </para>
4078 </listitem>
4079 </varlistentry>
4080
4081 <varlistentry>
4082 <term>
4083 <literal>W</>
4084 </term>
4085 <listitem>
4086 <para>
4087         Where: an indication of the context in which the error occurred.
4088         Presently this includes a call stack traceback of active
4089         procedural language functions and internally-generated queries.
4090         The trace is one entry per line, most recent first.
4091 </para>
4092 </listitem>
4093 </varlistentry>
4094
4095 <varlistentry>
4096 <term>
4097 <literal>F</>
4098 </term>
4099 <listitem>
4100 <para>
4101         File: the file name of the source-code location where the error
4102         was reported.
4103 </para>
4104 </listitem>
4105 </varlistentry>
4106
4107 <varlistentry>
4108 <term>
4109 <literal>L</>
4110 </term>
4111 <listitem>
4112 <para>
4113         Line: the line number of the source-code location where the error
4114         was reported.
4115 </para>
4116 </listitem>
4117 </varlistentry>
4118
4119 <varlistentry>
4120 <term>
4121 <literal>R</>
4122 </term>
4123 <listitem>
4124 <para>
4125         Routine: the name of the source-code routine reporting the error.
4126 </para>
4127 </listitem>
4128 </varlistentry>
4129
4130 </variablelist>
4131
4132 <para>
4133 The client is responsible for formatting displayed information to meet its
4134 needs; in particular it should break long lines as needed.  Newline characters
4135 appearing in the error message fields should be treated as paragraph breaks,
4136 not line breaks.
4137 </para>
4138
4139 </sect1>
4140
4141
4142 <sect1 id="protocol-changes">
4143 <title>Summary of Changes since Protocol 2.0</title>
4144
4145 <para>
4146 This section provides a quick checklist of changes, for the benefit of
4147 developers trying to update existing client libraries to protocol 3.0.
4148 </para>
4149
4150 <para>
4151 The initial startup packet uses a flexible list-of-strings format
4152 instead of a fixed format.  Notice that session default values for run-time
4153 parameters can now be specified directly in the startup packet.  (Actually,
4154 you could do that before using the <literal>options</> field, but given the
4155 limited width of <literal>options</> and the lack of any way to quote
4156 whitespace in the values, it wasn't a very safe technique.)
4157 </para>
4158
4159 <para>
4160 All messages now have a length count immediately following the message type
4161 byte (except for startup packets, which have no type byte).  Also note that
4162 PasswordMessage now has a type byte.
4163 </para>
4164
4165 <para>
4166 ErrorResponse and NoticeResponse ('<literal>E</>' and '<literal>N</>')
4167 messages now contain multiple fields, from which the client code can
4168 assemble an error message of the desired level of verbosity.  Note that
4169 individual fields will typically not end with a newline, whereas the single
4170 string sent in the older protocol always did.
4171 </para>
4172
4173 <para>
4174 The ReadyForQuery ('<literal>Z</>') message includes a transaction status
4175 indicator.
4176 </para>
4177
4178 <para>
4179 The distinction between BinaryRow and DataRow message types is gone; the
4180 single DataRow message type serves for returning data in all formats.
4181 Note that the layout of DataRow has changed to make it easier to parse.
4182 Also, the representation of binary values has changed: it is no longer
4183 directly tied to the server's internal representation.
4184 </para>
4185
4186 <para>
4187 There is a new <quote>extended query</> sub-protocol, which adds the frontend
4188 message types Parse, Bind, Execute, Describe, Close, Flush, and Sync, and the
4189 backend message types ParseComplete, BindComplete, PortalSuspended,
4190 ParameterDescription, NoData, and CloseComplete.  Existing clients do not
4191 have to concern themselves with this sub-protocol, but making use of it
4192 might allow improvements in performance or functionality.
4193 </para>
4194
4195 <para>
4196 <command>COPY</command> data is now encapsulated into CopyData and CopyDone messages.  There
4197 is a well-defined way to recover from errors during <command>COPY</command>.  The special
4198 <quote><literal>\.</></quote> last line is not needed anymore, and is not sent
4199 during <command>COPY OUT</command>.
4200 (It is still recognized as a terminator during <command>COPY IN</command>, but its use is
4201 deprecated and will eventually be removed.)  Binary <command>COPY</command> is supported.
4202 The CopyInResponse and CopyOutResponse messages include fields indicating
4203 the number of columns and the format of each column.
4204 </para>
4205
4206 <para>
4207 The layout of FunctionCall and FunctionCallResponse messages has changed.
4208 FunctionCall can now support passing NULL arguments to functions.  It also
4209 can handle passing parameters and retrieving results in either text or
4210 binary format.  There is no longer any reason to consider FunctionCall a
4211 potential security hole, since it does not offer direct access to internal
4212 server data representations.
4213 </para>
4214
4215 <para>
4216 The backend sends ParameterStatus ('<literal>S</>') messages during connection
4217 startup for all parameters it considers interesting to the client library.
4218 Subsequently, a ParameterStatus message is sent whenever the active value
4219 changes for any of these parameters.
4220 </para>
4221
4222 <para>
4223 The RowDescription ('<literal>T</>') message carries new table OID and column
4224 number fields for each column of the described row.  It also shows the format
4225 code for each column.
4226 </para>
4227
4228 <para>
4229 The CursorResponse ('<literal>P</>') message is no longer generated by
4230 the backend.
4231 </para>
4232
4233 <para>
4234 The NotificationResponse ('<literal>A</>') message has an additional string
4235 field, which is presently empty but might someday carry additional data passed
4236 from the <command>NOTIFY</command> event sender.
4237 </para>
4238
4239 <para>
4240 The EmptyQueryResponse ('<literal>I</>') message used to include an empty
4241 string parameter; this has been removed.
4242 </para>
4243
4244 </sect1>
4245
4246
4247 </chapter>