begriffs open source - ai-pg/blob - full-docs/txt/protocol-overview.txt

   1
   2 54.1. Overview #
   3
   4    54.1.1. Messaging Overview
   5    54.1.2. Extended Query Overview
   6    54.1.3. Formats and Format Codes
   7    54.1.4. Protocol Versions
   8
   9    The protocol has separate phases for startup and normal operation. In
  10    the startup phase, the frontend opens a connection to the server and
  11    authenticates itself to the satisfaction of the server. (This might
  12    involve a single message, or multiple messages depending on the
  13    authentication method being used.) If all goes well, the server then
  14    sends status information to the frontend, and finally enters normal
  15    operation. Except for the initial startup-request message, this part of
  16    the protocol is driven by the server.
  17
  18    During normal operation, the frontend sends queries and other commands
  19    to the backend, and the backend sends back query results and other
  20    responses. There are a few cases (such as NOTIFY) wherein the backend
  21    will send unsolicited messages, but for the most part this portion of a
  22    session is driven by frontend requests.
  23
  24    Termination of the session is normally by frontend choice, but can be
  25    forced by the backend in certain cases. In any case, when the backend
  26    closes the connection, it will roll back any open (incomplete)
  27    transaction before exiting.
  28
  29    Within normal operation, SQL commands can be executed through either of
  30    two sub-protocols. In the “simple query” protocol, the frontend just
  31    sends a textual query string, which is parsed and immediately executed
  32    by the backend. In the “extended query” protocol, processing of queries
  33    is separated into multiple steps: parsing, binding of parameter values,
  34    and execution. This offers flexibility and performance benefits, at the
  35    cost of extra complexity.
  36
  37    Normal operation has additional sub-protocols for special operations
  38    such as COPY.
  39
  40 54.1.1. Messaging Overview #
  41
  42    All communication is through a stream of messages. The first byte of a
  43    message identifies the message type, and the next four bytes specify
  44    the length of the rest of the message (this length count includes
  45    itself, but not the message-type byte). The remaining contents of the
  46    message are determined by the message type. For historical reasons, the
  47    very first message sent by the client (the startup message) has no
  48    initial message-type byte.
  49
  50    To avoid losing synchronization with the message stream, both servers
  51    and clients typically read an entire message into a buffer (using the
  52    byte count) before attempting to process its contents. This allows easy
  53    recovery if an error is detected while processing the contents. In
  54    extreme situations (such as not having enough memory to buffer the
  55    message), the receiver can use the byte count to determine how much
  56    input to skip before it resumes reading messages.
  57
  58    Conversely, both servers and clients must take care never to send an
  59    incomplete message. This is commonly done by marshaling the entire
  60    message in a buffer before beginning to send it. If a communications
  61    failure occurs partway through sending or receiving a message, the only
  62    sensible response is to abandon the connection, since there is little
  63    hope of recovering message-boundary synchronization.
  64
  65 54.1.2. Extended Query Overview #
  66
  67    In the extended-query protocol, execution of SQL commands is divided
  68    into multiple steps. The state retained between steps is represented by
  69    two types of objects: prepared statements and portals. A prepared
  70    statement represents the result of parsing and semantic analysis of a
  71    textual query string. A prepared statement is not in itself ready to
  72    execute, because it might lack specific values for parameters. A portal
  73    represents a ready-to-execute or already-partially-executed statement,
  74    with any missing parameter values filled in. (For SELECT statements, a
  75    portal is equivalent to an open cursor, but we choose to use a
  76    different term since cursors don't handle non-SELECT statements.)
  77
  78    The overall execution cycle consists of a parse step, which creates a
  79    prepared statement from a textual query string; a bind step, which
  80    creates a portal given a prepared statement and values for any needed
  81    parameters; and an execute step that runs a portal's query. In the case
  82    of a query that returns rows (SELECT, SHOW, etc.), the execute step can
  83    be told to fetch only a limited number of rows, so that multiple
  84    execute steps might be needed to complete the operation.
  85
  86    The backend can keep track of multiple prepared statements and portals
  87    (but note that these exist only within a session, and are never shared
  88    across sessions). Existing prepared statements and portals are
  89    referenced by names assigned when they were created. In addition, an
  90    “unnamed” prepared statement and portal exist. Although these behave
  91    largely the same as named objects, operations on them are optimized for
  92    the case of executing a query only once and then discarding it, whereas
  93    operations on named objects are optimized on the expectation of
  94    multiple uses.
  95
  96 54.1.3. Formats and Format Codes #
  97
  98    Data of a particular data type might be transmitted in any of several
  99    different formats. As of PostgreSQL 7.4 the only supported formats are
 100    “text” and “binary”, but the protocol makes provision for future
 101    extensions. The desired format for any value is specified by a format
 102    code. Clients can specify a format code for each transmitted parameter
 103    value and for each column of a query result. Text has format code zero,
 104    binary has format code one, and all other format codes are reserved for
 105    future definition.
 106
 107    The text representation of values is whatever strings are produced and
 108    accepted by the input/output conversion functions for the particular
 109    data type. In the transmitted representation, there is no trailing null
 110    character; the frontend must add one to received values if it wants to
 111    process them as C strings. (The text format does not allow embedded
 112    nulls, by the way.)
 113
 114    Binary representations for integers use network byte order (most
 115    significant byte first). For other data types consult the documentation
 116    or source code to learn about the binary representation. Keep in mind
 117    that binary representations for complex data types might change across
 118    server versions; the text format is usually the more portable choice.
 119
 120 54.1.4. Protocol Versions #
 121
 122    The current, latest version of the protocol is version 3.2. However,
 123    for backwards compatibility with old server versions and middleware
 124    that don't support the version negotiation yet, libpq still uses
 125    protocol version 3.0 by default.
 126
 127    A single server can support multiple protocol versions. The initial
 128    startup-request message tells the server which protocol version the
 129    client is attempting to use. If the major version requested by the
 130    client is not supported by the server, the connection will be rejected
 131    (for example, this would occur if the client requested protocol version
 132    4.0, which does not exist as of this writing). If the minor version
 133    requested by the client is not supported by the server (e.g., the
 134    client requests version 3.2, but the server supports only 3.0), the
 135    server may either reject the connection or may respond with a
 136    NegotiateProtocolVersion message containing the highest minor protocol
 137    version which it supports. The client may then choose either to
 138    continue with the connection using the specified protocol version or to
 139    abort the connection.
 140
 141    The protocol negotiation was introduced in PostgreSQL version 9.3.21.
 142    Earlier versions would reject the connection if the client requested a
 143    minor version that was not supported by the server.
 144
 145    Table 54.1 shows the currently supported protocol versions.
 146
 147    Table 54.1. Protocol Versions
 148    Version Supported by Description
 149    3.2 PostgreSQL 18 and later Current latest version. The secret key used
 150    in query cancellation was enlarged from 4 bytes to a variable length
 151    field. The BackendKeyData message was changed to accommodate that, and
 152    the CancelRequest message was redefined to have a variable length
 153    payload.
 154    3.1 - Reserved. Version 3.1 has not been used by any PostgreSQL
 155    version, but it was skipped because old versions of the popular
 156    pgbouncer application had a bug in the protocol negotiation which made
 157    it incorrectly claim that it supported version 3.1.
 158    3.0 PostgreSQL 7.4 and later
 159    2.0 up to PostgreSQL 13 See previous releases of the PostgreSQL
 160    documentation for details