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

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