diff options
| -rw-r--r-- | doc/src/sgml/protocol.sgml | 11588 |
1 files changed, 5348 insertions, 6240 deletions
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 75a7a76a558..a155370a3c4 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1597,1455 +1597,1416 @@ SELCT 1/0;<!-- this typo is intentional --> </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> + <sect1 id="sasl-authentication"> + <title>SASL 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>. + <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> - <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> + <procedure> + <title>SASL Authentication Message Flow</title> - <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> + <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> - <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> + <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> - <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> + <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> - <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. + On error, the server can abort the authentication at any stage, and send an + ErrorMessage. </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> + <sect2 id="sasl-scram-sha-256"> + <title>SCRAM-SHA-256 Authentication</title> -<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> + <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> - <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> + <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> - <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> + <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> - <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> + <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> - <varlistentry> - <term> - <literal>dbname</literal> (<type>text</type>) - </term> - <listitem> - <para> - Database connected to or null. - </para> - </listitem> - </varlistentry> + <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> - </variablelist> - </para> - </listitem> - </varlistentry> + <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> - <varlistentry id="protocol-replication-show"> - <term><literal>SHOW</literal> <replaceable class="parameter">name</replaceable> - <indexterm><primary>SHOW</primary></indexterm> - </term> - <listitem> + <procedure> + <title>Example</title> + <step id="scram-begin"> <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"/>. + 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> - <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> + <step id="scram-client-first"> <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: + 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> - <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> + Server sends an AuthenticationSASLContinue message, with a SCRAM + <structname>server-first-message</structname> as the content. + </para> + </step> - </variablelist> + <step id="scram-client-final"> + <para> + Client sends a SASLResponse message, with SCRAM + <structname>client-final-message</structname> as the content. </para> - </listitem> - </varlistentry> + </step> - <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">option</replaceable> [, ...] ) ] - <indexterm><primary>CREATE_REPLICATION_SLOT</primary></indexterm> - </term> - <listitem> + <step id="scram-server-final"> <para> - Create a physical or logical replication - slot. See <xref linkend="streaming-replication-slots"/> for more about - replication slots. + Server sends an AuthenticationSASLFinal message, with the SCRAM + <structname>server-final-message</structname>, followed immediately by + an AuthenticationOk message. </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> + </step> + </procedure> + </sect2> + </sect1> - <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> + <sect1 id="protocol-replication"> + <title>Streaming Replication Protocol</title> - <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> + 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>The following options are supported:</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> - <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 - transactions. With this option, two-phase commands like - <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> + <para> + In either physical replication or logical replication walsender mode, only the + simple query protocol can be used. + </para> - <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> + <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> - <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> + Replication commands are logged in the server log when + <xref linkend="guc-log-replication-commands"/> is enabled. + </para> - <para> - In response to this command, the server will send a one-row result set - containing the following fields: + <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>slot_name</literal> (<type>text</type>)</term> + <term><literal>systemid</literal> (<type>text</type>)</term> <listitem> <para> - The name of the newly-created replication slot. + 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>consistent_point</literal> (<type>text</type>)</term> + <term><literal>timeline</literal> (<type>int4</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. + Current timeline ID. Also useful to check that the standby is + consistent with the primary. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>snapshot_name</literal> (<type>text</type>)</term> + <term><literal>xlogpos</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. + 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>output_plugin</literal> (<type>text</type>)</term> + <term><literal>dbname</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. + Database connected to or null. </para> </listitem> </varlistentry> </variablelist> - </para> - </listitem> - </varlistentry> + </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-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> - <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> + <term><replaceable class="parameter">name</replaceable></term> <listitem> <para> - The replication slot's type, either <literal>physical</literal> or - <literal>NULL</literal>. + 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>restart_lsn</literal> (<type>text</type>)</term> + <term><literal>filename</literal> (<type>text</type>)</term> <listitem> <para> - The replication slot's <literal>restart_lsn</literal>. + File name of the timeline history file, e.g., <filename>00000002.history</filename>. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>restart_tli</literal> (<type>int8</type>)</term> + <term><literal>content</literal> (<type>text</type>)</term> <listitem> <para> - The timeline ID associated with <literal>restart_lsn</literal>, - following the current timeline history. + Contents of the timeline history file. </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> - - <para> - <variablelist> - <varlistentry id="protocol-replication-xlogdata"> - <term> - XLogData (B) - </term> - <listitem> - <para> - <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> - </para> - </listitem> - </varlistentry> - <varlistentry id="protocol-replication-primary-keepalive-message"> - <term> - Primary keepalive message (B) - </term> - <listitem> - <para> - <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> - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - - <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> - - <para> - <variablelist> - <varlistentry id="protocol-replication-standby-status-update"> - <term> - Standby status update (F) - </term> - <listitem> - <para> - <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> - </para> - </listitem> - </varlistentry> - </variablelist> - </para> + </listitem> + </varlistentry> - <para> - <variablelist> - <varlistentry id="protocol-replication-hot-standby-feedback-message"> - <term> - Hot standby feedback message (F) - </term> - <listitem> - <para> - <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> + <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">option</replaceable> [, ...] ) ] + <indexterm><primary>CREATE_REPLICATION_SLOT</primary></indexterm> + </term> + <listitem> <para> - The epoch of the catalog_xmin xid on the standby. - </para> - </listitem> - </varlistentry> - </variablelist> + Create a physical or logical replication + slot. See <xref linkend="streaming-replication-slots"/> for more about + replication slots. </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </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> + <term><replaceable class="parameter">slot_name</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. + 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><literal>TARGET</literal> <replaceable>'target'</replaceable></term> + <term><replaceable class="parameter">output_plugin</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. + The name of the output plugin used for logical decoding + (see <xref linkend="logicaldecoding-output-plugin"/>). </para> </listitem> </varlistentry> <varlistentry> - <term><literal>TARGET_DETAIL</literal> <replaceable>'detail'</replaceable></term> + <term><literal>TEMPORARY</literal></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. + 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>PROGRESS [ <replaceable class="parameter">boolean</replaceable> ]</literal></term> + <term><literal>TWO_PHASE [ <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. + If true, this logical replication slot supports decoding of two-phase + transactions. With this option, two-phase commands like + <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>CHECKPOINT { 'fast' | 'spread' }</literal></term> + <term><literal>RESERVE_WAL [ <replaceable class="parameter">boolean</replaceable> ]</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>. + 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>WAL [ <replaceable class="parameter">boolean</replaceable> ]</literal></term> + <term><literal>SNAPSHOT { 'export' | 'use' | 'nothing' }</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. + 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> - <varlistentry> - <term><literal>WAIT [ <replaceable class="parameter">boolean</replaceable> ]</literal></term> + <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> - <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> + <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> - <term><literal>COMPRESSION</literal> <replaceable>'method'</replaceable></term> + <varlistentry id="protocol-replication-primary-keepalive-message"> + <term>Primary keepalive message (B)</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> + <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> - <varlistentry> - <term><literal>COMPRESSION_DETAIL</literal> <replaceable>detail</replaceable></term> + <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> - <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 <literal>keyword</literal> or - <literal>keyword=value</literal>. Currently, the supported keywords - are <literal>level</literal> and <literal>workers</literal>. - </para> + <variablelist> + <varlistentry> + <term>Byte1('r')</term> + <listitem> + <para> + Identifies the message as a receiver status update. + </para> + </listitem> + </varlistentry> - <para> - The <literal>level</literal> keyword sets the compression level. - For <literal>gzip</literal> the compression level should be an - integer between 1 and 9, for <literal>lz4</literal> an integer - between 1 and 12, and for <literal>zstd</literal> an integer - between 1 and 22. - </para> + <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> - <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> + <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> - <term><literal>MAX_RATE</literal> <replaceable>rate</replaceable></term> + <varlistentry id="protocol-replication-hot-standby-feedback-message"> + <term>Hot standby feedback message (F)</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> + <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>TABLESPACE_MAP [ <replaceable class="parameter">boolean</replaceable> ]</literal></term> + <term><literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable></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. + 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><literal>VERIFY_CHECKSUMS [ <replaceable class="parameter">boolean</replaceable> ]</literal></term> + <term><replaceable class="parameter">XXX/XXX</replaceable></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. + The WAL location to begin streaming at. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>MANIFEST</literal> <replaceable>manifest_option</replaceable></term> + <term><replaceable class="parameter">option_name</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>. + The name of an option passed to the slot's logical decoding plugin. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>MANIFEST_CHECKSUMS</literal> <replaceable>checksum_algorithm</replaceable></term> + <term><replaceable class="parameter">option_value</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>. + Optional value, in the form of a string constant, associated with the + specified option. </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: + </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><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> + <term><replaceable class="parameter">slot_name</replaceable></term> <listitem> <para> - The full path of the tablespace directory, or null - if it's the base directory. + The name of the slot to drop. </para> </listitem> </varlistentry> + <varlistentry> - <term><literal>size</literal> (<type>int8</type>)</term> + <term><literal>WAIT</literal></term> <listitem> <para> - The approximate size of the tablespace, in kilobytes (1024 bytes), - if progress report has been requested; otherwise it's null. + 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> - </para> + </listitem> + </varlistentry> - <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> + <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 <literal>keyword</literal> or + <literal>keyword=value</literal>. 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 1 and 9, for <literal>lz4</literal> an integer + between 1 and 12, and for <literal>zstd</literal> an integer + between 1 and 22. + </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> - <variablelist> + <para> + When the backup is started, the server will first send two + ordinary result sets, followed by one or more CopyOutResponse + results. + </para> - <varlistentry> + <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><para><variablelist> + <listitem> + <variablelist> <varlistentry> - <term>Byte1('n')</term> - <listitem><para> - Identifes the messaage 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> + <term>Byte1('n')</term> + <listitem><para> + Identifes the messaage 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> + <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> + <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></para></listitem> - </varlistentry> + </variablelist> + </listitem> + </varlistentry> - <varlistentry> + <varlistentry> <term>manifest (B)</term> - <listitem><para><variablelist> + <listitem> + <variablelist> <varlistentry> - <term>Byte1('m')</term> - <listitem><para> - Identifes the message as indicating the start of the backup - manifest. - </para></listitem> + <term>Byte1('m')</term> + <listitem><para> + Identifes the message as indicating the start of the backup + manifest. + </para></listitem> </varlistentry> - </variablelist></para></listitem> - </varlistentry> + </variablelist> + </listitem> + </varlistentry> - <varlistentry> + <varlistentry> <term>archive or manifest data (B)</term> - <listitem><para><variablelist> + <listitem> + <variablelist> <varlistentry> - <term>Byte1('d')</term> - <listitem><para> - Identifes the message as containing archive or manifest data. - </para></listitem> + <term>Byte1('d')</term> + <listitem><para> + Identifes the message as containing archive or manifest data. + </para></listitem> </varlistentry> + <varlistentry> - <term>Byte<replaceable>n</replaceable></term> - <listitem><para> - Data bytes. - </para></listitem> + <term>Byte<replaceable>n</replaceable></term> + <listitem><para> + Data bytes. + </para></listitem> </varlistentry> - </variablelist></para></listitem> - </varlistentry> + </variablelist> + </listitem> + </varlistentry> - <varlistentry> + <varlistentry> <term>progress report (B)</term> - <listitem><para><variablelist> + <listitem> + <variablelist> <varlistentry> - <term>Byte1('p')</term> - <listitem><para> - Identifes the message as a progress report. - </para></listitem> + <term>Byte1('p')</term> + <listitem><para> + Identifes 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> + <term>Int64</term> + <listitem><para> + The number of bytes from the current tablespace for which + processing has been completed. + </para></listitem> </varlistentry> - </variablelist></para></listitem> - </varlistentry> - + </variablelist> + </listitem> + </varlistentry> </variablelist> - </para> - <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> + 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> + <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: -</sect1> + <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> @@ -3184,1083 +3145,877 @@ The commands accepted in replication mode are: </sect2> </sect1> -<sect1 id="protocol-message-types"> -<title>Message Data Types</title> - -<para> -This section describes the base data types used in messages. - -<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> -</para> -</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> -<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> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-AuthenticationKerberosV5"> -<term> -AuthenticationKerberosV5 (B) -</term> -<listitem> -<para> - -<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> -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-AuthenticationCleartextPassword"> -<term> -AuthenticationCleartextPassword (B) -</term> -<listitem> -<para> - -<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> -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-AuthenticationMD5Password"> -<term> -AuthenticationMD5Password (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-AuthenticationSCMCredential"> -<term> -AuthenticationSCMCredential (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-AuthenticationGSS"> -<term> -AuthenticationGSS (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-AuthenticationGSSContinue"> -<term> -AuthenticationGSSContinue (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-AuthenticationSSPI"> -<term> -AuthenticationSSPI (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-AuthenticationSASL"> -<term> -AuthenticationSASL (B) -</term> -<listitem> -<para> - -<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> -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> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-AuthenticationSASLFinal"> -<term> -AuthenticationSASLFinal (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-BackendKeyData"> -<term> -BackendKeyData (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-Bind"> -<term> -Bind (F) -</term> -<listitem> -<para> - -<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> - Next, the following pair of fields appear for each parameter: -<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> - After the last parameter, the following fields appear: -<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> -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-BindComplete"> -<term> -BindComplete (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-CancelRequest"> -<term> -CancelRequest (F) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-Close"> -<term> -Close (F) -</term> -<listitem> -<para> - -<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> -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-CloseComplete"> -<term> -CloseComplete (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-CommandComplete"> -<term> -CommandComplete (B) -</term> -<listitem> -<para> - -<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> + <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. @@ -4317,3959 +4072,3312 @@ CommandComplete (B) (Note: the row count appears only in <productname>PostgreSQL</productname> 8.2 and later.) </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> -</listitem> -</varlistentry> -</variablelist> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-CopyData"> -<term> -CopyData (F & B) -</term> -<listitem> -<para> -<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> -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-CopyDone"> -<term> -CopyDone (F & B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-CopyFail"> -<term> -CopyFail (F) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-CopyInResponse"> -<term> -CopyInResponse (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-CopyOutResponse"> -<term> -CopyOutResponse (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-CopyBothResponse"> -<term> -CopyBothResponse (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-DataRow"> -<term> -DataRow (B) -</term> -<listitem> -<para> -<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> - Next, the following pair of fields appear for each column: -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-Describe"> -<term> -Describe (F) -</term> -<listitem> -<para> - -<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> -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-EmptyQueryResponse"> -<term> -EmptyQueryResponse (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-ErrorResponse"> -<term> -ErrorResponse (B) -</term> -<listitem> -<para> - -<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> - 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: -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-Execute"> -<term> -Execute (F) -</term> -<listitem> -<para> - -<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> -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-Flush"> -<term> -Flush (F) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-FunctionCall"> -<term> -FunctionCall (F) -</term> -<listitem> -<para> - -<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> - Next, the following pair of fields appear for each argument: -<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> - After the last argument, the following field appears: -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-FunctionCallResponse"> -<term> -FunctionCallResponse (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-GSSENCRequest"> -<term> -GSSENCRequest (F) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-GSSResponse"> -<term> -GSSResponse (F) -</term> -<listitem> -<para> - -<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> -</para> -</listitem> -</varlistentry> - -<varlistentry id="protocol-message-formats-NegotiateProtocolVersion"> -<term> -NegotiateProtocolVersion (B) -</term> -<listitem> -<para> - -<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> - Then, for protocol option not recognized by the server, there - is the following: -<variablelist> -<varlistentry> -<term> - String -</term> -<listitem> -<para> - The option name. -</para> -</listitem> -</varlistentry> -</variablelist> -</para> -</listitem> -</varlistentry> - -<varlistentry id="protocol-message-formats-NoData"> -<term> -NoData (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-NoticeResponse"> -<term> -NoticeResponse (B) -</term> -<listitem> -<para> - -<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> - 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: -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-NotificationResponse"> -<term> -NotificationResponse (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-ParameterDescription"> -<term> -ParameterDescription (B) -</term> -<listitem> -<para> - -<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> - Then, for each parameter, there is the following: -<variablelist> -<varlistentry> -<term> - Int32 -</term> -<listitem> -<para> - Specifies the object ID of the parameter data type. -</para> -</listitem> -</varlistentry> -</variablelist> -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-ParameterStatus"> -<term> -ParameterStatus (B) -</term> -<listitem> -<para> - -<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> -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-Parse"> -<term> -Parse (F) -</term> -<listitem> -<para> - -<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> - Then, for each parameter, there is the following: -<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> -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-ParseComplete"> -<term> -ParseComplete (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-PasswordMessage"> -<term> -PasswordMessage (F) -</term> -<listitem> -<para> - -<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> -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-PortalSuspended"> -<term> -PortalSuspended (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-Query"> -<term> -Query (F) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-ReadyForQuery"> -<term> -ReadyForQuery (B) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-RowDescription"> -<term> -RowDescription (B) -</term> -<listitem> -<para> - -<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> - Then, for each field, there is the following: -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-SASLInitialResponse"> -<term> -SASLInitialResponse (F) -</term> -<listitem> -<para> - -<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> -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-SASLResponse"> -<term> -SASLResponse (F) -</term> -<listitem> -<para> - -<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> -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-SSLRequest"> -<term> -SSLRequest (F) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-StartupMessage"> -<term> -StartupMessage (F) -</term> -<listitem> -<para> - -<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> - 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: -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-Sync"> -<term> -Sync (F) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -<varlistentry id="protocol-message-formats-Terminate"> -<term> -Terminate (F) -</term> -<listitem> -<para> - -<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> - -</para> -</listitem> -</varlistentry> - - -</variablelist> + <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> -</sect1> + <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> -<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> + <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> -<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> + <varlistentry> + <term>Int32(4)</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> -</sect1> + <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> -<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> -<para> - -<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> -</para> -</listitem> -</varlistentry> - -<varlistentry id="protocol-logicalrep-message-formats-Message"> -<term> -Message -</term> -<listitem> -<para> - -<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> -</para> -</listitem> -</varlistentry> - -<varlistentry id="protocol-logicalrep-message-formats-Commit"> -<term> -Commit -</term> -<listitem> -<para> - -<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> -</para> -</listitem> -</varlistentry> - -<varlistentry id="protocol-logicalrep-message-formats-Origin"> -<term> -Origin -</term> -<listitem> -<para> - -<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> - -<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> -<para> - -<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> - Next, the following message part appears for each column included in - the publication (except generated columns): -<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> -</para> -</listitem> -</varlistentry> - -<varlistentry id="protocol-logicalrep-message-formats-Type"> -<term> -Type -</term> -<listitem> -<para> - -<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> -</para> -</listitem> -</varlistentry> - -<varlistentry id="protocol-logicalrep-message-formats-Insert"> -<term> -Insert -</term> -<listitem> -<para> - -<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> -</para> -</listitem> -</varlistentry> - -<varlistentry id="protocol-logicalrep-message-formats-Update"> -<term> -Update -</term> -<listitem> -<para> - -<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> - -<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> -<para> - -<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> - -<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> -<para> - -<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> -</para> -</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> -<para> - -<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> -</para> -</listitem> -</varlistentry> - -<varlistentry id="protocol-logicalrep-message-formats-Stream-Stop"> -<term> -Stream Stop -</term> -<listitem> -<para> - -<variablelist> -<varlistentry> -<term> - Byte1('E') -</term> -<listitem> -<para> - Identifies the message as a stream stop message. -</para> -</listitem> -</varlistentry> - -</variablelist> -</para> -</listitem> -</varlistentry> - -<varlistentry id="protocol-logicalrep-message-formats-Stream-Commit"> -<term> -Stream Commit -</term> -<listitem> -<para> - -<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> -</para> -</listitem> -</varlistentry> - -<varlistentry id="protocol-logicalrep-message-formats-Stream-Abort"> -<term> -Stream Abort -</term> -<listitem> -<para> - -<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> -</para> -</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> -<para> - -<variablelist> - -<varlistentry> -<term>Byte1('b')</term> -<listitem><para> - Identifies the message as the beginning of a two-phase 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 two-phase transaction. -</para></listitem> -</varlistentry> - -</variablelist> - -</para> -</listitem> -</varlistentry> - -<varlistentry id="protocol-logicalrep-message-formats-Prepare"> - -<term>Prepare</term> -<listitem> -<para> - -<variablelist> - -<varlistentry> -<term>Byte1('P')</term> -<listitem><para> - Identifies the message as a two-phase 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 two-phase transaction. -</para></listitem> -</varlistentry> - -</variablelist> - -</para> -</listitem> -</varlistentry> - -<varlistentry id="protocol-logicalrep-message-formats-Commit-Prepared"> - -<term>Commit Prepared</term> -<listitem> -<para> - -<variablelist> - -<varlistentry> -<term>Byte1('K')</term> -<listitem><para> - Identifies the message as the commit of a two-phase 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 prepared. -</para></listitem> -</varlistentry> - -<varlistentry> -<term> - Int64 (XLogRecPtr) -</term> -<listitem><para> - The end LSN of the commit 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 two-phase transaction. -</para></listitem> -</varlistentry> - -</variablelist> - -</para> -</listitem> -</varlistentry> - -<varlistentry id="protocol-logicalrep-message-formats-Rollback-Prepared"> - -<term>Rollback Prepared</term> -<listitem> -<para> - -<variablelist> - -<varlistentry> -<term>Byte1('r')</term> -<listitem><para> - Identifies the message as the rollback of a two-phase 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 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 two-phase transaction. -</para></listitem> -</varlistentry> - -</variablelist> - -</para> -</listitem> -</varlistentry> - -<varlistentry id="protocol-logicalrep-message-formats-Stream-Prepare"> - -<term>Stream Prepare</term> -<listitem> -<para> - -<variablelist> - -<varlistentry> -<term>Byte1('p')</term> -<listitem><para> - Identifies the message as a two-phase stream prepare 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 prepare 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 two-phase transaction. -</para></listitem> -</varlistentry> - -</variablelist> - -</para> -</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> -<para> - -<variablelist> -<varlistentry> -<term> - Int16 -</term> -<listitem> -<para> - Number of columns. -</para> -</listitem> -</varlistentry> -</variablelist> - 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> + <varlistentry> + <term>String</term> + <listitem> + <para> + An error message to report as the cause of failure. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> -</sect1> + <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> -<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> + <varlistentry> + <term>Int32</term> + <listitem> + <para> + Length of message contents in bytes, including self. + </para> + </listitem> + </varlistentry> -</sect1> + <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 two-phase 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 two-phase 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 two-phase 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 two-phase 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 two-phase 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 prepared. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Int64 (XLogRecPtr)</term> + <listitem> + <para> + The end LSN of the commit 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 two-phase 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 two-phase 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 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 two-phase 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 two-phase stream prepare 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 prepare 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 two-phase 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> |