diff options
Diffstat (limited to 'doc/src/sgml/protocol.sgml')
| -rw-r--r-- | doc/src/sgml/protocol.sgml | 7455 |
1 files changed, 7455 insertions, 0 deletions
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml new file mode 100644 index 0000000..405046f --- /dev/null +++ b/doc/src/sgml/protocol.sgml @@ -0,0 +1,7455 @@ +<!-- doc/src/sgml/protocol.sgml --> + +<chapter id="protocol"> + <title>Frontend/Backend Protocol</title> + + <indexterm zone="protocol"> + <primary>protocol</primary> + <secondary>frontend-backend</secondary> + </indexterm> + + <para> + <productname>PostgreSQL</productname> uses a message-based protocol + for communication between frontends and backends (clients and servers). + The protocol is supported over <acronym>TCP/IP</acronym> and also over + Unix-domain sockets. Port number 5432 has been registered with IANA as + the customary TCP port number for servers supporting this protocol, but + in practice any non-privileged port number can be used. + </para> + + <para> + This document describes version 3.0 of the protocol, implemented in + <productname>PostgreSQL</productname> 7.4 and later. For descriptions + of the earlier protocol versions, see previous releases of the + <productname>PostgreSQL</productname> documentation. A single server + can support multiple protocol versions. The initial startup-request + message tells the server which protocol version the client is attempting to + use. If the major version requested by the client is not supported by + the server, the connection will be rejected (for example, this would occur + if the client requested protocol version 4.0, which does not exist as of + this writing). If the minor version requested by the client is not + supported by the server (e.g., the client requests version 3.1, but the + server supports only 3.0), the server may either reject the connection or + may respond with a NegotiateProtocolVersion message containing the highest + minor protocol version which it supports. The client may then choose either + to continue with the connection using the specified protocol version or + to abort the connection. + </para> + + <para> + In order to serve multiple clients efficiently, the server launches + a new <quote>backend</quote> process for each client. + In the current implementation, a new child + process is created immediately after an incoming connection is detected. + This is transparent to the protocol, however. For purposes of the + protocol, the terms <quote>backend</quote> and <quote>server</quote> are + interchangeable; likewise <quote>frontend</quote> and <quote>client</quote> + are interchangeable. + </para> + + <sect1 id="protocol-overview"> + <title>Overview</title> + + <para> + The protocol has separate phases for startup and normal operation. + In the startup phase, the frontend opens a connection to the server + and authenticates itself to the satisfaction of the server. (This might + involve a single message, or multiple messages depending on the + authentication method being used.) If all goes well, the server then sends + status information to the frontend, and finally enters normal operation. + Except for the initial startup-request message, this part of the + protocol is driven by the server. + </para> + + <para> + During normal operation, the frontend sends queries and + other commands to the backend, and the backend sends back query results + and other responses. There are a few cases (such as <command>NOTIFY</command>) + wherein the + backend will send unsolicited messages, but for the most part this portion + of a session is driven by frontend requests. + </para> + + <para> + Termination of the session is normally by frontend choice, but can be + forced by the backend in certain cases. In any case, when the backend + closes the connection, it will roll back any open (incomplete) transaction + before exiting. + </para> + + <para> + Within normal operation, SQL commands can be executed through either of + two sub-protocols. In the <quote>simple query</quote> protocol, the frontend + just sends a textual query string, which is parsed and immediately + executed by the backend. In the <quote>extended query</quote> protocol, + processing of queries is separated into multiple steps: parsing, + binding of parameter values, and execution. This offers flexibility + and performance benefits, at the cost of extra complexity. + </para> + + <para> + Normal operation has additional sub-protocols for special operations + such as <command>COPY</command>. + </para> + + <sect2 id="protocol-message-concepts"> + <title>Messaging Overview</title> + + <para> + All communication is through a stream of messages. The first byte of a + message identifies the message type, and the next four bytes specify the + length of the rest of the message (this length count includes itself, but + not the message-type byte). The remaining contents of the message are + determined by the message type. For historical reasons, the very first + message sent by the client (the startup message) has no initial + message-type byte. + </para> + + <para> + To avoid losing synchronization with the message stream, both servers and + clients typically read an entire message into a buffer (using the byte + count) before attempting to process its contents. This allows easy + recovery if an error is detected while processing the contents. In + extreme situations (such as not having enough memory to buffer the + message), the receiver can use the byte count to determine how much + input to skip before it resumes reading messages. + </para> + + <para> + Conversely, both servers and clients must take care never to send an + incomplete message. This is commonly done by marshaling the entire message + in a buffer before beginning to send it. If a communications failure + occurs partway through sending or receiving a message, the only sensible + response is to abandon the connection, since there is little hope of + recovering message-boundary synchronization. + </para> + </sect2> + + <sect2 id="protocol-query-concepts"> + <title>Extended Query Overview</title> + + <para> + In the extended-query protocol, execution of SQL commands is divided + into multiple steps. The state retained between steps is represented + by two types of objects: <firstterm>prepared statements</firstterm> and + <firstterm>portals</firstterm>. A prepared statement represents the result of + parsing and semantic analysis of a textual query string. + A prepared statement is not in itself ready to execute, because it might + lack specific values for <firstterm>parameters</firstterm>. A portal represents + a ready-to-execute or already-partially-executed statement, with any + missing parameter values filled in. (For <command>SELECT</command> statements, + a portal is equivalent to an open cursor, but we choose to use a different + term since cursors don't handle non-<command>SELECT</command> statements.) + </para> + + <para> + The overall execution cycle consists of a <firstterm>parse</firstterm> step, + which creates a prepared statement from a textual query string; a + <firstterm>bind</firstterm> step, which creates a portal given a prepared + statement and values for any needed parameters; and an + <firstterm>execute</firstterm> step that runs a portal's query. In the case of + a query that returns rows (<command>SELECT</command>, <command>SHOW</command>, etc.), + the execute step can be told to fetch only + a limited number of rows, so that multiple execute steps might be needed + to complete the operation. + </para> + + <para> + The backend can keep track of multiple prepared statements and portals + (but note that these exist only within a session, and are never shared + across sessions). Existing prepared statements and portals are + referenced by names assigned when they were created. In addition, + an <quote>unnamed</quote> prepared statement and portal exist. Although these + behave largely the same as named objects, operations on them are optimized + for the case of executing a query only once and then discarding it, + whereas operations on named objects are optimized on the expectation + of multiple uses. + </para> + </sect2> + + <sect2 id="protocol-format-codes"> + <title>Formats and Format Codes</title> + + <para> + Data of a particular data type might be transmitted in any of several + different <firstterm>formats</firstterm>. As of <productname>PostgreSQL</productname> 7.4 + the only supported formats are <quote>text</quote> and <quote>binary</quote>, + but the protocol makes provision for future extensions. The desired + format for any value is specified by a <firstterm>format code</firstterm>. + Clients can specify a format code for each transmitted parameter value + and for each column of a query result. Text has format code zero, + binary has format code one, and all other format codes are reserved + for future definition. + </para> + + <para> + The text representation of values is whatever strings are produced + and accepted by the input/output conversion functions for the + particular data type. In the transmitted representation, there is + no trailing null character; the frontend must add one to received + values if it wants to process them as C strings. + (The text format does not allow embedded nulls, by the way.) + </para> + + <para> + Binary representations for integers use network byte order (most + significant byte first). For other data types consult the documentation + or source code to learn about the binary representation. Keep in mind + that binary representations for complex data types might change across + server versions; the text format is usually the more portable choice. + </para> + </sect2> + </sect1> + + <sect1 id="protocol-flow"> + <title>Message Flow</title> + + <para> + This section describes the message flow and the semantics of each + message type. (Details of the exact representation of each message + appear in <xref linkend="protocol-message-formats"/>.) There are + several different sub-protocols depending on the state of the + connection: start-up, query, function call, + <command>COPY</command>, and termination. There are also special + provisions for asynchronous operations (including notification + responses and command cancellation), which can occur at any time + after the start-up phase. + </para> + + <sect2> + <title>Start-up</title> + + <para> + To begin a session, a frontend opens a connection to the server and sends + a startup message. This message includes the names of the user and of the + database the user wants to connect to; it also identifies the particular + protocol version to be used. (Optionally, the startup message can include + additional settings for run-time parameters.) + The server then uses this information and + the contents of its configuration files (such as + <filename>pg_hba.conf</filename>) to determine + whether the connection is provisionally acceptable, and what additional + authentication is required (if any). + </para> + + <para> + The server then sends an appropriate authentication request message, + to which the frontend must reply with an appropriate authentication + response message (such as a password). + For all authentication methods except GSSAPI, SSPI and SASL, there is at + most one request and one response. In some methods, no response + at all is needed from the frontend, and so no authentication request + occurs. For GSSAPI, SSPI and SASL, multiple exchanges of packets may be + needed to complete the authentication. + </para> + + <para> + The authentication cycle ends with the server either rejecting the + connection attempt (ErrorResponse), or sending AuthenticationOk. + </para> + + <para> + The possible messages from the server in this phase are: + + <variablelist> + <varlistentry> + <term>ErrorResponse</term> + <listitem> + <para> + The connection attempt has been rejected. + The server then immediately closes the connection. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>AuthenticationOk</term> + <listitem> + <para> + The authentication exchange is successfully completed. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>AuthenticationKerberosV5</term> + <listitem> + <para> + The frontend must now take part in a Kerberos V5 + authentication dialog (not described here, part of the + Kerberos specification) with the server. If this is + successful, the server responds with an AuthenticationOk, + otherwise it responds with an ErrorResponse. This is no + longer supported. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>AuthenticationCleartextPassword</term> + <listitem> + <para> + The frontend must now send a PasswordMessage containing the + password in clear-text form. If + this is the correct password, the server responds with an + AuthenticationOk, otherwise it responds with an ErrorResponse. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>AuthenticationMD5Password</term> + <listitem> + <para> + The frontend must now send a PasswordMessage containing the + password (with user name) encrypted via MD5, then encrypted + again using the 4-byte random salt specified in the + AuthenticationMD5Password message. If this is the correct + password, the server responds with an AuthenticationOk, + otherwise it responds with an ErrorResponse. The actual + PasswordMessage can be computed in SQL as <literal>concat('md5', + md5(concat(md5(concat(password, username)), random-salt)))</literal>. + (Keep in mind the <function>md5()</function> function returns its + result as a hex string.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>AuthenticationSCMCredential</term> + <listitem> + <para> + This response is only possible for local Unix-domain connections + on platforms that support SCM credential messages. The frontend + must issue an SCM credential message and then send a single data + byte. (The contents of the data byte are uninteresting; it's + only used to ensure that the server waits long enough to receive + the credential message.) If the credential is acceptable, + the server responds with an + AuthenticationOk, otherwise it responds with an ErrorResponse. + (This message type is only issued by pre-9.1 servers. It may + eventually be removed from the protocol specification.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>AuthenticationGSS</term> + <listitem> + <para> + The frontend must now initiate a GSSAPI negotiation. The frontend + will send a GSSResponse message with the first part of the GSSAPI + data stream in response to this. If further messages are needed, + the server will respond with AuthenticationGSSContinue. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>AuthenticationSSPI</term> + <listitem> + <para> + The frontend must now initiate an SSPI negotiation. The frontend + will send a GSSResponse with the first part of the SSPI + data stream in response to this. If further messages are needed, + the server will respond with AuthenticationGSSContinue. + </para> + </listitem> + + </varlistentry> + <varlistentry> + <term>AuthenticationGSSContinue</term> + <listitem> + <para> + This message contains the response data from the previous step + of GSSAPI or SSPI negotiation (AuthenticationGSS, AuthenticationSSPI + or a previous AuthenticationGSSContinue). If the GSSAPI + or SSPI data in this message + indicates more data is needed to complete the authentication, + the frontend must send that data as another GSSResponse message. If + GSSAPI or SSPI authentication is completed by this message, the server + will next send AuthenticationOk to indicate successful authentication + or ErrorResponse to indicate failure. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>AuthenticationSASL</term> + <listitem> + <para> + The frontend must now initiate a SASL negotiation, using one of the + SASL mechanisms listed in the message. The frontend will send a + SASLInitialResponse with the name of the selected mechanism, and the + first part of the SASL data stream in response to this. If further + messages are needed, the server will respond with + AuthenticationSASLContinue. See <xref linkend="sasl-authentication"/> + for details. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>AuthenticationSASLContinue</term> + <listitem> + <para> + This message contains challenge data from the previous step of SASL + negotiation (AuthenticationSASL, or a previous + AuthenticationSASLContinue). The frontend must respond with a + SASLResponse message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>AuthenticationSASLFinal</term> + <listitem> + <para> + SASL authentication has completed with additional mechanism-specific + data for the client. The server will next send AuthenticationOk to + indicate successful authentication, or an ErrorResponse to indicate + failure. This message is sent only if the SASL mechanism specifies + additional data to be sent from server to client at completion. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>NegotiateProtocolVersion</term> + <listitem> + <para> + The server does not support the minor protocol version requested + by the client, but does support an earlier version of the protocol; + this message indicates the highest supported minor version. This + message will also be sent if the client requested unsupported protocol + options (i.e., beginning with <literal>_pq_.</literal>) in the + startup packet. This message will be followed by an ErrorResponse or + a message indicating the success or failure of authentication. + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + + <para> + If the frontend does not support the authentication method + requested by the server, then it should immediately close the + connection. + </para> + + <para> + After having received AuthenticationOk, the frontend must wait + for further messages from the server. In this phase a backend process + is being started, and the frontend is just an interested bystander. + It is still possible for the startup attempt + to fail (ErrorResponse) or the server to decline support for the requested + minor protocol version (NegotiateProtocolVersion), but in the normal case + the backend will send some ParameterStatus messages, BackendKeyData, and + finally ReadyForQuery. + </para> + + <para> + During this phase the backend will attempt to apply any additional + run-time parameter settings that were given in the startup message. + If successful, these values become session defaults. An error causes + ErrorResponse and exit. + </para> + + <para> + The possible messages from the backend in this phase are: + + <variablelist> + <varlistentry> + <term>BackendKeyData</term> + <listitem> + <para> + This message provides secret-key data that the frontend must + save if it wants to be able to issue cancel requests later. + The frontend should not respond to this message, but should + continue listening for a ReadyForQuery message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ParameterStatus</term> + <listitem> + <para> + This message informs the frontend about the current (initial) + setting of backend parameters, such as <xref + linkend="guc-client-encoding"/> or <xref linkend="guc-datestyle"/>. + The frontend can ignore this message, or record the settings + for its future use; see <xref linkend="protocol-async"/> for + more details. The frontend should not respond to this + message, but should continue listening for a ReadyForQuery + message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ReadyForQuery</term> + <listitem> + <para> + Start-up is completed. The frontend can now issue commands. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ErrorResponse</term> + <listitem> + <para> + Start-up failed. The connection is closed after sending this + message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>NoticeResponse</term> + <listitem> + <para> + A warning message has been issued. The frontend should + display the message but continue listening for ReadyForQuery + or ErrorResponse. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + The ReadyForQuery message is the same one that the backend will + issue after each command cycle. Depending on the coding needs of + the frontend, it is reasonable to consider ReadyForQuery as + starting a command cycle, or to consider ReadyForQuery as ending the + start-up phase and each subsequent command cycle. + </para> + </sect2> + + <sect2> + <title>Simple Query</title> + + <para> + A simple query cycle is initiated by the frontend sending a Query message + to the backend. The message includes an SQL command (or commands) + expressed as a text string. + The backend then sends one or more response + messages depending on the contents of the query command string, + and finally a ReadyForQuery response message. ReadyForQuery + informs the frontend that it can safely send a new command. + (It is not actually necessary for the frontend to wait for + ReadyForQuery before issuing another command, but the frontend must + then take responsibility for figuring out what happens if the earlier + command fails and already-issued later commands succeed.) + </para> + + <para> + The possible response messages from the backend are: + + <variablelist> + <varlistentry> + <term>CommandComplete</term> + <listitem> + <para> + An SQL command completed normally. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>CopyInResponse</term> + <listitem> + <para> + The backend is ready to copy data from the frontend to a + table; see <xref linkend="protocol-copy"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>CopyOutResponse</term> + <listitem> + <para> + The backend is ready to copy data from a table to the + frontend; see <xref linkend="protocol-copy"/>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RowDescription</term> + <listitem> + <para> + Indicates that rows are about to be returned in response to + a <command>SELECT</command>, <command>FETCH</command>, etc. query. + The contents of this message describe the column layout of the rows. + This will be followed by a DataRow message for each row being returned + to the frontend. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>DataRow</term> + <listitem> + <para> + One of the set of rows returned by + a <command>SELECT</command>, <command>FETCH</command>, etc. query. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>EmptyQueryResponse</term> + <listitem> + <para> + An empty query string was recognized. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ErrorResponse</term> + <listitem> + <para> + An error has occurred. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ReadyForQuery</term> + <listitem> + <para> + Processing of the query string is complete. A separate + message is sent to indicate this because the query string might + contain multiple SQL commands. (CommandComplete marks the + end of processing one SQL command, not the whole string.) + ReadyForQuery will always be sent, whether processing + terminates successfully or with an error. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>NoticeResponse</term> + <listitem> + <para> + A warning message has been issued in relation to the query. + Notices are in addition to other responses, i.e., the backend + will continue processing the command. + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + + <para> + The response to a <command>SELECT</command> query (or other queries that + return row sets, such as <command>EXPLAIN</command> or <command>SHOW</command>) + normally consists of RowDescription, zero or more + DataRow messages, and then CommandComplete. + <command>COPY</command> to or from the frontend invokes special protocol + as described in <xref linkend="protocol-copy"/>. + All other query types normally produce only + a CommandComplete message. + </para> + + <para> + Since a query string could contain several queries (separated by + semicolons), there might be several such response sequences before the + backend finishes processing the query string. ReadyForQuery is issued + when the entire string has been processed and the backend is ready to + accept a new query string. + </para> + + <para> + If a completely empty (no contents other than whitespace) query string + is received, the response is EmptyQueryResponse followed by ReadyForQuery. + </para> + + <para> + In the event of an error, ErrorResponse is issued followed by + ReadyForQuery. All further processing of the query string is aborted by + ErrorResponse (even if more queries remained in it). Note that this + might occur partway through the sequence of messages generated by an + individual query. + </para> + + <para> + In simple Query mode, the format of retrieved values is always text, + except when the given command is a <command>FETCH</command> from a cursor + declared with the <literal>BINARY</literal> option. In that case, the + retrieved values are in binary format. The format codes given in + the RowDescription message tell which format is being used. + </para> + + <para> + A frontend must be prepared to accept ErrorResponse and + NoticeResponse messages whenever it is expecting any other type of + message. See also <xref linkend="protocol-async"/> concerning messages + that the backend might generate due to outside events. + </para> + + <para> + Recommended practice is to code frontends in a state-machine style + that will accept any message type at any time that it could make sense, + rather than wiring in assumptions about the exact sequence of messages. + </para> + + <sect3 id="protocol-flow-multi-statement"> + <title>Multiple Statements in a Simple Query</title> + + <para> + When a simple Query message contains more than one SQL statement + (separated by semicolons), those statements are executed as a single + transaction, unless explicit transaction control commands are included + to force a different behavior. For example, if the message contains +<programlisting> +INSERT INTO mytable VALUES(1); +SELECT 1/0; +INSERT INTO mytable VALUES(2); +</programlisting> + then the divide-by-zero failure in the <command>SELECT</command> will force + rollback of the first <command>INSERT</command>. Furthermore, because + execution of the message is abandoned at the first error, the second + <command>INSERT</command> is never attempted at all. + </para> + + <para> + If instead the message contains +<programlisting> +BEGIN; +INSERT INTO mytable VALUES(1); +COMMIT; +INSERT INTO mytable VALUES(2); +SELECT 1/0; +</programlisting> + then the first <command>INSERT</command> is committed by the + explicit <command>COMMIT</command> command. The second <command>INSERT</command> + and the <command>SELECT</command> are still treated as a single transaction, + so that the divide-by-zero failure will roll back the + second <command>INSERT</command>, but not the first one. + </para> + + <para> + This behavior is implemented by running the statements in a + multi-statement Query message in an <firstterm>implicit transaction + block</firstterm> unless there is some explicit transaction block for them to + run in. The main difference between an implicit transaction block and + a regular one is that an implicit block is closed automatically at the + end of the Query message, either by an implicit commit if there was no + error, or an implicit rollback if there was an error. This is similar + to the implicit commit or rollback that happens for a statement + executed by itself (when not in a transaction block). + </para> + + <para> + If the session is already in a transaction block, as a result of + a <command>BEGIN</command> in some previous message, then the Query message + simply continues that transaction block, whether the message contains + one statement or several. However, if the Query message contains + a <command>COMMIT</command> or <command>ROLLBACK</command> closing the existing + transaction block, then any following statements are executed in an + implicit transaction block. + Conversely, if a <command>BEGIN</command> appears in a multi-statement Query + message, then it starts a regular transaction block that will only be + terminated by an explicit <command>COMMIT</command> or <command>ROLLBACK</command>, + whether that appears in this Query message or a later one. + If the <command>BEGIN</command> follows some statements that were executed as + an implicit transaction block, those statements are not immediately + committed; in effect, they are retroactively included into the new + regular transaction block. + </para> + + <para> + A <command>COMMIT</command> or <command>ROLLBACK</command> appearing in an implicit + transaction block is executed as normal, closing the implicit block; + however, a warning will be issued since a <command>COMMIT</command> + or <command>ROLLBACK</command> without a previous <command>BEGIN</command> might + represent a mistake. If more statements follow, a new implicit + transaction block will be started for them. + </para> + + <para> + Savepoints are not allowed in an implicit transaction block, since + they would conflict with the behavior of automatically closing the + block upon any error. + </para> + + <para> + Remember that, regardless of any transaction control commands that may + be present, execution of the Query message stops at the first error. + Thus for example given +<programlisting> +BEGIN; +SELECT 1/0; +ROLLBACK; +</programlisting> + in a single Query message, the session will be left inside a failed + regular transaction block, since the <command>ROLLBACK</command> is not + reached after the divide-by-zero error. Another <command>ROLLBACK</command> + will be needed to restore the session to a usable state. + </para> + + <para> + Another behavior of note is that initial lexical and syntactic + analysis is done on the entire query string before any of it is + executed. Thus simple errors (such as a misspelled keyword) in later + statements can prevent execution of any of the statements. This + is normally invisible to users since the statements would all roll + back anyway when done as an implicit transaction block. However, + it can be visible when attempting to do multiple transactions within a + multi-statement Query. For instance, if a typo turned our previous + example into +<programlisting> +BEGIN; +INSERT INTO mytable VALUES(1); +COMMIT; +INSERT INTO mytable VALUES(2); +SELCT 1/0;<!-- this typo is intentional --> +</programlisting> + then none of the statements would get run, resulting in the visible + difference that the first <command>INSERT</command> is not committed. + Errors detected at semantic analysis or later, such as a misspelled + table or column name, do not have this effect. + </para> + </sect3> + </sect2> + + <sect2 id="protocol-flow-ext-query"> + <title>Extended Query</title> + + <para> + The extended query protocol breaks down the above-described simple + query protocol into multiple steps. The results of preparatory + steps can be re-used multiple times for improved efficiency. + Furthermore, additional features are available, such as the possibility + of supplying data values as separate parameters instead of having to + insert them directly into a query string. + </para> + + <para> + In the extended protocol, the frontend first sends a Parse message, + which contains a textual query string, optionally some information + about data types of parameter placeholders, and the + name of a destination prepared-statement object (an empty string + selects the unnamed prepared statement). The response is + either ParseComplete or ErrorResponse. Parameter data types can be + specified by OID; if not given, the parser attempts to infer the + data types in the same way as it would do for untyped literal string + constants. + </para> + + <note> + <para> + A parameter data type can be left unspecified by setting it to zero, + or by making the array of parameter type OIDs shorter than the + number of parameter symbols (<literal>$</literal><replaceable>n</replaceable>) + used in the query string. Another special case is that a parameter's + type can be specified as <type>void</type> (that is, the OID of the + <type>void</type> pseudo-type). This is meant to allow parameter symbols + to be used for function parameters that are actually OUT parameters. + Ordinarily there is no context in which a <type>void</type> parameter + could be used, but if such a parameter symbol appears in a function's + parameter list, it is effectively ignored. For example, a function + call such as <literal>foo($1,$2,$3,$4)</literal> could match a function with + two IN and two OUT arguments, if <literal>$3</literal> and <literal>$4</literal> + are specified as having type <type>void</type>. + </para> + </note> + + <note> + <para> + The query string contained in a Parse message cannot include more + than one SQL statement; else a syntax error is reported. This + restriction does not exist in the simple-query protocol, but it + does exist in the extended protocol, because allowing prepared + statements or portals to contain multiple commands would complicate + the protocol unduly. + </para> + </note> + + <para> + If successfully created, a named prepared-statement object lasts till + the end of the current session, unless explicitly destroyed. An unnamed + prepared statement lasts only until the next Parse statement specifying + the unnamed statement as destination is issued. (Note that a simple + Query message also destroys the unnamed statement.) Named prepared + statements must be explicitly closed before they can be redefined by + another Parse message, but this is not required for the unnamed statement. + Named prepared statements can also be created and accessed at the SQL + command level, using <command>PREPARE</command> and <command>EXECUTE</command>. + </para> + + <para> + Once a prepared statement exists, it can be readied for execution using a + Bind message. The Bind message gives the name of the source prepared + statement (empty string denotes the unnamed prepared statement), the name + of the destination portal (empty string denotes the unnamed portal), and + the values to use for any parameter placeholders present in the prepared + statement. The + supplied parameter set must match those needed by the prepared statement. + (If you declared any <type>void</type> parameters in the Parse message, + pass NULL values for them in the Bind message.) + Bind also specifies the format to use for any data returned + by the query; the format can be specified overall, or per-column. + The response is either BindComplete or ErrorResponse. + </para> + + <note> + <para> + The choice between text and binary output is determined by the format + codes given in Bind, regardless of the SQL command involved. The + <literal>BINARY</literal> attribute in cursor declarations is irrelevant when + using extended query protocol. + </para> + </note> + + <para> + Query planning typically occurs when the Bind message is processed. + If the prepared statement has no parameters, or is executed repeatedly, + the server might save the created plan and re-use it during subsequent + Bind messages for the same prepared statement. However, it will do so + only if it finds that a generic plan can be created that is not much + less efficient than a plan that depends on the specific parameter values + supplied. This happens transparently so far as the protocol is concerned. + </para> + + <para> + If successfully created, a named portal object lasts till the end of the + current transaction, unless explicitly destroyed. An unnamed portal is + destroyed at the end of the transaction, or as soon as the next Bind + statement specifying the unnamed portal as destination is issued. (Note + that a simple Query message also destroys the unnamed portal.) Named + portals must be explicitly closed before they can be redefined by another + Bind message, but this is not required for the unnamed portal. + Named portals can also be created and accessed at the SQL + command level, using <command>DECLARE CURSOR</command> and <command>FETCH</command>. + </para> + + <para> + Once a portal exists, it can be executed using an Execute message. + The Execute message specifies the portal name (empty string denotes the + unnamed portal) and + a maximum result-row count (zero meaning <quote>fetch all rows</quote>). + The result-row count is only meaningful for portals + containing commands that return row sets; in other cases the command is + always executed to completion, and the row count is ignored. + The possible + responses to Execute are the same as those described above for queries + issued via simple query protocol, except that Execute doesn't cause + ReadyForQuery or RowDescription to be issued. + </para> + + <para> + If Execute terminates before completing the execution of a portal + (due to reaching a nonzero result-row count), it will send a + PortalSuspended message; the appearance of this message tells the frontend + that another Execute should be issued against the same portal to + complete the operation. The CommandComplete message indicating + completion of the source SQL command is not sent until + the portal's execution is completed. Therefore, an Execute phase is + always terminated by the appearance of exactly one of these messages: + CommandComplete, EmptyQueryResponse (if the portal was created from + an empty query string), ErrorResponse, or PortalSuspended. + </para> + + <para> + At completion of each series of extended-query messages, the frontend + should issue a Sync message. This parameterless message causes the + backend to close the current transaction if it's not inside a + <command>BEGIN</command>/<command>COMMIT</command> transaction block (<quote>close</quote> + meaning to commit if no error, or roll back if error). Then a + ReadyForQuery response is issued. The purpose of Sync is to provide + a resynchronization point for error recovery. When an error is detected + while processing any extended-query message, the backend issues + ErrorResponse, then reads and discards messages until a Sync is reached, + then issues ReadyForQuery and returns to normal message processing. + (But note that no skipping occurs if an error is detected + <emphasis>while</emphasis> processing Sync — this ensures that there is one + and only one ReadyForQuery sent for each Sync.) + </para> + + <note> + <para> + Sync does not cause a transaction block opened with <command>BEGIN</command> + to be closed. It is possible to detect this situation since the + ReadyForQuery message includes transaction status information. + </para> + </note> + + <para> + In addition to these fundamental, required operations, there are several + optional operations that can be used with extended-query protocol. + </para> + + <para> + The Describe message (portal variant) specifies the name of an existing + portal (or an empty string for the unnamed portal). The response is a + RowDescription message describing the rows that will be returned by + executing the portal; or a NoData message if the portal does not contain a + query that will return rows; or ErrorResponse if there is no such portal. + </para> + + <para> + The Describe message (statement variant) specifies the name of an existing + prepared statement (or an empty string for the unnamed prepared + statement). The response is a ParameterDescription message describing the + parameters needed by the statement, followed by a RowDescription message + describing the rows that will be returned when the statement is eventually + executed (or a NoData message if the statement will not return rows). + ErrorResponse is issued if there is no such prepared statement. Note that + since Bind has not yet been issued, the formats to be used for returned + columns are not yet known to the backend; the format code fields in the + RowDescription message will be zeroes in this case. + </para> + + <tip> + <para> + In most scenarios the frontend should issue one or the other variant + of Describe before issuing Execute, to ensure that it knows how to + interpret the results it will get back. + </para> + </tip> + + <para> + The Close message closes an existing prepared statement or portal + and releases resources. It is not an error to issue Close against + a nonexistent statement or portal name. The response is normally + CloseComplete, but could be ErrorResponse if some difficulty is + encountered while releasing resources. Note that closing a prepared + statement implicitly closes any open portals that were constructed + from that statement. + </para> + + <para> + The Flush message does not cause any specific output to be generated, + but forces the backend to deliver any data pending in its output + buffers. A Flush must be sent after any extended-query command except + Sync, if the frontend wishes to examine the results of that command before + issuing more commands. Without Flush, messages returned by the backend + will be combined into the minimum possible number of packets to minimize + network overhead. + </para> + + <note> + <para> + The simple Query message is approximately equivalent to the series Parse, + Bind, portal Describe, Execute, Close, Sync, using the unnamed prepared + statement and portal objects and no parameters. One difference is that + it will accept multiple SQL statements in the query string, automatically + performing the bind/describe/execute sequence for each one in succession. + Another difference is that it will not return ParseComplete, BindComplete, + CloseComplete, or NoData messages. + </para> + </note> + </sect2> + + <sect2 id="protocol-flow-pipelining"> + <title>Pipelining</title> + + <indexterm zone="protocol-flow-pipelining"> + <primary>pipelining</primary> + <secondary>protocol specification</secondary> + </indexterm> + + <para> + Use of the extended query protocol + allows <firstterm>pipelining</firstterm>, which means sending a series + of queries without waiting for earlier ones to complete. This reduces + the number of network round trips needed to complete a given series of + operations. However, the user must carefully consider the required + behavior if one of the steps fails, since later queries will already + be in flight to the server. + </para> + + <para> + One way to deal with that is to make the whole query series be a + single transaction, that is wrap it in <command>BEGIN</command> ... + <command>COMMIT</command>. However, this does not help if one wishes + for some of the commands to commit independently of others. + </para> + + <para> + The extended query protocol provides another way to manage this + concern, which is to omit sending Sync messages between steps that + are dependent. Since, after an error, the backend will skip command + messages until it finds Sync, this allows later commands in a pipeline + to be skipped automatically when an earlier one fails, without the + client having to manage that explicitly with <command>BEGIN</command> + and <command>COMMIT</command>. Independently-committable segments + of the pipeline can be separated by Sync messages. + </para> + + <para> + If the client has not issued an explicit <command>BEGIN</command>, + then each Sync ordinarily causes an implicit <command>COMMIT</command> + if the preceding step(s) succeeded, or an + implicit <command>ROLLBACK</command> if they failed. However, there + are a few DDL commands (such as <command>CREATE DATABASE</command>) + that cannot be executed inside a transaction block. If one of + these is executed in a pipeline, it will fail unless it is the first + command in the pipeline. Furthermore, upon success it will force an + immediate commit to preserve database consistency. Thus a Sync + immediately following one of these commands has no effect except to + respond with ReadyForQuery. + </para> + + <para> + When using this method, completion of the pipeline must be determined + by counting ReadyForQuery messages and waiting for that to reach the + number of Syncs sent. Counting command completion responses is + unreliable, since some of the commands may be skipped and thus not + produce a completion message. + </para> + </sect2> + + <sect2> + <title>Function Call</title> + + <para> + The Function Call sub-protocol allows the client to request a direct + call of any function that exists in the database's + <structname>pg_proc</structname> system catalog. The client must have + execute permission for the function. + </para> + + <note> + <para> + The Function Call sub-protocol is a legacy feature that is probably best + avoided in new code. Similar results can be accomplished by setting up + a prepared statement that does <literal>SELECT function($1, ...)</literal>. + The Function Call cycle can then be replaced with Bind/Execute. + </para> + </note> + + <para> + A Function Call cycle is initiated by the frontend sending a + FunctionCall message to the backend. The backend then sends one + or more response messages depending on the results of the function + call, and finally a ReadyForQuery response message. ReadyForQuery + informs the frontend that it can safely send a new query or + function call. + </para> + + <para> + The possible response messages from the backend are: + + <variablelist> + <varlistentry> + <term>ErrorResponse</term> + <listitem> + <para> + An error has occurred. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>FunctionCallResponse</term> + <listitem> + <para> + The function call was completed and returned the result given + in the message. + (Note that the Function Call protocol can only handle a single + scalar result, not a row type or set of results.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ReadyForQuery</term> + <listitem> + <para> + Processing of the function call is complete. ReadyForQuery + will always be sent, whether processing terminates + successfully or with an error. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>NoticeResponse</term> + <listitem> + <para> + A warning message has been issued in relation to the function + call. Notices are in addition to other responses, i.e., the + backend will continue processing the command. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </sect2> + + <sect2 id="protocol-copy"> + <title>COPY Operations</title> + + <para> + The <command>COPY</command> command allows high-speed bulk data transfer + to or from the server. Copy-in and copy-out operations each switch + the connection into a distinct sub-protocol, which lasts until the + operation is completed. + </para> + + <para> + Copy-in mode (data transfer to the server) is initiated when the + backend executes a <command>COPY FROM STDIN</command> SQL statement. The backend + sends a CopyInResponse message to the frontend. The frontend should + then send zero or more CopyData messages, forming a stream of input + data. (The message boundaries are not required to have anything to do + with row boundaries, although that is often a reasonable choice.) + The frontend can terminate the copy-in mode by sending either a CopyDone + message (allowing successful termination) or a CopyFail message (which + will cause the <command>COPY</command> SQL statement to fail with an + error). The backend then reverts to the command-processing mode it was + in before the <command>COPY</command> started, which will be either simple or + extended query protocol. It will next send either CommandComplete + (if successful) or ErrorResponse (if not). + </para> + + <para> + In the event of a backend-detected error during copy-in mode (including + receipt of a CopyFail message), the backend will issue an ErrorResponse + message. If the <command>COPY</command> command was issued via an extended-query + message, the backend will now discard frontend messages until a Sync + message is received, then it will issue ReadyForQuery and return to normal + processing. If the <command>COPY</command> command was issued in a simple + Query message, the rest of that message is discarded and ReadyForQuery + is issued. In either case, any subsequent CopyData, CopyDone, or CopyFail + messages issued by the frontend will simply be dropped. + </para> + + <para> + The backend will ignore Flush and Sync messages received during copy-in + mode. Receipt of any other non-copy message type constitutes an error + that will abort the copy-in state as described above. (The exception for + Flush and Sync is for the convenience of client libraries that always + send Flush or Sync after an Execute message, without checking whether + the command to be executed is a <command>COPY FROM STDIN</command>.) + </para> + + <para> + Copy-out mode (data transfer from the server) is initiated when the + backend executes a <command>COPY TO STDOUT</command> SQL statement. The backend + sends a CopyOutResponse message to the frontend, followed by + zero or more CopyData messages (always one per row), followed by CopyDone. + The backend then reverts to the command-processing mode it was + in before the <command>COPY</command> started, and sends CommandComplete. + The frontend cannot abort the transfer (except by closing the connection + or issuing a Cancel request), + but it can discard unwanted CopyData and CopyDone messages. + </para> + + <para> + In the event of a backend-detected error during copy-out mode, + the backend will issue an ErrorResponse message and revert to normal + processing. The frontend should treat receipt of ErrorResponse as + terminating the copy-out mode. + </para> + + <para> + It is possible for NoticeResponse and ParameterStatus messages to be + interspersed between CopyData messages; frontends must handle these cases, + and should be prepared for other asynchronous message types as well (see + <xref linkend="protocol-async"/>). Otherwise, any message type other than + CopyData or CopyDone may be treated as terminating copy-out mode. + </para> + + <para> + There is another Copy-related mode called copy-both, which allows + high-speed bulk data transfer to <emphasis>and</emphasis> from the server. + Copy-both mode is initiated when a backend in walsender mode + executes a <command>START_REPLICATION</command> statement. The + backend sends a CopyBothResponse message to the frontend. Both + the backend and the frontend may then send CopyData messages + until either end sends a CopyDone message. After the client + sends a CopyDone message, the connection goes from copy-both mode to + copy-out mode, and the client may not send any more CopyData messages. + Similarly, when the server sends a CopyDone message, the connection + goes into copy-in mode, and the server may not send any more CopyData + messages. After both sides have sent a CopyDone message, the copy mode + is terminated, and the backend reverts to the command-processing mode. + In the event of a backend-detected error during copy-both mode, + the backend will issue an ErrorResponse message, discard frontend messages + until a Sync message is received, and then issue ReadyForQuery and return + to normal processing. The frontend should treat receipt of ErrorResponse + as terminating the copy in both directions; no CopyDone should be sent + in this case. See <xref linkend="protocol-replication"/> for more + information on the subprotocol transmitted over copy-both mode. + </para> + + <para> + The CopyInResponse, CopyOutResponse and CopyBothResponse messages + include fields that inform the frontend of the number of columns + per row and the format codes being used for each column. (As of + the present implementation, all columns in a given <command>COPY</command> + operation will use the same format, but the message design does not + assume this.) + </para> + + </sect2> + + <sect2 id="protocol-async"> + <title>Asynchronous Operations</title> + + <para> + There are several cases in which the backend will send messages that + are not specifically prompted by the frontend's command stream. + Frontends must be prepared to deal with these messages at any time, + even when not engaged in a query. + At minimum, one should check for these cases before beginning to + read a query response. + </para> + + <para> + It is possible for NoticeResponse messages to be generated due to + outside activity; for example, if the database administrator commands + a <quote>fast</quote> database shutdown, the backend will send a NoticeResponse + indicating this fact before closing the connection. Accordingly, + frontends should always be prepared to accept and display NoticeResponse + messages, even when the connection is nominally idle. + </para> + + <para> + ParameterStatus messages will be generated whenever the active + value changes for any of the parameters the backend believes the + frontend should know about. Most commonly this occurs in response + to a <command>SET</command> SQL command executed by the frontend, and + this case is effectively synchronous — but it is also possible + for parameter status changes to occur because the administrator + changed a configuration file and then sent the + <systemitem>SIGHUP</systemitem> signal to the server. Also, + if a <command>SET</command> command is rolled back, an appropriate + ParameterStatus message will be generated to report the current + effective value. + </para> + + <para> + At present there is a hard-wired set of parameters for which + ParameterStatus will be generated: they are + <varname>server_version</varname>, + <varname>server_encoding</varname>, + <varname>client_encoding</varname>, + <varname>application_name</varname>, + <varname>default_transaction_read_only</varname>, + <varname>in_hot_standby</varname>, + <varname>is_superuser</varname>, + <varname>session_authorization</varname>, + <varname>DateStyle</varname>, + <varname>IntervalStyle</varname>, + <varname>TimeZone</varname>, + <varname>integer_datetimes</varname>, and + <varname>standard_conforming_strings</varname>. + (<varname>server_encoding</varname>, <varname>TimeZone</varname>, and + <varname>integer_datetimes</varname> were not reported by releases before 8.0; + <varname>standard_conforming_strings</varname> was not reported by releases + before 8.1; + <varname>IntervalStyle</varname> was not reported by releases before 8.4; + <varname>application_name</varname> was not reported by releases before + 9.0; + <varname>default_transaction_read_only</varname> and + <varname>in_hot_standby</varname> were not reported by releases before + 14.) + Note that + <varname>server_version</varname>, + <varname>server_encoding</varname> and + <varname>integer_datetimes</varname> + are pseudo-parameters that cannot change after startup. + This set might change in the future, or even become configurable. + Accordingly, a frontend should simply ignore ParameterStatus for + parameters that it does not understand or care about. + </para> + + <para> + If a frontend issues a <command>LISTEN</command> command, then the + backend will send a NotificationResponse message (not to be + confused with NoticeResponse!) whenever a + <command>NOTIFY</command> command is executed for the same + channel name. + </para> + + <note> + <para> + At present, NotificationResponse can only be sent outside a + transaction, and thus it will not occur in the middle of a + command-response series, though it might occur just before ReadyForQuery. + It is unwise to design frontend logic that assumes that, however. + Good practice is to be able to accept NotificationResponse at any + point in the protocol. + </para> + </note> + </sect2> + + <sect2> + <title>Canceling Requests in Progress</title> + + <para> + During the processing of a query, the frontend might request + cancellation of the query. The cancel request is not sent + directly on the open connection to the backend for reasons of + implementation efficiency: we don't want to have the backend + constantly checking for new input from the frontend during query + processing. Cancel requests should be relatively infrequent, so + we make them slightly cumbersome in order to avoid a penalty in + the normal case. + </para> + + <para> + To issue a cancel request, the frontend opens a new connection to + the server and sends a CancelRequest message, rather than the + StartupMessage message that would ordinarily be sent across a new + connection. The server will process this request and then close + the connection. For security reasons, no direct reply is made to + the cancel request message. + </para> + + <para> + A CancelRequest message will be ignored unless it contains the + same key data (PID and secret key) passed to the frontend during + connection start-up. If the request matches the PID and secret + key for a currently executing backend, the processing of the + current query is aborted. (In the existing implementation, this is + done by sending a special signal to the backend process that is + processing the query.) + </para> + + <para> + The cancellation signal might or might not have any effect — for + example, if it arrives after the backend has finished processing + the query, then it will have no effect. If the cancellation is + effective, it results in the current command being terminated + early with an error message. + </para> + + <para> + The upshot of all this is that for reasons of both security and + efficiency, the frontend has no direct way to tell whether a + cancel request has succeeded. It must continue to wait for the + backend to respond to the query. Issuing a cancel simply improves + the odds that the current query will finish soon, and improves the + odds that it will fail with an error message instead of + succeeding. + </para> + + <para> + Since the cancel request is sent across a new connection to the + server and not across the regular frontend/backend communication + link, it is possible for the cancel request to be issued by any + process, not just the frontend whose query is to be canceled. + This might provide additional flexibility when building + multiple-process applications. It also introduces a security + risk, in that unauthorized persons might try to cancel queries. + The security risk is addressed by requiring a dynamically + generated secret key to be supplied in cancel requests. + </para> + </sect2> + + <sect2> + <title>Termination</title> + + <para> + The normal, graceful termination procedure is that the frontend + sends a Terminate message and immediately closes the connection. + On receipt of this message, the backend closes the connection and + terminates. + </para> + + <para> + In rare cases (such as an administrator-commanded database shutdown) + the backend might disconnect without any frontend request to do so. + In such cases the backend will attempt to send an error or notice message + giving the reason for the disconnection before it closes the connection. + </para> + + <para> + Other termination scenarios arise from various failure cases, such as core + dump at one end or the other, loss of the communications link, loss of + message-boundary synchronization, etc. If either frontend or backend sees + an unexpected closure of the connection, it should clean + up and terminate. The frontend has the option of launching a new backend + by recontacting the server if it doesn't want to terminate itself. + Closing the connection is also advisable if an unrecognizable message type + is received, since this probably indicates loss of message-boundary sync. + </para> + + <para> + For either normal or abnormal termination, any open transaction is + rolled back, not committed. One should note however that if a + frontend disconnects while a non-<command>SELECT</command> query + is being processed, the backend will probably finish the query + before noticing the disconnection. If the query is outside any + transaction block (<command>BEGIN</command> ... <command>COMMIT</command> + sequence) then its results might be committed before the + disconnection is recognized. + </para> + </sect2> + + <sect2> + <title><acronym>SSL</acronym> Session Encryption</title> + + <para> + If <productname>PostgreSQL</productname> was built with + <acronym>SSL</acronym> support, frontend/backend communications + can be encrypted using <acronym>SSL</acronym>. This provides + communication security in environments where attackers might be + able to capture the session traffic. For more information on + encrypting <productname>PostgreSQL</productname> sessions with + <acronym>SSL</acronym>, see <xref linkend="ssl-tcp"/>. + </para> + + <para> + To initiate an <acronym>SSL</acronym>-encrypted connection, the + frontend initially sends an SSLRequest message rather than a + StartupMessage. The server then responds with a single byte + containing <literal>S</literal> or <literal>N</literal>, indicating that it is + willing or unwilling to perform <acronym>SSL</acronym>, + respectively. The frontend might close the connection at this point + if it is dissatisfied with the response. To continue after + <literal>S</literal>, perform an <acronym>SSL</acronym> startup handshake + (not described here, part of the <acronym>SSL</acronym> + specification) with the server. If this is successful, continue + with sending the usual StartupMessage. In this case the + StartupMessage and all subsequent data will be + <acronym>SSL</acronym>-encrypted. To continue after + <literal>N</literal>, send the usual StartupMessage and proceed without + encryption. + (Alternatively, it is permissible to issue a GSSENCRequest message + after an <literal>N</literal> response to try to + use <acronym>GSSAPI</acronym> encryption instead + of <acronym>SSL</acronym>.) + </para> + + <para> + The frontend should also be prepared to handle an ErrorMessage + response to SSLRequest from the server. This would only occur if + the server predates the addition of <acronym>SSL</acronym> support + to <productname>PostgreSQL</productname>. (Such servers are now very ancient, + and likely do not exist in the wild anymore.) + In this case the connection must + be closed, but the frontend might choose to open a fresh connection + and proceed without requesting <acronym>SSL</acronym>. + </para> + + <para> + When <acronym>SSL</acronym> encryption can be performed, the server + is expected to send only the single <literal>S</literal> byte and then + wait for the frontend to initiate an <acronym>SSL</acronym> handshake. + If additional bytes are available to read at this point, it likely + means that a man-in-the-middle is attempting to perform a + buffer-stuffing attack + (<ulink url="https://www.postgresql.org/support/security/CVE-2021-23222/">CVE-2021-23222</ulink>). + Frontends should be coded either to read exactly one byte from the + socket before turning the socket over to their SSL library, or to + treat it as a protocol violation if they find they have read additional + bytes. + </para> + + <para> + An initial SSLRequest can also be used in a connection that is being + opened to send a CancelRequest message. + </para> + + <para> + While the protocol itself does not provide a way for the server to + force <acronym>SSL</acronym> encryption, the administrator can + configure the server to reject unencrypted sessions as a byproduct + of authentication checking. + </para> + </sect2> + + <sect2> + <title><acronym>GSSAPI</acronym> Session Encryption</title> + + <para> + If <productname>PostgreSQL</productname> was built with + <acronym>GSSAPI</acronym> support, frontend/backend communications + can be encrypted using <acronym>GSSAPI</acronym>. This provides + communication security in environments where attackers might be + able to capture the session traffic. For more information on + encrypting <productname>PostgreSQL</productname> sessions with + <acronym>GSSAPI</acronym>, see <xref linkend="gssapi-enc"/>. + </para> + + <para> + To initiate a <acronym>GSSAPI</acronym>-encrypted connection, the + frontend initially sends a GSSENCRequest message rather than a + StartupMessage. The server then responds with a single byte + containing <literal>G</literal> or <literal>N</literal>, indicating that it + is willing or unwilling to perform <acronym>GSSAPI</acronym> encryption, + respectively. The frontend might close the connection at this point + if it is dissatisfied with the response. To continue after + <literal>G</literal>, using the GSSAPI C bindings as discussed in + <ulink url="https://tools.ietf.org/html/rfc2744">RFC 2744</ulink> + or equivalent, perform a <acronym>GSSAPI</acronym> initialization by + calling <function>gss_init_sec_context()</function> in a loop and sending + the result to the server, starting with an empty input and then with each + result from the server, until it returns no output. When sending the + results of <function>gss_init_sec_context()</function> to the server, + prepend the length of the message as a four byte integer in network byte + order. + To continue after + <literal>N</literal>, send the usual StartupMessage and proceed without + encryption. + (Alternatively, it is permissible to issue an SSLRequest message + after an <literal>N</literal> response to try to + use <acronym>SSL</acronym> encryption instead + of <acronym>GSSAPI</acronym>.) + </para> + + <para> + The frontend should also be prepared to handle an ErrorMessage + response to GSSENCRequest from the server. This would only occur if + the server predates the addition of <acronym>GSSAPI</acronym> encryption + support to <productname>PostgreSQL</productname>. In this case the + connection must be closed, but the frontend might choose to open a fresh + connection and proceed without requesting <acronym>GSSAPI</acronym> + encryption. + </para> + + <para> + When <acronym>GSSAPI</acronym> encryption can be performed, the server + is expected to send only the single <literal>G</literal> byte and then + wait for the frontend to initiate a <acronym>GSSAPI</acronym> handshake. + If additional bytes are available to read at this point, it likely + means that a man-in-the-middle is attempting to perform a + buffer-stuffing attack + (<ulink url="https://www.postgresql.org/support/security/CVE-2021-23222/">CVE-2021-23222</ulink>). + Frontends should be coded either to read exactly one byte from the + socket before turning the socket over to their GSSAPI library, or to + treat it as a protocol violation if they find they have read additional + bytes. + </para> + + <para> + An initial GSSENCRequest can also be used in a connection that is being + opened to send a CancelRequest message. + </para> + + <para> + Once <acronym>GSSAPI</acronym> encryption has been successfully + established, use <function>gss_wrap()</function> to + encrypt the usual StartupMessage and all subsequent data, prepending the + length of the result from <function>gss_wrap()</function> as a four byte + integer in network byte order to the actual encrypted payload. Note that + the server will only accept encrypted packets from the client which are less + than 16kB; <function>gss_wrap_size_limit()</function> should be used by the + client to determine the size of the unencrypted message which will fit + within this limit and larger messages should be broken up into multiple + <function>gss_wrap()</function> calls. Typical segments are 8kB of + unencrypted data, resulting in encrypted packets of slightly larger than 8kB + but well within the 16kB maximum. The server can be expected to not send + encrypted packets of larger than 16kB to the client. + </para> + + <para> + While the protocol itself does not provide a way for the server to + force <acronym>GSSAPI</acronym> encryption, the administrator can + configure the server to reject unencrypted sessions as a byproduct + of authentication checking. + </para> + </sect2> + </sect1> + + <sect1 id="sasl-authentication"> + <title>SASL Authentication</title> + + <para> + <firstterm>SASL</firstterm> is a framework for authentication in connection-oriented + protocols. At the moment, <productname>PostgreSQL</productname> implements two SASL + authentication mechanisms, SCRAM-SHA-256 and SCRAM-SHA-256-PLUS. More + might be added in the future. The below steps illustrate how SASL + authentication is performed in general, while the next subsection gives + more details on SCRAM-SHA-256 and SCRAM-SHA-256-PLUS. + </para> + + <procedure> + <title>SASL Authentication Message Flow</title> + + <step id="sasl-auth-begin"> + <para> + To begin a SASL authentication exchange, the server sends an + AuthenticationSASL message. It includes a list of SASL authentication + mechanisms that the server can accept, in the server's preferred order. + </para> + </step> + + <step id="sasl-auth-initial-response"> + <para> + The client selects one of the supported mechanisms from the list, and sends + a SASLInitialResponse message to the server. The message includes the name + of the selected mechanism, and an optional Initial Client Response, if the + selected mechanism uses that. + </para> + </step> + + <step id="sasl-auth-continue"> + <para> + One or more server-challenge and client-response message will follow. Each + server-challenge is sent in an AuthenticationSASLContinue message, followed + by a response from client in a SASLResponse message. The particulars of + the messages are mechanism specific. + </para> + </step> + + <step id="sasl-auth-end"> + <para> + Finally, when the authentication exchange is completed successfully, the + server sends an AuthenticationSASLFinal message, followed + immediately by an AuthenticationOk message. The AuthenticationSASLFinal + contains additional server-to-client data, whose content is particular to the + selected authentication mechanism. If the authentication mechanism doesn't + use additional data that's sent at completion, the AuthenticationSASLFinal + message is not sent. + </para> + </step> + </procedure> + + <para> + On error, the server can abort the authentication at any stage, and send an + ErrorMessage. + </para> + + <sect2 id="sasl-scram-sha-256"> + <title>SCRAM-SHA-256 Authentication</title> + + <para> + The implemented SASL mechanisms at the moment + are <literal>SCRAM-SHA-256</literal> and its variant with channel + binding <literal>SCRAM-SHA-256-PLUS</literal>. They are described in + detail in <ulink url="https://tools.ietf.org/html/rfc7677">RFC 7677</ulink> + and <ulink url="https://tools.ietf.org/html/rfc5802">RFC 5802</ulink>. + </para> + + <para> + When SCRAM-SHA-256 is used in PostgreSQL, the server will ignore the user name + that the client sends in the <structname>client-first-message</structname>. The user name + that was already sent in the startup message is used instead. + <productname>PostgreSQL</productname> supports multiple character encodings, while SCRAM + dictates UTF-8 to be used for the user name, so it might be impossible to + represent the PostgreSQL user name in UTF-8. + </para> + + <para> + The SCRAM specification dictates that the password is also in UTF-8, and is + processed with the <firstterm>SASLprep</firstterm> algorithm. + <productname>PostgreSQL</productname>, however, does not require UTF-8 to be used for + the password. When a user's password is set, it is processed with SASLprep + as if it was in UTF-8, regardless of the actual encoding used. However, if + it is not a legal UTF-8 byte sequence, or it contains UTF-8 byte sequences + that are prohibited by the SASLprep algorithm, the raw password will be used + without SASLprep processing, instead of throwing an error. This allows the + password to be normalized when it is in UTF-8, but still allows a non-UTF-8 + password to be used, and doesn't require the system to know which encoding + the password is in. + </para> + + <para> + <firstterm>Channel binding</firstterm> is supported in PostgreSQL builds with + SSL support. The SASL mechanism name for SCRAM with channel binding is + <literal>SCRAM-SHA-256-PLUS</literal>. The channel binding type used by + PostgreSQL is <literal>tls-server-end-point</literal>. + </para> + + <para> + In <acronym>SCRAM</acronym> without channel binding, the server chooses + a random number that is transmitted to the client to be mixed with the + user-supplied password in the transmitted password hash. While this + prevents the password hash from being successfully retransmitted in + a later session, it does not prevent a fake server between the real + server and client from passing through the server's random value + and successfully authenticating. + </para> + + <para> + <acronym>SCRAM</acronym> with channel binding prevents such + man-in-the-middle attacks by mixing the signature of the server's + certificate into the transmitted password hash. While a fake server can + retransmit the real server's certificate, it doesn't have access to the + private key matching that certificate, and therefore cannot prove it is + the owner, causing SSL connection failure. + </para> + + <procedure> + <title>Example</title> + <step id="scram-begin"> + <para> + The server sends an AuthenticationSASL message. It includes a list of + SASL authentication mechanisms that the server can accept. + This will be <literal>SCRAM-SHA-256-PLUS</literal> + and <literal>SCRAM-SHA-256</literal> if the server is built with SSL + support, or else just the latter. + </para> + </step> + + <step id="scram-client-first"> + <para> + The client responds by sending a SASLInitialResponse message, which + indicates the chosen mechanism, <literal>SCRAM-SHA-256</literal> or + <literal>SCRAM-SHA-256-PLUS</literal>. (A client is free to choose either + mechanism, but for better security it should choose the channel-binding + variant if it can support it.) In the Initial Client response field, the + message contains the SCRAM <structname>client-first-message</structname>. + The <structname>client-first-message</structname> also contains the channel + binding type chosen by the client. + </para> + </step> + + <step id="scram-server-first"> + <para> + Server sends an AuthenticationSASLContinue message, with a SCRAM + <structname>server-first-message</structname> as the content. + </para> + </step> + + <step id="scram-client-final"> + <para> + Client sends a SASLResponse message, with SCRAM + <structname>client-final-message</structname> as the content. + </para> + </step> + + <step id="scram-server-final"> + <para> + Server sends an AuthenticationSASLFinal message, with the SCRAM + <structname>server-final-message</structname>, followed immediately by + an AuthenticationOk message. + </para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 id="protocol-replication"> + <title>Streaming Replication Protocol</title> + + <para> + To initiate streaming replication, the frontend sends the + <literal>replication</literal> parameter in the startup message. A Boolean + value of <literal>true</literal> (or <literal>on</literal>, + <literal>yes</literal>, <literal>1</literal>) tells the backend to go into + physical replication walsender mode, wherein a small set of replication + commands, shown below, can be issued instead of SQL statements. + </para> + + <para> + Passing <literal>database</literal> as the value for the + <literal>replication</literal> parameter instructs the backend to go into + logical replication walsender mode, connecting to the database specified in + the <literal>dbname</literal> parameter. In logical replication walsender + mode, the replication commands shown below as well as normal SQL commands can + be issued. + </para> + + <para> + In either physical replication or logical replication walsender mode, only the + simple query protocol can be used. + </para> + + <para> + For the purpose of testing replication commands, you can make a replication + connection via <application>psql</application> or any other + <application>libpq</application>-using tool with a connection string including + the <literal>replication</literal> option, + e.g.: +<programlisting> +psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" +</programlisting> + However, it is often more useful to use + <xref linkend="app-pgreceivewal"/> (for physical replication) or + <xref linkend="app-pgrecvlogical"/> (for logical replication). + </para> + + <para> + Replication commands are logged in the server log when + <xref linkend="guc-log-replication-commands"/> is enabled. + </para> + + <para> + The commands accepted in replication mode are: + + <variablelist> + <varlistentry id="protocol-replication-identify-system"> + <term><literal>IDENTIFY_SYSTEM</literal> + <indexterm><primary>IDENTIFY_SYSTEM</primary></indexterm> + </term> + <listitem> + <para> + Requests the server to identify itself. Server replies with a result + set of a single row, containing four fields: + </para> + + <variablelist> + <varlistentry> + <term><literal>systemid</literal> (<type>text</type>)</term> + <listitem> + <para> + The unique system identifier identifying the cluster. This + can be used to check that the base backup used to initialize the + standby came from the same cluster. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>timeline</literal> (<type>int4</type>)</term> + <listitem> + <para> + Current timeline ID. Also useful to check that the standby is + consistent with the primary. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>xlogpos</literal> (<type>text</type>)</term> + <listitem> + <para> + Current WAL flush location. Useful to get a known location in the + write-ahead log where streaming can start. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>dbname</literal> (<type>text</type>)</term> + <listitem> + <para> + Database connected to or null. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-replication-show"> + <term><literal>SHOW</literal> <replaceable class="parameter">name</replaceable> + <indexterm><primary>SHOW</primary></indexterm> + </term> + <listitem> + <para> + Requests the server to send the current setting of a run-time parameter. + This is similar to the SQL command <xref linkend="sql-show"/>. + </para> + + <variablelist> + <varlistentry> + <term><replaceable class="parameter">name</replaceable></term> + <listitem> + <para> + The name of a run-time parameter. Available parameters are documented + in <xref linkend="runtime-config"/>. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-replication-timeline-history"> + <term><literal>TIMELINE_HISTORY</literal> <replaceable class="parameter">tli</replaceable> + <indexterm><primary>TIMELINE_HISTORY</primary></indexterm> + </term> + <listitem> + <para> + Requests the server to send over the timeline history file for timeline + <replaceable class="parameter">tli</replaceable>. Server replies with a + result set of a single row, containing two fields. While the fields + are labeled as <type>text</type>, they effectively return raw bytes, + with no encoding conversion: + </para> + + <variablelist> + <varlistentry> + <term><literal>filename</literal> (<type>text</type>)</term> + <listitem> + <para> + File name of the timeline history file, e.g., <filename>00000002.history</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>content</literal> (<type>text</type>)</term> + <listitem> + <para> + Contents of the timeline history file. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-replication-create-replication-slot" xreflabel="CREATE_REPLICATION_SLOT"> + <term><literal>CREATE_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable> [ <literal>TEMPORARY</literal> ] { <literal>PHYSICAL</literal> | <literal>LOGICAL</literal> <replaceable class="parameter">output_plugin</replaceable> } [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] + <indexterm><primary>CREATE_REPLICATION_SLOT</primary></indexterm> + </term> + <listitem> + <para> + Create a physical or logical replication + slot. See <xref linkend="streaming-replication-slots"/> for more about + replication slots. + </para> + + <variablelist> + <varlistentry> + <term><replaceable class="parameter">slot_name</replaceable></term> + <listitem> + <para> + The name of the slot to create. Must be a valid replication slot + name (see <xref linkend="streaming-replication-slots-manipulation"/>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">output_plugin</replaceable></term> + <listitem> + <para> + The name of the output plugin used for logical decoding + (see <xref linkend="logicaldecoding-output-plugin"/>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>TEMPORARY</literal></term> + <listitem> + <para> + Specify that this replication slot is a temporary one. Temporary + slots are not saved to disk and are automatically dropped on error + or when the session has finished. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para>The following options are supported:</para> + + <variablelist> + <varlistentry> + <term><literal>TWO_PHASE [ <replaceable class="parameter">boolean</replaceable> ]</literal></term> + <listitem> + <para> + If true, this logical replication slot supports decoding of two-phase + commit. With this option, commands related to two-phase commit such as + <literal>PREPARE TRANSACTION</literal>, <literal>COMMIT PREPARED</literal> + and <literal>ROLLBACK PREPARED</literal> are decoded and transmitted. + The transaction will be decoded and transmitted at + <literal>PREPARE TRANSACTION</literal> time. + The default is false. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESERVE_WAL [ <replaceable class="parameter">boolean</replaceable> ]</literal></term> + <listitem> + <para> + If true, this physical replication slot reserves <acronym>WAL</acronym> + immediately. Otherwise, <acronym>WAL</acronym> is only reserved upon + connection from a streaming replication client. + The default is false. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>SNAPSHOT { 'export' | 'use' | 'nothing' }</literal></term> + <listitem> + <para> + Decides what to do with the snapshot created during logical slot + initialization. <literal>'export'</literal>, which is the default, + will export the snapshot for use in other sessions. This option can't + be used inside a transaction. <literal>'use'</literal> will use the + snapshot for the current transaction executing the command. This + option must be used in a transaction, and + <literal>CREATE_REPLICATION_SLOT</literal> must be the first command + run in that transaction. Finally, <literal>'nothing'</literal> will + just use the snapshot for logical decoding as normal but won't do + anything else with it. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + In response to this command, the server will send a one-row result set + containing the following fields: + + <variablelist> + <varlistentry> + <term><literal>slot_name</literal> (<type>text</type>)</term> + <listitem> + <para> + The name of the newly-created replication slot. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>consistent_point</literal> (<type>text</type>)</term> + <listitem> + <para> + The WAL location at which the slot became consistent. This is the + earliest location from which streaming can start on this replication + slot. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>snapshot_name</literal> (<type>text</type>)</term> + <listitem> + <para> + The identifier of the snapshot exported by the command. The + snapshot is valid until a new command is executed on this connection + or the replication connection is closed. Null if the created slot + is physical. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>output_plugin</literal> (<type>text</type>)</term> + <listitem> + <para> + The name of the output plugin used by the newly-created replication + slot. Null if the created slot is physical. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + + <varlistentry id="protocol-replication-create-replication-slot-legacy"> + <term><literal>CREATE_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable> [ <literal>TEMPORARY</literal> ] { <literal>PHYSICAL</literal> [ <literal>RESERVE_WAL</literal> ] | <literal>LOGICAL</literal> <replaceable class="parameter">output_plugin</replaceable> [ <literal>EXPORT_SNAPSHOT</literal> | <literal>NOEXPORT_SNAPSHOT</literal> | <literal>USE_SNAPSHOT</literal> | <literal>TWO_PHASE</literal> ] } + </term> + <listitem> + <para> + For compatibility with older releases, this alternative syntax for + the <literal>CREATE_REPLICATION_SLOT</literal> command is still supported. + </para> + </listitem> + </varlistentry> + + <varlistentry id="protocol-replication-read-replication-slot"> + <term><literal>READ_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable> + <indexterm><primary>READ_REPLICATION_SLOT</primary></indexterm> + </term> + <listitem> + <para> + Read some information associated with a replication slot. Returns a tuple + with <literal>NULL</literal> values if the replication slot does not + exist. This command is currently only supported for physical replication + slots. + </para> + + <para> + In response to this command, the server will return a one-row result set, + containing the following fields: + <variablelist> + <varlistentry> + <term><literal>slot_type</literal> (<type>text</type>)</term> + <listitem> + <para> + The replication slot's type, either <literal>physical</literal> or + <literal>NULL</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>restart_lsn</literal> (<type>text</type>)</term> + <listitem> + <para> + The replication slot's <literal>restart_lsn</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>restart_tli</literal> (<type>int8</type>)</term> + <listitem> + <para> + The timeline ID associated with <literal>restart_lsn</literal>, + following the current timeline history. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + + <varlistentry id="protocol-replication-start-replication"> + <term><literal>START_REPLICATION</literal> [ <literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable> ] [ <literal>PHYSICAL</literal> ] <replaceable class="parameter">XXX/XXX</replaceable> [ <literal>TIMELINE</literal> <replaceable class="parameter">tli</replaceable> ] + <indexterm><primary>START_REPLICATION</primary></indexterm> + </term> + <listitem> + <para> + Instructs server to start streaming WAL, starting at + WAL location <replaceable class="parameter">XXX/XXX</replaceable>. + If <literal>TIMELINE</literal> option is specified, + streaming starts on timeline <replaceable class="parameter">tli</replaceable>; + otherwise, the server's current timeline is selected. The server can + reply with an error, for example if the requested section of WAL has already + been recycled. On success, the server responds with a CopyBothResponse + message, and then starts to stream WAL to the frontend. + </para> + + <para> + If a slot's name is provided + via <replaceable class="parameter">slot_name</replaceable>, it will be updated + as replication progresses so that the server knows which WAL segments, + and if <varname>hot_standby_feedback</varname> is on which transactions, + are still needed by the standby. + </para> + + <para> + If the client requests a timeline that's not the latest but is part of + the history of the server, the server will stream all the WAL on that + timeline starting from the requested start point up to the point where + the server switched to another timeline. If the client requests + streaming at exactly the end of an old timeline, the server skips COPY + mode entirely. + </para> + + <para> + After streaming all the WAL on a timeline that is not the latest one, + the server will end streaming by exiting the COPY mode. When the client + acknowledges this by also exiting COPY mode, the server sends a result + set with one row and two columns, indicating the next timeline in this + server's history. The first column is the next timeline's ID (type <type>int8</type>), and the + second column is the WAL location where the switch happened (type <type>text</type>). Usually, + the switch position is the end of the WAL that was streamed, but there + are corner cases where the server can send some WAL from the old + timeline that it has not itself replayed before promoting. Finally, the + server sends two CommandComplete messages (one that ends the CopyData + and the other ends the <literal>START_REPLICATION</literal> itself), and + is ready to accept a new command. + </para> + + <para> + WAL data is sent as a series of CopyData messages. (This allows + other information to be intermixed; in particular the server can send + an ErrorResponse message if it encounters a failure after beginning + to stream.) The payload of each CopyData message from server to the + client contains a message of one of the following formats: + </para> + + <variablelist> + <varlistentry id="protocol-replication-xlogdata"> + <term>XLogData (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('w')</term> + <listitem> + <para> + Identifies the message as WAL data. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64</term> + <listitem> + <para> + The starting point of the WAL data in this message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64</term> + <listitem> + <para> + The current end of WAL on the server. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64</term> + <listitem> + <para> + The server's system clock at the time of transmission, as + microseconds since midnight on 2000-01-01. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte<replaceable>n</replaceable></term> + <listitem> + <para> + A section of the WAL data stream. + </para> + + <para> + A single WAL record is never split across two XLogData messages. + When a WAL record crosses a WAL page boundary, and is therefore + already split using continuation records, it can be split at the page + boundary. In other words, the first main WAL record and its + continuation records can be sent in different XLogData messages. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-replication-primary-keepalive-message"> + <term>Primary keepalive message (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('k')</term> + <listitem> + <para> + Identifies the message as a sender keepalive. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64</term> + <listitem> + <para> + The current end of WAL on the server. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64</term> + <listitem> + <para> + The server's system clock at the time of transmission, as + microseconds since midnight on 2000-01-01. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte1</term> + <listitem> + <para> + 1 means that the client should reply to this message as soon as + possible, to avoid a timeout disconnect. 0 otherwise. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + + <para> + The receiving process can send replies back to the sender at any time, + using one of the following message formats (also in the payload of a + CopyData message): + </para> + + <variablelist> + <varlistentry id="protocol-replication-standby-status-update"> + <term>Standby status update (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('r')</term> + <listitem> + <para> + Identifies the message as a receiver status update. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64</term> + <listitem> + <para> + The location of the last WAL byte + 1 received and written to disk + in the standby. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64</term> + <listitem> + <para> + The location of the last WAL byte + 1 flushed to disk in + the standby. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64</term> + <listitem> + <para> + The location of the last WAL byte + 1 applied in the standby. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64</term> + <listitem> + <para> + The client's system clock at the time of transmission, as + microseconds since midnight on 2000-01-01. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte1</term> + <listitem> + <para> + If 1, the client requests the server to reply to this message + immediately. This can be used to ping the server, to test if + the connection is still healthy. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-replication-hot-standby-feedback-message"> + <term>Hot standby feedback message (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('h')</term> + <listitem> + <para> + Identifies the message as a hot standby feedback message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64</term> + <listitem> + <para> + The client's system clock at the time of transmission, as + microseconds since midnight on 2000-01-01. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + The standby's current global xmin, excluding the catalog_xmin from any + replication slots. If both this value and the following + catalog_xmin are 0 this is treated as a notification that hot standby + feedback will no longer be sent on this connection. Later non-zero + messages may reinitiate the feedback mechanism. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + The epoch of the global xmin xid on the standby. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + The lowest catalog_xmin of any replication slots on the standby. Set to 0 + if no catalog_xmin exists on the standby or if hot standby feedback is being + disabled. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + The epoch of the catalog_xmin xid on the standby. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-replication-start-replication-slot-logical"> + <term><literal>START_REPLICATION</literal> <literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable> <literal>LOGICAL</literal> <replaceable class="parameter">XXX/XXX</replaceable> [ ( <replaceable>option_name</replaceable> [ <replaceable>option_value</replaceable> ] [, ...] ) ]</term> + <listitem> + <para> + Instructs server to start streaming WAL for logical replication, + starting at either WAL location <replaceable + class="parameter">XXX/XXX</replaceable> or the slot's + <literal>confirmed_flush_lsn</literal> (see <xref + linkend="view-pg-replication-slots"/>), whichever is greater. This + behavior makes it easier for clients to avoid updating their local LSN + status when there is no data to process. However, starting at a + different LSN than requested might not catch certain kinds of client + errors; so the client may wish to check that + <literal>confirmed_flush_lsn</literal> matches its expectations before + issuing <literal>START_REPLICATION</literal>. + </para> + + <para> + The server can reply with an error, for example if the + slot does not exist. On success, the server responds with a CopyBothResponse + message, and then starts to stream WAL to the frontend. + </para> + + <para> + The messages inside the CopyBothResponse messages are of the same format + documented for <literal>START_REPLICATION ... PHYSICAL</literal>, including + two CommandComplete messages. + </para> + + <para> + The output plugin associated with the selected slot is used + to process the output for streaming. + </para> + + <variablelist> + <varlistentry> + <term><literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable></term> + <listitem> + <para> + The name of the slot to stream changes from. This parameter is required, + and must correspond to an existing logical replication slot created + with <literal>CREATE_REPLICATION_SLOT</literal> in + <literal>LOGICAL</literal> mode. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">XXX/XXX</replaceable></term> + <listitem> + <para> + The WAL location to begin streaming at. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">option_name</replaceable></term> + <listitem> + <para> + The name of an option passed to the slot's logical decoding plugin. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">option_value</replaceable></term> + <listitem> + <para> + Optional value, in the form of a string constant, associated with the + specified option. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-replication-drop-replication-slot"> + <term> + <literal>DROP_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable> <optional> <literal>WAIT</literal> </optional> + <indexterm><primary>DROP_REPLICATION_SLOT</primary></indexterm> + </term> + <listitem> + <para> + Drops a replication slot, freeing any reserved server-side resources. + If the slot is a logical slot that was created in a database other than + the database the walsender is connected to, this command fails. + </para> + + <variablelist> + <varlistentry> + <term><replaceable class="parameter">slot_name</replaceable></term> + <listitem> + <para> + The name of the slot to drop. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>WAIT</literal></term> + <listitem> + <para> + This option causes the command to wait if the slot is active until + it becomes inactive, instead of the default behavior of raising an + error. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-replication-base-backup" xreflabel="BASE_BACKUP"> + <term><literal>BASE_BACKUP</literal> [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] + <indexterm><primary>BASE_BACKUP</primary></indexterm> + </term> + <listitem> + <para> + Instructs the server to start streaming a base backup. + The system will automatically be put in backup mode before the backup + is started, and taken out of it when the backup is complete. The + following options are accepted: + + <variablelist> + <varlistentry> + <term><literal>LABEL</literal> <replaceable>'label'</replaceable></term> + <listitem> + <para> + Sets the label of the backup. If none is specified, a backup label + of <literal>base backup</literal> will be used. The quoting rules + for the label are the same as a standard SQL string with + <xref linkend="guc-standard-conforming-strings"/> turned on. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>TARGET</literal> <replaceable>'target'</replaceable></term> + <listitem> + <para> + Tells the server where to send the backup. If the target is + <literal>client</literal>, which is the default, the backup data is + sent to the client. If it is <literal>server</literal>, the backup + data is written to the server at the pathname specified by the + <literal>TARGET_DETAIL</literal> option. If it is + <literal>blackhole</literal>, the backup data is not sent + anywhere; it is simply discarded. + </para> + + <para> + The <literal>server</literal> target requires superuser privilege or + being granted the <literal>pg_write_server_files</literal> role. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>TARGET_DETAIL</literal> <replaceable>'detail'</replaceable></term> + <listitem> + <para> + Provides additional information about the backup target. + </para> + + <para> + Currently, this option can only be used when the backup target is + <literal>server</literal>. It specifies the server directory + to which the backup should be written. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>PROGRESS [ <replaceable class="parameter">boolean</replaceable> ]</literal></term> + <listitem> + <para> + If set to true, request information required to generate a progress + report. This will send back an approximate size in the header of each + tablespace, which can be used to calculate how far along the stream + is done. This is calculated by enumerating all the file sizes once + before the transfer is even started, and might as such have a + negative impact on the performance. In particular, it might take + longer before the first data + is streamed. Since the database files can change during the backup, + the size is only approximate and might both grow and shrink between + the time of approximation and the sending of the actual files. + The default is false. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CHECKPOINT { 'fast' | 'spread' }</literal></term> + <listitem> + <para> + Sets the type of checkpoint to be performed at the beginning of the + base backup. The default is <literal>spread</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>WAL [ <replaceable class="parameter">boolean</replaceable> ]</literal></term> + <listitem> + <para> + If set to true, include the necessary WAL segments in the backup. + This will include all the files between start and stop backup in the + <filename>pg_wal</filename> directory of the base directory tar + file. The default is false. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>WAIT [ <replaceable class="parameter">boolean</replaceable> ]</literal></term> + <listitem> + <para> + If set to true, the backup will wait until the last required WAL + segment has been archived, or emit a warning if log archiving is + not enabled. If false, the backup will neither wait nor warn, + leaving the client responsible for ensuring the required log is + available. The default is true. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>COMPRESSION</literal> <replaceable>'method'</replaceable></term> + <listitem> + <para> + Instructs the server to compress the backup using the specified + method. Currently, the supported methods are <literal>gzip</literal>, + <literal>lz4</literal>, and <literal>zstd</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>COMPRESSION_DETAIL</literal> <replaceable>detail</replaceable></term> + <listitem> + <para> + Specifies details for the chosen compression method. This should only + be used in conjunction with the <literal>COMPRESSION</literal> + option. If the value is an integer, it specifies the compression + level. Otherwise, it should be a comma-separated list of items, + each of the form <replaceable>keyword</replaceable> or + <replaceable>keyword=value</replaceable>. Currently, the supported + keywords are <literal>level</literal> and <literal>workers</literal>. + </para> + + <para> + The <literal>level</literal> keyword sets the compression level. + For <literal>gzip</literal> the compression level should be an + integer between <literal>1</literal> and <literal>9</literal> + (default <literal>Z_DEFAULT_COMPRESSION</literal> or + <literal>-1</literal>), for <literal>lz4</literal> an integer + between 1 and 12 (default <literal>0</literal> for fast compression + mode), and for <literal>zstd</literal> an integer between + <literal>ZSTD_minCLevel()</literal> (usually <literal>-131072</literal>) + and <literal>ZSTD_maxCLevel()</literal> (usually <literal>22</literal>), + (default <literal>ZSTD_CLEVEL_DEFAULT</literal> or + <literal>3</literal>). + </para> + + <para> + The <literal>workers</literal> keyword sets the number of threads + that should be used for parallel compression. Parallel compression + is supported only for <literal>zstd</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>MAX_RATE</literal> <replaceable>rate</replaceable></term> + <listitem> + <para> + Limit (throttle) the maximum amount of data transferred from server + to client per unit of time. The expected unit is kilobytes per second. + If this option is specified, the value must either be equal to zero + or it must fall within the range from 32 kB through 1 GB (inclusive). + If zero is passed or the option is not specified, no restriction is + imposed on the transfer. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>TABLESPACE_MAP [ <replaceable class="parameter">boolean</replaceable> ]</literal></term> + <listitem> + <para> + If true, include information about symbolic links present in the + directory <filename>pg_tblspc</filename> in a file named + <filename>tablespace_map</filename>. The tablespace map file includes + each symbolic link name as it exists in the directory + <filename>pg_tblspc/</filename> and the full path of that symbolic link. + The default is false. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>VERIFY_CHECKSUMS [ <replaceable class="parameter">boolean</replaceable> ]</literal></term> + <listitem> + <para> + If true, checksums are verified during a base backup if they are + enabled. If false, this is skipped. The default is true. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>MANIFEST</literal> <replaceable>manifest_option</replaceable></term> + <listitem> + <para> + When this option is specified with a value of <literal>yes</literal> + or <literal>force-encode</literal>, a backup manifest is created + and sent along with the backup. The manifest is a list of every + file present in the backup with the exception of any WAL files that + may be included. It also stores the size, last modification time, and + optionally a checksum for each file. + A value of <literal>force-encode</literal> forces all filenames + to be hex-encoded; otherwise, this type of encoding is performed only + for files whose names are non-UTF8 octet sequences. + <literal>force-encode</literal> is intended primarily for testing + purposes, to be sure that clients which read the backup manifest + can handle this case. For compatibility with previous releases, + the default is <literal>MANIFEST 'no'</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>MANIFEST_CHECKSUMS</literal> <replaceable>checksum_algorithm</replaceable></term> + <listitem> + <para> + Specifies the checksum algorithm that should be applied to each file included + in the backup manifest. Currently, the available + algorithms are <literal>NONE</literal>, <literal>CRC32C</literal>, + <literal>SHA224</literal>, <literal>SHA256</literal>, + <literal>SHA384</literal>, and <literal>SHA512</literal>. + The default is <literal>CRC32C</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + When the backup is started, the server will first send two + ordinary result sets, followed by one or more CopyOutResponse + results. + </para> + + <para> + The first ordinary result set contains the starting position of the + backup, in a single row with two columns. The first column contains + the start position given in XLogRecPtr format, and the second column + contains the corresponding timeline ID. + </para> + + <para> + The second ordinary result set has one row for each tablespace. + The fields in this row are: + + <variablelist> + <varlistentry> + <term><literal>spcoid</literal> (<type>oid</type>)</term> + <listitem> + <para> + The OID of the tablespace, or null if it's the base + directory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>spclocation</literal> (<type>text</type>)</term> + <listitem> + <para> + The full path of the tablespace directory, or null + if it's the base directory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>size</literal> (<type>int8</type>)</term> + <listitem> + <para> + The approximate size of the tablespace, in kilobytes (1024 bytes), + if progress report has been requested; otherwise it's null. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + After the second regular result set, a CopyOutResponse will be sent. + The payload of each CopyData message will contain a message in one of + the following formats: + </para> + + <variablelist> + <varlistentry> + <term>new archive (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('n')</term> + <listitem><para> + Identifies the message as indicating the start of a new archive. + There will be one archive for the main data directory and one + for each additional tablespace; each will use tar format + (following the <quote>ustar interchange format</quote> specified + in the POSIX 1003.1-2008 standard). + </para></listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem><para> + The file name for this archive. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem><para> + For the main data directory, an empty string. For other + tablespaces, the full path to the directory from which this + archive was created. + </para></listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>manifest (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('m')</term> + <listitem><para> + Identifies the message as indicating the start of the backup + manifest. + </para></listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>archive or manifest data (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('d')</term> + <listitem><para> + Identifies the message as containing archive or manifest data. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>Byte<replaceable>n</replaceable></term> + <listitem><para> + Data bytes. + </para></listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>progress report (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('p')</term> + <listitem><para> + Identifies the message as a progress report. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>Int64</term> + <listitem><para> + The number of bytes from the current tablespace for which + processing has been completed. + </para></listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + + <para> + After the CopyOutResponse, or all such responses, have been sent, a + final ordinary result set will be sent, containing the WAL end position + of the backup, in the same format as the start position. + </para> + + <para> + The tar archive for the data directory and each tablespace will contain + all files in the directories, regardless of whether they are + <productname>PostgreSQL</productname> files or other files added to the same + directory. The only excluded files are: + + <itemizedlist spacing="compact" mark="bullet"> + <listitem> + <para> + <filename>postmaster.pid</filename> + </para> + </listitem> + <listitem> + <para> + <filename>postmaster.opts</filename> + </para> + </listitem> + <listitem> + <para> + <filename>pg_internal.init</filename> (found in multiple directories) + </para> + </listitem> + <listitem> + <para> + Various temporary files and directories created during the operation + of the PostgreSQL server, such as any file or directory beginning + with <filename>pgsql_tmp</filename> and temporary relations. + </para> + </listitem> + <listitem> + <para> + Unlogged relations, except for the init fork which is required to + recreate the (empty) unlogged relation on recovery. + </para> + </listitem> + <listitem> + <para> + <filename>pg_wal</filename>, including subdirectories. If the backup is run + with WAL files included, a synthesized version of <filename>pg_wal</filename> will be + included, but it will only contain the files necessary for the + backup to work, not the rest of the contents. + </para> + </listitem> + <listitem> + <para> + <filename>pg_dynshmem</filename>, <filename>pg_notify</filename>, + <filename>pg_replslot</filename>, <filename>pg_serial</filename>, + <filename>pg_snapshots</filename>, <filename>pg_stat_tmp</filename>, and + <filename>pg_subtrans</filename> are copied as empty directories (even if + they are symbolic links). + </para> + </listitem> + <listitem> + <para> + Files other than regular files and directories, such as symbolic + links (other than for the directories listed above) and special + device files, are skipped. (Symbolic links + in <filename>pg_tblspc</filename> are maintained.) + </para> + </listitem> + </itemizedlist> + Owner, group, and file mode are set if the underlying file system on + the server supports it. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </sect1> + +<sect1 id="protocol-logical-replication"> + <title>Logical Streaming Replication Protocol</title> + + <para> + This section describes the logical replication protocol, which is the message + flow started by the <literal>START_REPLICATION</literal> + <literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable> + <literal>LOGICAL</literal> replication command. + </para> + + <para> + The logical streaming replication protocol builds on the primitives of + the physical streaming replication protocol. + </para> + + <sect2 id="protocol-logical-replication-params"> + <title>Logical Streaming Replication Parameters</title> + + <para> + The logical replication <literal>START_REPLICATION</literal> command + accepts following parameters: + + <variablelist> + <varlistentry> + <term> + proto_version + </term> + <listitem> + <para> + Protocol version. Currently versions <literal>1</literal>, <literal>2</literal>, + and <literal>3</literal> are supported. + </para> + <para> + Version <literal>2</literal> is supported only for server version 14 + and above, and it allows streaming of large in-progress transactions. + </para> + <para> + Version <literal>3</literal> is supported only for server version 15 + and above, and it allows streaming of two-phase commits. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + publication_names + </term> + <listitem> + <para> + Comma separated list of publication names for which to subscribe + (receive changes). The individual publication names are treated + as standard objects names and can be quoted the same as needed. + </para> + </listitem> + </varlistentry> + </variablelist> + + </para> + </sect2> + + <sect2 id="protocol-logical-messages"> + <title>Logical Replication Protocol Messages</title> + + <para> + The individual protocol messages are discussed in the following + subsections. Individual messages are described in + <xref linkend="protocol-logicalrep-message-formats"/>. + </para> + + <para> + All top-level protocol messages begin with a message type byte. + While represented in code as a character, this is a signed byte with no + associated encoding. + </para> + + <para> + Since the streaming replication protocol supplies a message length there + is no need for top-level protocol messages to embed a length in their + header. + </para> + + </sect2> + + <sect2 id="protocol-logical-messages-flow"> + <title>Logical Replication Protocol Message Flow</title> + + <para> + With the exception of the <literal>START_REPLICATION</literal> command and + the replay progress messages, all information flows only from the backend + to the frontend. + </para> + + <para> + The logical replication protocol sends individual transactions one by one. + This means that all messages between a pair of Begin and Commit messages + belong to the same transaction. Similarly, all messages between a pair of + Begin Prepare and Prepare messages belong to the same transaction. + It also sends changes of large in-progress transactions between a pair of + Stream Start and Stream Stop messages. The last stream of such a transaction + contains a Stream Commit or Stream Abort message. + </para> + + <para> + Every sent transaction contains zero or more DML messages (Insert, + Update, Delete). In case of a cascaded setup it can also contain Origin + messages. The origin message indicates that the transaction originated on + different replication node. Since a replication node in the scope of logical + replication protocol can be pretty much anything, the only identifier + is the origin name. It's downstream's responsibility to handle this as + needed (if needed). The Origin message is always sent before any DML + messages in the transaction. + </para> + + <para> + Every DML message contains a relation OID, identifying the publisher's + relation that was acted on. Before the first DML message for a given + relation OID, a Relation message will be sent, describing the schema of + that relation. Subsequently, a new Relation message will be sent if + the relation's definition has changed since the last Relation message + was sent for it. (The protocol assumes that the client is capable of + remembering this metadata for as many relations as needed.) + </para> + + <para> + Relation messages identify column types by their OIDs. In the case + of a built-in type, it is assumed that the client can look up that + type OID locally, so no additional data is needed. For a non-built-in + type OID, a Type message will be sent before the Relation message, + to provide the type name associated with that OID. Thus, a client that + needs to specifically identify the types of relation columns should + cache the contents of Type messages, and first consult that cache to + see if the type OID is defined there. If not, look up the type OID + locally. + </para> + </sect2> +</sect1> + + <sect1 id="protocol-message-types"> + <title>Message Data Types</title> + + <para> + This section describes the base data types used in messages. + </para> + + <variablelist> + <varlistentry> + <term>Int<replaceable>n</replaceable>(<replaceable>i</replaceable>)</term> + <listitem> + <para> + An <replaceable>n</replaceable>-bit integer in network byte + order (most significant byte first). + If <replaceable>i</replaceable> is specified it + is the exact value that will appear, otherwise the value + is variable. Eg. Int16, Int32(42). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int<replaceable>n</replaceable>[<replaceable>k</replaceable>]</term> + <listitem> + <para> + An array of <replaceable>k</replaceable> + <replaceable>n</replaceable>-bit integers, each in network + byte order. The array length <replaceable>k</replaceable> + is always determined by an earlier field in the message. + Eg. Int16[M]. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String(<replaceable>s</replaceable>)</term> + <listitem> + <para> + A null-terminated string (C-style string). There is no + specific length limitation on strings. + If <replaceable>s</replaceable> is specified it is the exact + value that will appear, otherwise the value is variable. + Eg. String, String("user"). + </para> + + <note> + <para> + <emphasis>There is no predefined limit</emphasis> on the length of a string + that can be returned by the backend. Good coding strategy for a frontend + is to use an expandable buffer so that anything that fits in memory can be + accepted. If that's not feasible, read the full string and discard trailing + characters that don't fit into your fixed-size buffer. + </para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte<replaceable>n</replaceable>(<replaceable>c</replaceable>)</term> + <listitem> + <para> + Exactly <replaceable>n</replaceable> bytes. If the field + width <replaceable>n</replaceable> is not a constant, it is + always determinable from an earlier field in the message. + If <replaceable>c</replaceable> is specified it is the exact + value. Eg. Byte2, Byte1('\n'). + </para> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1 id="protocol-message-formats"> + <title>Message Formats</title> + + <para> + This section describes the detailed format of each message. Each is marked to + indicate that it can be sent by a frontend (F), a backend (B), or both + (F & B). + Notice that although each message includes a byte count at the beginning, + the message format is defined so that the message end can be found without + reference to the byte count. This aids validity checking. (The CopyData + message is an exception, because it forms part of a data stream; the contents + of any individual CopyData message cannot be interpretable on their own.) + </para> + + <variablelist> + <varlistentry id="protocol-message-formats-AuthenticationOk"> + <term>AuthenticationOk (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('R')</term> + <listitem> + <para> + Identifies the message as an authentication request. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(8)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(0)</term> + <listitem> + <para> + Specifies that the authentication was successful. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-AuthenticationKerberosV5"> + <term>AuthenticationKerberosV5 (B)</term> + <listitem> + + <variablelist> + <varlistentry> + <term>Byte1('R')</term> + <listitem> + <para> + Identifies the message as an authentication request. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(8)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(2)</term> + <listitem> + <para> + Specifies that Kerberos V5 authentication is required. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-AuthenticationCleartextPassword"> + <term>AuthenticationCleartextPassword (B)</term> + <listitem> + + <variablelist> + <varlistentry> + <term>Byte1('R')</term> + <listitem> + <para> + Identifies the message as an authentication request. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(8)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(3)</term> + <listitem> + <para> + Specifies that a clear-text password is required. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-AuthenticationMD5Password"> + <term>AuthenticationMD5Password (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('R')</term> + <listitem> + <para> + Identifies the message as an authentication request. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(12)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(5)</term> + <listitem> + <para> + Specifies that an MD5-encrypted password is required. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte4</term> + <listitem> + <para> + The salt to use when encrypting the password. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-AuthenticationSCMCredential"> + <term>AuthenticationSCMCredential (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('R')</term> + <listitem> + <para> + Identifies the message as an authentication request. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(8)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(6)</term> + <listitem> + <para> + Specifies that an SCM credentials message is required. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-AuthenticationGSS"> + <term>AuthenticationGSS (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('R')</term> + <listitem> + <para> + Identifies the message as an authentication request. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Int32(8)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(7)</term> + <listitem> + <para> + Specifies that GSSAPI authentication is required. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-AuthenticationGSSContinue"> + <term>AuthenticationGSSContinue (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('R')</term> + <listitem> + <para> + Identifies the message as an authentication request. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(8)</term> + <listitem> + <para> + Specifies that this message contains GSSAPI or SSPI data. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte<replaceable>n</replaceable></term> + <listitem> + <para> + GSSAPI or SSPI authentication data. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-AuthenticationSSPI"> + <term>AuthenticationSSPI (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('R')</term> + <listitem> + <para> + Identifies the message as an authentication request. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(8)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(9)</term> + <listitem> + <para> + Specifies that SSPI authentication is required. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-AuthenticationSASL"> + <term>AuthenticationSASL (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('R')</term> + <listitem> + <para> + Identifies the message as an authentication request. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(10)</term> + <listitem> + <para> + Specifies that SASL authentication is required. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + The message body is a list of SASL authentication mechanisms, in the + server's order of preference. A zero byte is required as terminator after + the last authentication mechanism name. For each mechanism, there is the + following: + + <variablelist> + <varlistentry> + <term>String</term> + <listitem> + <para> + Name of a SASL authentication mechanism. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-AuthenticationSASLContinue"> + <term>AuthenticationSASLContinue (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('R')</term> + <listitem> + <para> + Identifies the message as an authentication request. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(11)</term> + <listitem> + <para> + Specifies that this message contains a SASL challenge. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte<replaceable>n</replaceable></term> + <listitem> + <para> + SASL data, specific to the SASL mechanism being used. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-AuthenticationSASLFinal"> + <term>AuthenticationSASLFinal (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('R')</term> + <listitem> + <para> + Identifies the message as an authentication request. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(12)</term> + <listitem> + <para> + Specifies that SASL authentication has completed. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte<replaceable>n</replaceable></term> + <listitem> + <para> + SASL outcome "additional data", specific to the SASL mechanism + being used. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-BackendKeyData"> + <term>BackendKeyData (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('K')</term> + <listitem> + <para> + Identifies the message as cancellation key data. + The frontend must save these values if it wishes to be + able to issue CancelRequest messages later. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(12)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + The process ID of this backend. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + The secret key of this backend. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-Bind"> + <term>Bind (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('B')</term> + <listitem> + <para> + Identifies the message as a Bind command. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The name of the destination portal + (an empty string selects the unnamed portal). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The name of the source prepared statement + (an empty string selects the unnamed prepared statement). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16</term> + <listitem> + <para> + The number of parameter format codes that follow + (denoted <replaceable>C</replaceable> below). + This can be zero to indicate that there are no parameters + or that the parameters all use the default format (text); + or one, in which case the specified format code is applied + to all parameters; or it can equal the actual number of + parameters. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16[<replaceable>C</replaceable>]</term> + <listitem> + <para> + The parameter format codes. Each must presently be + zero (text) or one (binary). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16</term> + <listitem> + <para> + The number of parameter values that follow (possibly zero). + This must match the number of parameters needed by the query. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + Next, the following pair of fields appear for each parameter: + </para> + + <variablelist> + <varlistentry> + <term>Int32</term> + <listitem> + <para> + The length of the parameter value, in bytes (this count + does not include itself). Can be zero. + As a special case, -1 indicates a NULL parameter value. + No value bytes follow in the NULL case. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte<replaceable>n</replaceable></term> + <listitem> + <para> + The value of the parameter, in the format indicated by the + associated format code. + <replaceable>n</replaceable> is the above length. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + After the last parameter, the following fields appear: + </para> + + <variablelist> + <varlistentry> + <term>Int16</term> + <listitem> + <para> + The number of result-column format codes that follow + (denoted <replaceable>R</replaceable> below). + This can be zero to indicate that there are no result columns + or that the result columns should all use the default format + (text); + or one, in which case the specified format code is applied + to all result columns (if any); or it can equal the actual + number of result columns of the query. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16[<replaceable>R</replaceable>]</term> + <listitem> + <para> + The result-column format codes. Each must presently be + zero (text) or one (binary). + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-BindComplete"> + <term>BindComplete (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('2')</term> + <listitem> + <para> + Identifies the message as a Bind-complete indicator. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(4)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-CancelRequest"> + <term>CancelRequest (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Int32(16)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(80877102)</term> + <listitem> + <para> + The cancel request code. The value is chosen to contain + <literal>1234</literal> in the most significant 16 bits, and <literal>5678</literal> in the + least significant 16 bits. (To avoid confusion, this code + must not be the same as any protocol version number.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + The process ID of the target backend. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + The secret key for the target backend. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-Close"> + <term>Close (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('C')</term> + <listitem> + <para> + Identifies the message as a Close command. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte1</term> + <listitem> + <para> + '<literal>S</literal>' to close a prepared statement; or + '<literal>P</literal>' to close a portal. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The name of the prepared statement or portal to close + (an empty string selects the unnamed prepared statement + or portal). + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-CloseComplete"> + <term>CloseComplete (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('3')</term> + <listitem> + <para> + Identifies the message as a Close-complete indicator. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(4)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-CommandComplete"> + <term>CommandComplete (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('C')</term> + <listitem> + <para> + Identifies the message as a command-completed response. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The command tag. This is usually a single + word that identifies which SQL command was completed. + </para> + + <para> + For an <command>INSERT</command> command, the tag is + <literal>INSERT <replaceable>oid</replaceable> + <replaceable>rows</replaceable></literal>, where + <replaceable>rows</replaceable> is the number of rows + inserted. <replaceable>oid</replaceable> used to be the object ID + of the inserted row if <replaceable>rows</replaceable> was 1 + and the target table had OIDs, but OIDs system columns are + not supported anymore; therefore <replaceable>oid</replaceable> + is always 0. + </para> + + <para> + For a <command>DELETE</command> command, the tag is + <literal>DELETE <replaceable>rows</replaceable></literal> where + <replaceable>rows</replaceable> is the number of rows deleted. + </para> + + <para> + For an <command>UPDATE</command> command, the tag is + <literal>UPDATE <replaceable>rows</replaceable></literal> where + <replaceable>rows</replaceable> is the number of rows updated. + </para> + + <para> + For a <command>MERGE</command> command, the tag is + <literal>MERGE <replaceable>rows</replaceable></literal> where + <replaceable>rows</replaceable> is the number of rows inserted, + updated, or deleted. + </para> + + <para> + For a <command>SELECT</command> or <command>CREATE TABLE AS</command> + command, the tag is <literal>SELECT <replaceable>rows</replaceable></literal> + where <replaceable>rows</replaceable> is the number of rows retrieved. + </para> + + <para> + For a <command>MOVE</command> command, the tag is + <literal>MOVE <replaceable>rows</replaceable></literal> where + <replaceable>rows</replaceable> is the number of rows the + cursor's position has been changed by. + </para> + + <para> + For a <command>FETCH</command> command, the tag is + <literal>FETCH <replaceable>rows</replaceable></literal> where + <replaceable>rows</replaceable> is the number of rows that + have been retrieved from the cursor. + </para> + + <para> + For a <command>COPY</command> command, the tag is + <literal>COPY <replaceable>rows</replaceable></literal> where + <replaceable>rows</replaceable> is the number of rows copied. + (Note: the row count appears only in + <productname>PostgreSQL</productname> 8.2 and later.) + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-CopyData"> + <term>CopyData (F & B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('d')</term> + <listitem> + <para> + Identifies the message as <command>COPY</command> data. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte<replaceable>n</replaceable></term> + <listitem> + <para> + Data that forms part of a <command>COPY</command> data stream. Messages sent + from the backend will always correspond to single data rows, + but messages sent by frontends might divide the data stream + arbitrarily. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-CopyDone"> + <term>CopyDone (F & B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('c')</term> + <listitem> + <para> + Identifies the message as a <command>COPY</command>-complete indicator. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(4)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-CopyFail"> + <term>CopyFail (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('f')</term> + <listitem> + <para> + Identifies the message as a <command>COPY</command>-failure indicator. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + An error message to report as the cause of failure. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-CopyInResponse"> + <term>CopyInResponse (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('G')</term> + <listitem> + <para> + Identifies the message as a Start Copy In response. + The frontend must now send copy-in data (if not + prepared to do so, send a CopyFail message). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int8</term> + <listitem> + <para> + 0 indicates the overall <command>COPY</command> format is textual (rows + separated by newlines, columns separated by separator + characters, etc.). + 1 indicates the overall copy format is binary (similar + to DataRow format). + See <xref linkend="sql-copy"/> + for more information. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16</term> + <listitem> + <para> + The number of columns in the data to be copied + (denoted <replaceable>N</replaceable> below). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16[<replaceable>N</replaceable>]</term> + <listitem> + <para> + The format codes to be used for each column. + Each must presently be zero (text) or one (binary). + All must be zero if the overall copy format is textual. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-CopyOutResponse"> + <term>CopyOutResponse (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('H')</term> + <listitem> + <para> + Identifies the message as a Start Copy Out response. + This message will be followed by copy-out data. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int8</term> + <listitem> + <para> + 0 indicates the overall <command>COPY</command> format + is textual (rows separated by newlines, columns + separated by separator characters, etc.). 1 indicates + the overall copy format is binary (similar to DataRow + format). See <xref linkend="sql-copy"/> for more information. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16</term> + <listitem> + <para> + The number of columns in the data to be copied + (denoted <replaceable>N</replaceable> below). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16[<replaceable>N</replaceable>]</term> + <listitem> + <para> + The format codes to be used for each column. + Each must presently be zero (text) or one (binary). + All must be zero if the overall copy format is textual. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-CopyBothResponse"> + <term>CopyBothResponse (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('W')</term> + <listitem> + <para> + Identifies the message as a Start Copy Both response. + This message is used only for Streaming Replication. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int8</term> + <listitem> + <para> + 0 indicates the overall <command>COPY</command> format + is textual (rows separated by newlines, columns + separated by separator characters, etc.). 1 indicates + the overall copy format is binary (similar to DataRow + format). See <xref linkend="sql-copy"/> for more information. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16</term> + <listitem> + <para> + The number of columns in the data to be copied + (denoted <replaceable>N</replaceable> below). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16[<replaceable>N</replaceable>]</term> + <listitem> + <para> + The format codes to be used for each column. + Each must presently be zero (text) or one (binary). + All must be zero if the overall copy format is textual. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-DataRow"> + <term>DataRow (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('D')</term> + <listitem> + <para> + Identifies the message as a data row. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16</term> + <listitem> + <para> + The number of column values that follow (possibly zero). + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + Next, the following pair of fields appear for each column: + </para> + + <variablelist> + <varlistentry> + <term>Int32</term> + <listitem> + <para> + The length of the column value, in bytes (this count + does not include itself). Can be zero. + As a special case, -1 indicates a NULL column value. + No value bytes follow in the NULL case. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte<replaceable>n</replaceable></term> + <listitem> + <para> + The value of the column, in the format indicated by the + associated format code. + <replaceable>n</replaceable> is the above length. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-Describe"> + <term>Describe (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('D')</term> + <listitem> + <para> + Identifies the message as a Describe command. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte1</term> + <listitem> + <para> + '<literal>S</literal>' to describe a prepared statement; or + '<literal>P</literal>' to describe a portal. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The name of the prepared statement or portal to describe + (an empty string selects the unnamed prepared statement + or portal). + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-EmptyQueryResponse"> + <term>EmptyQueryResponse (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('I')</term> + <listitem> + <para> + Identifies the message as a response to an empty query string. + (This substitutes for CommandComplete.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(4)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-ErrorResponse"> + <term>ErrorResponse (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('E')</term> + <listitem> + <para> + Identifies the message as an error. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + The message body consists of one or more identified fields, + followed by a zero byte as a terminator. Fields can appear in + any order. For each field there is the following: + </para> + + <variablelist> + <varlistentry> + <term>Byte1</term> + <listitem> + <para> + A code identifying the field type; if zero, this is + the message terminator and no string follows. + The presently defined field types are listed in + <xref linkend="protocol-error-fields"/>. + Since more field types might be added in future, + frontends should silently ignore fields of unrecognized + type. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The field value. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-Execute"> + <term>Execute (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('E')</term> + <listitem> + <para> + Identifies the message as an Execute command. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The name of the portal to execute + (an empty string selects the unnamed portal). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Maximum number of rows to return, if portal contains + a query that returns rows (ignored otherwise). Zero + denotes <quote>no limit</quote>. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-Flush"> + <term>Flush (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('H')</term> + <listitem> + <para> + Identifies the message as a Flush command. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(4)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-FunctionCall"> + <term>FunctionCall (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('F')</term> + <listitem> + <para> + Identifies the message as a function call. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Specifies the object ID of the function to call. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16</term> + <listitem> + <para> + The number of argument format codes that follow + (denoted <replaceable>C</replaceable> below). + This can be zero to indicate that there are no arguments + or that the arguments all use the default format (text); + or one, in which case the specified format code is applied + to all arguments; or it can equal the actual number of + arguments. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16[<replaceable>C</replaceable>]</term> + <listitem> + <para> + The argument format codes. Each must presently be + zero (text) or one (binary). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16</term> + <listitem> + <para> + Specifies the number of arguments being supplied to the + function. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + Next, the following pair of fields appear for each argument: + </para> + + <variablelist> + <varlistentry> + <term>Int32</term> + <listitem> + <para> + The length of the argument value, in bytes (this count + does not include itself). Can be zero. + As a special case, -1 indicates a NULL argument value. + No value bytes follow in the NULL case. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte<replaceable>n</replaceable></term> + <listitem> + <para> + The value of the argument, in the format indicated by the + associated format code. + <replaceable>n</replaceable> is the above length. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + After the last argument, the following field appears: + </para> + + <variablelist> + <varlistentry> + <term>Int16</term> + <listitem> + <para> + The format code for the function result. Must presently be + zero (text) or one (binary). + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-FunctionCallResponse"> + <term>FunctionCallResponse (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('V')</term> + <listitem> + <para> + Identifies the message as a function call result. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + The length of the function result value, in bytes (this count + does not include itself). Can be zero. + As a special case, -1 indicates a NULL function result. + No value bytes follow in the NULL case. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte<replaceable>n</replaceable></term> + <listitem> + <para> + The value of the function result, in the format indicated by + the associated format code. + <replaceable>n</replaceable> is the above length. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-GSSENCRequest"> + <term>GSSENCRequest (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Int32(8)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(80877104)</term> + <listitem> + <para> + The <acronym>GSSAPI</acronym> Encryption request code. The value is chosen to contain + <literal>1234</literal> in the most significant 16 bits, and <literal>5680</literal> in the + least significant 16 bits. (To avoid confusion, this code + must not be the same as any protocol version number.) + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-GSSResponse"> + <term>GSSResponse (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('p')</term> + <listitem> + <para> + Identifies the message as a GSSAPI or SSPI response. Note that + this is also used for SASL and password response messages. + The exact message type can be deduced from the context. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte<replaceable>n</replaceable></term> + <listitem> + <para> + GSSAPI/SSPI specific message data. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-NegotiateProtocolVersion"> + <term>NegotiateProtocolVersion (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('v')</term> + <listitem> + <para> + Identifies the message as a protocol version negotiation + message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Newest minor protocol version supported by the server + for the major protocol version requested by the client. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Number of protocol options not recognized by the server. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + Then, for protocol option not recognized by the server, there + is the following: + </para> + + <variablelist> + <varlistentry> + <term>String</term> + <listitem> + <para> + The option name. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-NoData"> + <term>NoData (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('n')</term> + <listitem> + <para> + Identifies the message as a no-data indicator. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(4)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-NoticeResponse"> + <term>NoticeResponse (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('N')</term> + <listitem> + <para> + Identifies the message as a notice. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + The message body consists of one or more identified fields, + followed by a zero byte as a terminator. Fields can appear in + any order. For each field there is the following: + </para> + + <variablelist> + <varlistentry> + <term>Byte1</term> + <listitem> + <para> + A code identifying the field type; if zero, this is + the message terminator and no string follows. + The presently defined field types are listed in + <xref linkend="protocol-error-fields"/>. + Since more field types might be added in future, + frontends should silently ignore fields of unrecognized + type. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The field value. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-NotificationResponse"> + <term>NotificationResponse (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('A')</term> + <listitem> + <para> + Identifies the message as a notification response. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + The process ID of the notifying backend process. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The name of the channel that the notify has been raised on. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The <quote>payload</quote> string passed from the notifying process. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-ParameterDescription"> + <term>ParameterDescription (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('t')</term> + <listitem> + <para> + Identifies the message as a parameter description. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16</term> + <listitem> + <para> + The number of parameters used by the statement + (can be zero). + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + Then, for each parameter, there is the following: + </para> + + <variablelist> + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Specifies the object ID of the parameter data type. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-ParameterStatus"> + <term>ParameterStatus (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('S')</term> + <listitem> + <para> + Identifies the message as a run-time parameter status report. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The name of the run-time parameter being reported. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The current value of the parameter. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-Parse"> + <term>Parse (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('P')</term> + <listitem> + <para> + Identifies the message as a Parse command. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The name of the destination prepared statement + (an empty string selects the unnamed prepared statement). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The query string to be parsed. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16</term> + <listitem> + <para> + The number of parameter data types specified + (can be zero). Note that this is not an indication of + the number of parameters that might appear in the + query string, only the number that the frontend wants to + prespecify types for. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + Then, for each parameter, there is the following: + </para> + + <variablelist> + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Specifies the object ID of the parameter data type. + Placing a zero here is equivalent to leaving the type + unspecified. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-ParseComplete"> + <term>ParseComplete (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('1')</term> + <listitem> + <para> + Identifies the message as a Parse-complete indicator. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(4)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-PasswordMessage"> + <term>PasswordMessage (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('p')</term> + <listitem> + <para> + Identifies the message as a password response. Note that + this is also used for GSSAPI, SSPI and SASL response messages. + The exact message type can be deduced from the context. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The password (encrypted, if requested). + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-PortalSuspended"> + <term>PortalSuspended (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('s')</term> + <listitem> + <para> + Identifies the message as a portal-suspended indicator. + Note this only appears if an Execute message's row-count limit + was reached. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(4)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-Query"> + <term>Query (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('Q')</term> + <listitem> + <para> + Identifies the message as a simple query. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The query string itself. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-ReadyForQuery"> + <term>ReadyForQuery (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('Z')</term> + <listitem> + <para> + Identifies the message type. ReadyForQuery is sent + whenever the backend is ready for a new query cycle. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(5)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte1</term> + <listitem> + <para> + Current backend transaction status indicator. + Possible values are '<literal>I</literal>' if idle (not in + a transaction block); '<literal>T</literal>' if in a transaction + block; or '<literal>E</literal>' if in a failed transaction + block (queries will be rejected until block is ended). + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-RowDescription"> + <term>RowDescription (B)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('T')</term> + <listitem> + <para> + Identifies the message as a row description. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16</term> + <listitem> + <para> + Specifies the number of fields in a row (can be zero). + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + Then, for each field, there is the following: + </para> + + <variablelist> + <varlistentry> + <term>String</term> + <listitem> + <para> + The field name. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + If the field can be identified as a column of a specific + table, the object ID of the table; otherwise zero. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16</term> + <listitem> + <para> + If the field can be identified as a column of a specific + table, the attribute number of the column; otherwise zero. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + The object ID of the field's data type. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16</term> + <listitem> + <para> + The data type size (see <varname>pg_type.typlen</varname>). + Note that negative values denote variable-width types. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + The type modifier (see <varname>pg_attribute.atttypmod</varname>). + The meaning of the modifier is type-specific. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16</term> + <listitem> + <para> + The format code being used for the field. Currently will + be zero (text) or one (binary). In a RowDescription + returned from the statement variant of Describe, the + format code is not yet known and will always be zero. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-SASLInitialResponse"> + <term>SASLInitialResponse (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('p')</term> + <listitem> + <para> + Identifies the message as an initial SASL response. Note that + this is also used for GSSAPI, SSPI and password response messages. + The exact message type is deduced from the context. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + Name of the SASL authentication mechanism that the client + selected. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of SASL mechanism specific "Initial Client Response" that + follows, or -1 if there is no Initial Response. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte<replaceable>n</replaceable></term> + <listitem> + <para> + SASL mechanism specific "Initial Response". + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-SASLResponse"> + <term>SASLResponse (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('p')</term> + <listitem> + <para> + Identifies the message as a SASL response. Note that + this is also used for GSSAPI, SSPI and password response messages. + The exact message type can be deduced from the context. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte<replaceable>n</replaceable></term> + <listitem> + <para> + SASL mechanism specific message data. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-SSLRequest"> + <term>SSLRequest (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Int32(8)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(80877103)</term> + <listitem> + <para> + The <acronym>SSL</acronym> request code. The value is chosen to contain + <literal>1234</literal> in the most significant 16 bits, and <literal>5679</literal> in the + least significant 16 bits. (To avoid confusion, this code + must not be the same as any protocol version number.) + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-StartupMessage"> + <term>StartupMessage (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(196608)</term> + <listitem> + <para> + The protocol version number. The most significant 16 bits are + the major version number (3 for the protocol described here). + The least significant 16 bits are the minor version number + (0 for the protocol described here). + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + The protocol version number is followed by one or more pairs of + parameter name and value strings. A zero byte is required as a + terminator after the last name/value pair. + Parameters can appear in any + order. <literal>user</literal> is required, others are optional. + Each parameter is specified as: + </para> + + <variablelist> + <varlistentry> + <term>String</term> + <listitem> + <para> + The parameter name. Currently recognized names are: + + <variablelist> + <varlistentry> + <term><literal>user</literal></term> + <listitem> + <para> + The database user name to connect as. Required; + there is no default. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>database</literal></term> + <listitem> + <para> + The database to connect to. Defaults to the user name. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>options</literal></term> + <listitem> + <para> + Command-line arguments for the backend. (This is + deprecated in favor of setting individual run-time + parameters.) Spaces within this string are + considered to separate arguments, unless escaped with + a backslash (<literal>\</literal>); write <literal>\\</literal> to + represent a literal backslash. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>replication</literal></term> + <listitem> + <para> + Used to connect in streaming replication mode, where + a small set of replication commands can be issued + instead of SQL statements. Value can be + <literal>true</literal>, <literal>false</literal>, or + <literal>database</literal>, and the default is + <literal>false</literal>. See + <xref linkend="protocol-replication"/> for details. + </para> + </listitem> + </varlistentry> + </variablelist> + + In addition to the above, other parameters may be listed. + Parameter names beginning with <literal>_pq_.</literal> are + reserved for use as protocol extensions, while others are + treated as run-time parameters to be set at backend start + time. Such settings will be applied during backend start + (after parsing the command-line arguments if any) and will + act as session defaults. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The parameter value. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-Sync"> + <term>Sync (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('S')</term> + <listitem> + <para> + Identifies the message as a Sync command. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(4)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-message-formats-Terminate"> + <term>Terminate (F)</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('X')</term> + <listitem> + <para> + Identifies the message as a termination. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32(4)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1 id="protocol-error-fields"> + <title>Error and Notice Message Fields</title> + + <para> + This section describes the fields that can appear in ErrorResponse and + NoticeResponse messages. Each field type has a single-byte identification + token. Note that any given field type should appear at most once per + message. + </para> + + <variablelist> + <varlistentry> + <term><literal>S</literal></term> + <listitem> + <para> + Severity: the field contents are + <literal>ERROR</literal>, <literal>FATAL</literal>, or + <literal>PANIC</literal> (in an error message), or + <literal>WARNING</literal>, <literal>NOTICE</literal>, <literal>DEBUG</literal>, + <literal>INFO</literal>, or <literal>LOG</literal> (in a notice message), + or a localized translation of one of these. Always present. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>V</literal></term> + <listitem> + <para> + Severity: the field contents are + <literal>ERROR</literal>, <literal>FATAL</literal>, or + <literal>PANIC</literal> (in an error message), or + <literal>WARNING</literal>, <literal>NOTICE</literal>, <literal>DEBUG</literal>, + <literal>INFO</literal>, or <literal>LOG</literal> (in a notice message). + This is identical to the <literal>S</literal> field except + that the contents are never localized. This is present only in + messages generated by <productname>PostgreSQL</productname> versions 9.6 + and later. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>C</literal></term> + <listitem> + <para> + Code: the SQLSTATE code for the error (see <xref + linkend="errcodes-appendix"/>). Not localizable. Always present. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>M</literal></term> + <listitem> + <para> + Message: the primary human-readable error message. + This should be accurate but terse (typically one line). + Always present. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>D</literal></term> + <listitem> + <para> + Detail: an optional secondary error message carrying more + detail about the problem. Might run to multiple lines. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>H</literal></term> + <listitem> + <para> + Hint: an optional suggestion what to do about the problem. + This is intended to differ from Detail in that it offers advice + (potentially inappropriate) rather than hard facts. + Might run to multiple lines. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>P</literal></term> + <listitem> + <para> + Position: the field value is a decimal ASCII integer, indicating + an error cursor position as an index into the original query string. + The first character has index 1, and positions are measured in + characters not bytes. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>p</literal></term> + <listitem> + <para> + Internal position: this is defined the same as the <literal>P</literal> + field, but it is used when the cursor position refers to an internally + generated command rather than the one submitted by the client. + The <literal>q</literal> field will always appear when this field appears. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>q</literal></term> + <listitem> + <para> + Internal query: the text of a failed internally-generated command. + This could be, for example, an SQL query issued by a PL/pgSQL function. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>W</literal></term> + <listitem> + <para> + Where: an indication of the context in which the error occurred. + Presently this includes a call stack traceback of active + procedural language functions and internally-generated queries. + The trace is one entry per line, most recent first. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>s</literal></term> + <listitem> + <para> + Schema name: if the error was associated with a specific database + object, the name of the schema containing that object, if any. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>t</literal></term> + <listitem> + <para> + Table name: if the error was associated with a specific table, the + name of the table. (Refer to the schema name field for the name of + the table's schema.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>c</literal></term> + <listitem> + <para> + Column name: if the error was associated with a specific table column, + the name of the column. (Refer to the schema and table name fields to + identify the table.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>d</literal></term> + <listitem> + <para> + Data type name: if the error was associated with a specific data type, + the name of the data type. (Refer to the schema name field for the + name of the data type's schema.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>n</literal></term> + <listitem> + <para> + Constraint name: if the error was associated with a specific + constraint, the name of the constraint. Refer to fields listed above + for the associated table or domain. (For this purpose, indexes are + treated as constraints, even if they weren't created with constraint + syntax.) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>F</literal></term> + <listitem> + <para> + File: the file name of the source-code location where the error + was reported. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>L</literal></term> + <listitem> + <para> + Line: the line number of the source-code location where the error + was reported. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>R</literal></term> + <listitem> + <para> + Routine: the name of the source-code routine reporting the error. + </para> + </listitem> + </varlistentry> + </variablelist> + + <note> + <para> + The fields for schema name, table name, column name, data type name, and + constraint name are supplied only for a limited number of error types; + see <xref linkend="errcodes-appendix"/>. Frontends should not assume that + the presence of any of these fields guarantees the presence of another + field. Core error sources observe the interrelationships noted above, but + user-defined functions may use these fields in other ways. In the same + vein, clients should not assume that these fields denote contemporary + objects in the current database. + </para> + </note> + + <para> + The client is responsible for formatting displayed information to meet its + needs; in particular it should break long lines as needed. Newline characters + appearing in the error message fields should be treated as paragraph breaks, + not line breaks. + </para> + </sect1> + + <sect1 id="protocol-logicalrep-message-formats"> + <title>Logical Replication Message Formats</title> + + <para> + This section describes the detailed format of each logical replication + message. These messages are either returned by the replication slot SQL + interface or are sent by a walsender. In the case of a walsender, they are + encapsulated inside replication protocol WAL messages as described in + <xref linkend="protocol-replication"/>, and generally obey the same message + flow as physical replication. + </para> + + <variablelist> + <varlistentry id="protocol-logicalrep-message-formats-Begin"> + <term>Begin</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('B')</term> + <listitem> + <para> + Identifies the message as a begin message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (XLogRecPtr)</term> + <listitem> + <para> + The final LSN of the transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (TimestampTz)</term> + <listitem> + <para> + Commit timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (TransactionId)</term> + <listitem> + <para> + Xid of the transaction. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-logicalrep-message-formats-Message"> + <term>Message</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('M')</term> + <listitem> + <para> + Identifies the message as a logical decoding message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (TransactionId)</term> + <listitem> + <para> + Xid of the transaction (only present for streamed transactions). + This field is available since protocol version 2. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int8</term> + <listitem> + <para> + Flags; Either 0 for no flags or 1 if the logical decoding + message is transactional. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (XLogRecPtr)</term> + <listitem> + <para> + The LSN of the logical decoding message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The prefix of the logical decoding message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of the content. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte<replaceable>n</replaceable></term> + <listitem> + <para> + The content of the logical decoding message. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-logicalrep-message-formats-Commit"> + <term>Commit</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('C')</term> + <listitem> + <para> + Identifies the message as a commit message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int8(0)</term> + <listitem> + <para> + Flags; currently unused. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (XLogRecPtr)</term> + <listitem> + <para> + The LSN of the commit. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (XLogRecPtr)</term> + <listitem> + <para> + The end LSN of the transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (TimestampTz)</term> + <listitem> + <para> + Commit timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-logicalrep-message-formats-Origin"> + <term>Origin</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('O')</term> + <listitem> + <para> + Identifies the message as an origin message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (XLogRecPtr)</term> + <listitem> + <para> + The LSN of the commit on the origin server. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + Name of the origin. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + Note that there can be multiple Origin messages inside a single transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry id="protocol-logicalrep-message-formats-Relation"> + <term>Relation</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('R')</term> + <listitem> + <para> + Identifies the message as a relation message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (TransactionId)</term> + <listitem> + <para> + Xid of the transaction (only present for streamed transactions). + This field is available since protocol version 2. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (Oid)</term> + <listitem> + <para> + OID of the relation. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + Namespace (empty string for <literal>pg_catalog</literal>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + Relation name. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int8</term> + <listitem> + <para> + Replica identity setting for the relation (same as + <structfield>relreplident</structfield> in <structname>pg_class</structname>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int16</term> + <listitem> + <para> + Number of columns. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + Next, the following message part appears for each column included in + the publication (except generated columns): + </para> + + <variablelist> + <varlistentry> + <term>Int8</term> + <listitem> + <para> + Flags for the column. Currently can be either 0 for no flags + or 1 which marks the column as part of the key. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + Name of the column. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (Oid)</term> + <listitem> + <para> + OID of the column's data type. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Type modifier of the column (<structfield>atttypmod</structfield>). + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-logicalrep-message-formats-Type"> + <term>Type</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('Y')</term> + <listitem> + <para> + Identifies the message as a type message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (TransactionId)</term> + <listitem> + <para> + Xid of the transaction (only present for streamed transactions). + This field is available since protocol version 2. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (Oid)</term> + <listitem> + <para> + OID of the data type. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + Namespace (empty string for <literal>pg_catalog</literal>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + Name of the data type. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-logicalrep-message-formats-Insert"> + <term>Insert</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('I')</term> + <listitem> + <para> + Identifies the message as an insert message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (TransactionId)</term> + <listitem> + <para> + Xid of the transaction (only present for streamed transactions). + This field is available since protocol version 2. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (Oid)</term> + <listitem> + <para> + OID of the relation corresponding to the ID in the relation + message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte1('N')</term> + <listitem> + <para> + Identifies the following TupleData message as a new tuple. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>TupleData</term> + <listitem> + <para> + TupleData message part representing the contents of new tuple. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-logicalrep-message-formats-Update"> + <term>Update</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('U')</term> + <listitem> + <para> + Identifies the message as an update message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (TransactionId)</term> + <listitem> + <para> + Xid of the transaction (only present for streamed transactions). + This field is available since protocol version 2. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (Oid)</term> + <listitem> + <para> + OID of the relation corresponding to the ID in the relation + message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte1('K')</term> + <listitem> + <para> + Identifies the following TupleData submessage as a key. + This field is optional and is only present if + the update changed data in any of the column(s) that are + part of the REPLICA IDENTITY index. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte1('O')</term> + <listitem> + <para> + Identifies the following TupleData submessage as an old tuple. + This field is optional and is only present if table in which + the update happened has REPLICA IDENTITY set to FULL. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>TupleData</term> + <listitem> + <para> + TupleData message part representing the contents of the old tuple + or primary key. Only present if the previous 'O' or 'K' part + is present. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte1('N')</term> + <listitem> + <para> + Identifies the following TupleData message as a new tuple. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>TupleData</term> + <listitem> + <para> + TupleData message part representing the contents of a new tuple. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + The Update message may contain either a 'K' message part or an 'O' message part + or neither of them, but never both of them. + </para> + </listitem> + </varlistentry> + + <varlistentry id="protocol-logicalrep-message-formats-Delete"> + <term>Delete</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('D')</term> + <listitem> + <para> + Identifies the message as a delete message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (TransactionId)</term> + <listitem> + <para> + Xid of the transaction (only present for streamed transactions). + This field is available since protocol version 2. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (Oid)</term> + <listitem> + <para> + OID of the relation corresponding to the ID in the relation + message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte1('K')</term> + <listitem> + <para> + Identifies the following TupleData submessage as a key. + This field is present if the table in which the delete has + happened uses an index as REPLICA IDENTITY. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte1('O')</term> + <listitem> + <para> + Identifies the following TupleData message as an old tuple. + This field is present if the table in which the delete + happened has REPLICA IDENTITY set to FULL. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>TupleData</term> + <listitem> + <para> + TupleData message part representing the contents of the old tuple + or primary key, depending on the previous field. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + The Delete message may contain either a 'K' message part or an 'O' message part, + but never both of them. + </para> + </listitem> + </varlistentry> + + <varlistentry id="protocol-logicalrep-message-formats-Truncate"> + <term>Truncate</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('T')</term> + <listitem> + <para> + Identifies the message as a truncate message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (TransactionId)</term> + <listitem> + <para> + Xid of the transaction (only present for streamed transactions). + This field is available since protocol version 2. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Number of relations + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int8</term> + <listitem> + <para> + Option bits for <command>TRUNCATE</command>: + 1 for <literal>CASCADE</literal>, 2 for <literal>RESTART IDENTITY</literal> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (Oid)</term> + <listitem> + <para> + OID of the relation corresponding to the ID in the relation + message. This field is repeated for each relation. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + + <para> + The following messages (Stream Start, Stream Stop, Stream Commit, and + Stream Abort) are available since protocol version 2. + </para> + + <variablelist> + <varlistentry id="protocol-logicalrep-message-formats-Stream-Start"> + <term>Stream Start</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('S')</term> + <listitem> + <para> + Identifies the message as a stream start message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (TransactionId)</term> + <listitem> + <para> + Xid of the transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int8</term> + <listitem> + <para> + A value of 1 indicates this is the first stream segment for + this XID, 0 for any other stream segment. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-logicalrep-message-formats-Stream-Stop"> + <term>Stream Stop</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('E')</term> + <listitem> + <para> + Identifies the message as a stream stop message. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-logicalrep-message-formats-Stream-Commit"> + <term>Stream Commit</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('c')</term> + <listitem> + <para> + Identifies the message as a stream commit message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (TransactionId)</term> + <listitem> + <para> + Xid of the transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int8(0)</term> + <listitem> + <para> + Flags; currently unused. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (XLogRecPtr)</term> + <listitem> + <para> + The LSN of the commit. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (XLogRecPtr)</term> + <listitem> + <para> + The end LSN of the transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (TimestampTz)</term> + <listitem> + <para> + Commit timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-logicalrep-message-formats-Stream-Abort"> + <term>Stream Abort</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('A')</term> + <listitem> + <para> + Identifies the message as a stream abort message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (TransactionId)</term> + <listitem> + <para> + Xid of the transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (TransactionId)</term> + <listitem> + <para> + Xid of the subtransaction (will be same as xid of the transaction for top-level + transactions). + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + + <para> + The following messages (Begin Prepare, Prepare, Commit Prepared, Rollback Prepared, Stream Prepare) + are available since protocol version 3. + </para> + + <variablelist> + <varlistentry id="protocol-logicalrep-message-formats-Begin-Prepare"> + <term>Begin Prepare</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('b')</term> + <listitem> + <para> + Identifies the message as the beginning of a prepared transaction message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (XLogRecPtr)</term> + <listitem> + <para> + The LSN of the prepare. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (XLogRecPtr)</term> + <listitem> + <para> + The end LSN of the prepared transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (TimestampTz)</term> + <listitem> + <para> + Prepare timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (TransactionId)</term> + <listitem> + <para> + Xid of the transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The user defined GID of the prepared transaction. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-logicalrep-message-formats-Prepare"> + <term>Prepare</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('P')</term> + <listitem> + <para> + Identifies the message as a prepared transaction message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int8(0)</term> + <listitem> + <para> + Flags; currently unused. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (XLogRecPtr)</term> + <listitem> + <para> + The LSN of the prepare. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (XLogRecPtr)</term> + <listitem> + <para> + The end LSN of the prepared transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (TimestampTz)</term> + <listitem> + <para> + Prepare timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (TransactionId)</term> + <listitem> + <para> + Xid of the transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The user defined GID of the prepared transaction. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-logicalrep-message-formats-Commit-Prepared"> + <term>Commit Prepared</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('K')</term> + <listitem> + <para> + Identifies the message as the commit of a prepared transaction message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int8(0)</term> + <listitem> + <para> + Flags; currently unused. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (XLogRecPtr)</term> + <listitem> + <para> + The LSN of the commit of the prepared transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (XLogRecPtr)</term> + <listitem> + <para> + The end LSN of the commit of the prepared transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (TimestampTz)</term> + <listitem> + <para> + Commit timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (TransactionId)</term> + <listitem> + <para> + Xid of the transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The user defined GID of the prepared transaction. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-logicalrep-message-formats-Rollback-Prepared"> + <term>Rollback Prepared</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('r')</term> + <listitem> + <para> + Identifies the message as the rollback of a prepared transaction message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int8(0)</term> + <listitem> + <para> + Flags; currently unused. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (XLogRecPtr)</term> + <listitem> + <para> + The end LSN of the prepared transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (XLogRecPtr)</term> + <listitem> + <para> + The end LSN of the rollback of the prepared transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (TimestampTz)</term> + <listitem> + <para> + Prepare timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (TimestampTz)</term> + <listitem> + <para> + Rollback timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (TransactionId)</term> + <listitem> + <para> + Xid of the transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The user defined GID of the prepared transaction. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry id="protocol-logicalrep-message-formats-Stream-Prepare"> + <term>Stream Prepare</term> + <listitem> + <variablelist> + <varlistentry> + <term>Byte1('p')</term> + <listitem> + <para> + Identifies the message as a stream prepared transaction message. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int8(0)</term> + <listitem> + <para> + Flags; currently unused. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (XLogRecPtr)</term> + <listitem> + <para> + The LSN of the prepare. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (XLogRecPtr)</term> + <listitem> + <para> + The end LSN of the prepared transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (TimestampTz)</term> + <listitem> + <para> + Prepare timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32 (TransactionId)</term> + <listitem> + <para> + Xid of the transaction. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>String</term> + <listitem> + <para> + The user defined GID of the prepared transaction. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + + <para> + The following message parts are shared by the above messages. + </para> + + <variablelist> + <varlistentry id="protocol-logicalrep-message-formats-TupleData"> + <term>TupleData</term> + <listitem> + <variablelist> + <varlistentry> + <term>Int16</term> + <listitem> + <para> + Number of columns. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + Next, one of the following submessages appears for each column (except generated columns): + + <variablelist> + <varlistentry> + <term>Byte1('n')</term> + <listitem> + <para> + Identifies the data as NULL value. + </para> + </listitem> + </varlistentry> + </variablelist> + Or + <variablelist> + <varlistentry> + <term>Byte1('u')</term> + <listitem> + <para> + Identifies unchanged TOASTed value (the actual value is not + sent). + </para> + </listitem> + </varlistentry> + </variablelist> + Or + <variablelist> + <varlistentry> + <term>Byte1('t')</term> + <listitem> + <para> + Identifies the data as text formatted value. + </para> + </listitem> + </varlistentry> + </variablelist> + Or + <variablelist> + <varlistentry> + <term>Byte1('b')</term> + <listitem> + <para> + Identifies the data as binary formatted value. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of the column value. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Byte<replaceable>n</replaceable></term> + <listitem> + <para> + The value of the column, either in binary or in text format. + (As specified in the preceding format byte). + <replaceable>n</replaceable> is the above length. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1 id="protocol-changes"> + <title>Summary of Changes since Protocol 2.0</title> + + <para> + This section provides a quick checklist of changes, for the benefit of + developers trying to update existing client libraries to protocol 3.0. + </para> + + <para> + The initial startup packet uses a flexible list-of-strings format + instead of a fixed format. Notice that session default values for run-time + parameters can now be specified directly in the startup packet. (Actually, + you could do that before using the <literal>options</literal> field, but given the + limited width of <literal>options</literal> and the lack of any way to quote + whitespace in the values, it wasn't a very safe technique.) + </para> + + <para> + All messages now have a length count immediately following the message type + byte (except for startup packets, which have no type byte). Also note that + PasswordMessage now has a type byte. + </para> + + <para> + ErrorResponse and NoticeResponse ('<literal>E</literal>' and '<literal>N</literal>') + messages now contain multiple fields, from which the client code can + assemble an error message of the desired level of verbosity. Note that + individual fields will typically not end with a newline, whereas the single + string sent in the older protocol always did. + </para> + + <para> + The ReadyForQuery ('<literal>Z</literal>') message includes a transaction status + indicator. + </para> + + <para> + The distinction between BinaryRow and DataRow message types is gone; the + single DataRow message type serves for returning data in all formats. + Note that the layout of DataRow has changed to make it easier to parse. + Also, the representation of binary values has changed: it is no longer + directly tied to the server's internal representation. + </para> + + <para> + There is a new <quote>extended query</quote> sub-protocol, which adds the frontend + message types Parse, Bind, Execute, Describe, Close, Flush, and Sync, and the + backend message types ParseComplete, BindComplete, PortalSuspended, + ParameterDescription, NoData, and CloseComplete. Existing clients do not + have to concern themselves with this sub-protocol, but making use of it + might allow improvements in performance or functionality. + </para> + + <para> + <command>COPY</command> data is now encapsulated into CopyData and CopyDone messages. There + is a well-defined way to recover from errors during <command>COPY</command>. The special + <quote><literal>\.</literal></quote> last line is not needed anymore, and is not sent + during <command>COPY OUT</command>. + (It is still recognized as a terminator during <command>COPY IN</command>, but its use is + deprecated and will eventually be removed.) Binary <command>COPY</command> is supported. + The CopyInResponse and CopyOutResponse messages include fields indicating + the number of columns and the format of each column. + </para> + + <para> + The layout of FunctionCall and FunctionCallResponse messages has changed. + FunctionCall can now support passing NULL arguments to functions. It also + can handle passing parameters and retrieving results in either text or + binary format. There is no longer any reason to consider FunctionCall a + potential security hole, since it does not offer direct access to internal + server data representations. + </para> + + <para> + The backend sends ParameterStatus ('<literal>S</literal>') messages during connection + startup for all parameters it considers interesting to the client library. + Subsequently, a ParameterStatus message is sent whenever the active value + changes for any of these parameters. + </para> + + <para> + The RowDescription ('<literal>T</literal>') message carries new table OID and column + number fields for each column of the described row. It also shows the format + code for each column. + </para> + + <para> + The CursorResponse ('<literal>P</literal>') message is no longer generated by + the backend. + </para> + + <para> + The NotificationResponse ('<literal>A</literal>') message has an additional string + field, which can carry a <quote>payload</quote> string passed + from the <command>NOTIFY</command> event sender. + </para> + + <para> + The EmptyQueryResponse ('<literal>I</literal>') message used to include an empty + string parameter; this has been removed. + </para> + </sect1> +</chapter> |