</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>
+ 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>The following options are supported:</para>
+ <para>
+ In either physical replication or logical replication walsender mode, only the
+ simple query protocol can be used.
+ </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>
+ 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>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>
+ Replication commands are logged in the server log when
+ <xref linkend="guc-log-replication-commands"/> is enabled.
+ </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>
+ The commands accepted in replication mode are:
- <para>
- In response to this command, the server will send a one-row result set
- containing the following fields:
+ <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>
+ </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>
+ <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>
+ Create a physical or logical replication
+ slot. See <xref linkend="streaming-replication-slots"/> for more about
+ replication slots.
+ </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>
+ <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>
- <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>
+ <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>
- <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>
+ <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>
- 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>The following options are supported:</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>
+ <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>
+
+ <varlistentry>
+ <term><literal>RESERVE_WAL [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
+ <listitem>
+ <para>
+ If true, this physical replication slot reserves <acronym>WAL</acronym>
+ immediately. Otherwise, <acronym>WAL</acronym> is only reserved upon
+ connection from a streaming replication client.
+ The default is false.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>SNAPSHOT { 'export' | 'use' | 'nothing' }</literal></term>
+ <listitem>
+ <para>
+ Decides what to do with the snapshot created during logical slot
+ initialization. <literal>'export'</literal>, which is the default,
+ will export the snapshot for use in other sessions. This option can't
+ be used inside a transaction. <literal>'use'</literal> will use the
+ snapshot for the current transaction executing the command. This
+ option must be used in a transaction, and
+ <literal>CREATE_REPLICATION_SLOT</literal> must be the first command
+ run in that transaction. Finally, <literal>'nothing'</literal> will
+ just use the snapshot for logical decoding as normal but won't do
+ anything else with it.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ In response to this command, the server will send a one-row result set
+ containing the following fields:
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>slot_name</literal> (<type>text</type>)</term>
+ <listitem>
+ <para>
+ The name of the newly-created replication slot.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>consistent_point</literal> (<type>text</type>)</term>
+ <listitem>
+ <para>
+ The WAL location at which the slot became consistent. This is the
+ earliest location from which streaming can start on this replication
+ slot.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>snapshot_name</literal> (<type>text</type>)</term>
+ <listitem>
+ <para>
+ The identifier of the snapshot exported by the command. The
+ snapshot is valid until a new command is executed on this connection
+ or the replication connection is closed. Null if the created slot
+ is physical.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>output_plugin</literal> (<type>text</type>)</term>
+ <listitem>
+ <para>
+ The name of the output plugin used by the newly-created replication
+ slot. Null if the created slot is physical.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-replication-create-replication-slot-legacy">
+ <term><literal>CREATE_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable> [ <literal>TEMPORARY</literal> ] { <literal>PHYSICAL</literal> [ <literal>RESERVE_WAL</literal> ] | <literal>LOGICAL</literal> <replaceable class="parameter">output_plugin</replaceable> [ <literal>EXPORT_SNAPSHOT</literal> | <literal>NOEXPORT_SNAPSHOT</literal> | <literal>USE_SNAPSHOT</literal> | <literal>TWO_PHASE</literal> ] }
+ </term>
+ <listitem>
+ <para>
+ For compatibility with older releases, this alternative syntax for
+ the <literal>CREATE_REPLICATION_SLOT</literal> command is still supported.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-replication-read-replication-slot">
+ <term><literal>READ_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable>
+ <indexterm><primary>READ_REPLICATION_SLOT</primary></indexterm>
+ </term>
+ <listitem>
+ <para>
+ Read some information associated with a replication slot. Returns a tuple
+ with <literal>NULL</literal> values if the replication slot does not
+ exist. This command is currently only supported for physical replication
+ slots.
+ </para>
+
+ <para>
+ In response to this command, the server will return a one-row result set,
+ containing the following fields:
+ <variablelist>
+ <varlistentry>
+ <term><literal>slot_type</literal> (<type>text</type>)</term>
+ <listitem>
+ <para>
+ The replication slot's type, either <literal>physical</literal> or
+ <literal>NULL</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>restart_lsn</literal> (<type>text</type>)</term>
+ <listitem>
+ <para>
+ The replication slot's <literal>restart_lsn</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>restart_tli</literal> (<type>int8</type>)</term>
+ <listitem>
+ <para>
+ The timeline ID associated with <literal>restart_lsn</literal>,
+ following the current timeline history.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-replication-start-replication">
+ <term><literal>START_REPLICATION</literal> [ <literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable> ] [ <literal>PHYSICAL</literal> ] <replaceable class="parameter">XXX/XXX</replaceable> [ <literal>TIMELINE</literal> <replaceable class="parameter">tli</replaceable> ]
+ <indexterm><primary>START_REPLICATION</primary></indexterm>
+ </term>
+ <listitem>
+ <para>
+ Instructs server to start streaming WAL, starting at
+ WAL location <replaceable class="parameter">XXX/XXX</replaceable>.
+ If <literal>TIMELINE</literal> option is specified,
+ streaming starts on timeline <replaceable class="parameter">tli</replaceable>;
+ otherwise, the server's current timeline is selected. The server can
+ reply with an error, for example if the requested section of WAL has already
+ been recycled. On success, the server responds with a CopyBothResponse
+ message, and then starts to stream WAL to the frontend.
+ </para>
+
+ <para>
+ If a slot's name is provided
+ via <replaceable class="parameter">slot_name</replaceable>, it will be updated
+ as replication progresses so that the server knows which WAL segments,
+ and if <varname>hot_standby_feedback</varname> is on which transactions,
+ are still needed by the standby.
+ </para>
+
+ <para>
+ If the client requests a timeline that's not the latest but is part of
+ the history of the server, the server will stream all the WAL on that
+ timeline starting from the requested start point up to the point where
+ the server switched to another timeline. If the client requests
+ streaming at exactly the end of an old timeline, the server skips COPY
+ mode entirely.
+ </para>
+
+ <para>
+ After streaming all the WAL on a timeline that is not the latest one,
+ the server will end streaming by exiting the COPY mode. When the client
+ acknowledges this by also exiting COPY mode, the server sends a result
+ set with one row and two columns, indicating the next timeline in this
+ server's history. The first column is the next timeline's ID (type <type>int8</type>), and the
+ second column is the WAL location where the switch happened (type <type>text</type>). Usually,
+ the switch position is the end of the WAL that was streamed, but there
+ are corner cases where the server can send some WAL from the old
+ timeline that it has not itself replayed before promoting. Finally, the
+ server sends two CommandComplete messages (one that ends the CopyData
+ and the other ends the <literal>START_REPLICATION</literal> itself), and
+ is ready to accept a new command.
+ </para>
+
+ <para>
+ WAL data is sent as a series of CopyData messages. (This allows
+ other information to be intermixed; in particular the server can send
+ an ErrorResponse message if it encounters a failure after beginning
+ to stream.) The payload of each CopyData message from server to the
+ client contains a message of one of the following formats:
+ </para>
+
+ <variablelist>
+ <varlistentry id="protocol-replication-xlogdata">
+ <term>XLogData (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('w')</term>
+ <listitem>
+ <para>
+ Identifies the message as WAL data.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64</term>
+ <listitem>
+ <para>
+ The starting point of the WAL data in this message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64</term>
+ <listitem>
+ <para>
+ The current end of WAL on the server.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64</term>
+ <listitem>
+ <para>
+ The server's system clock at the time of transmission, as
+ microseconds since midnight on 2000-01-01.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte<replaceable>n</replaceable></term>
+ <listitem>
+ <para>
+ A section of the WAL data stream.
+ </para>
+
+ <para>
+ A single WAL record is never split across two XLogData messages.
+ When a WAL record crosses a WAL page boundary, and is therefore
+ already split using continuation records, it can be split at the page
+ boundary. In other words, the first main WAL record and its
+ continuation records can be sent in different XLogData messages.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-replication-primary-keepalive-message">
+ <term>Primary keepalive message (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('k')</term>
+ <listitem>
+ <para>
+ Identifies the message as a sender keepalive.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64</term>
+ <listitem>
+ <para>
+ The current end of WAL on the server.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64</term>
+ <listitem>
+ <para>
+ The server's system clock at the time of transmission, as
+ microseconds since midnight on 2000-01-01.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte1</term>
+ <listitem>
+ <para>
+ 1 means that the client should reply to this message as soon as
+ possible, to avoid a timeout disconnect. 0 otherwise.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The receiving process can send replies back to the sender at any time,
+ using one of the following message formats (also in the payload of a
+ CopyData message):
+ </para>
+
+ <variablelist>
+ <varlistentry id="protocol-replication-standby-status-update">
+ <term>Standby status update (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('r')</term>
+ <listitem>
+ <para>
+ Identifies the message as a receiver status update.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64</term>
+ <listitem>
+ <para>
+ The location of the last WAL byte + 1 received and written to disk
+ in the standby.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64</term>
+ <listitem>
+ <para>
+ The location of the last WAL byte + 1 flushed to disk in
+ the standby.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64</term>
+ <listitem>
+ <para>
+ The location of the last WAL byte + 1 applied in the standby.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64</term>
+ <listitem>
+ <para>
+ The client's system clock at the time of transmission, as
+ microseconds since midnight on 2000-01-01.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte1</term>
+ <listitem>
+ <para>
+ If 1, the client requests the server to reply to this message
+ immediately. This can be used to ping the server, to test if
+ the connection is still healthy.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-replication-hot-standby-feedback-message">
+ <term>Hot standby feedback message (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('h')</term>
+ <listitem>
+ <para>
+ Identifies the message as a hot standby feedback message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64</term>
+ <listitem>
+ <para>
+ The client's system clock at the time of transmission, as
+ microseconds since midnight on 2000-01-01.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ The standby's current global xmin, excluding the catalog_xmin from any
+ replication slots. If both this value and the following
+ catalog_xmin are 0 this is treated as a notification that hot standby
+ feedback will no longer be sent on this connection. Later non-zero
+ messages may reinitiate the feedback mechanism.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ The epoch of the global xmin xid on the standby.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ The lowest catalog_xmin of any replication slots on the standby. Set to 0
+ if no catalog_xmin exists on the standby or if hot standby feedback is being
+ disabled.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ The epoch of the catalog_xmin xid on the standby.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-replication-start-replication-slot-logical">
+ <term><literal>START_REPLICATION</literal> <literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable> <literal>LOGICAL</literal> <replaceable class="parameter">XXX/XXX</replaceable> [ ( <replaceable>option_name</replaceable> [ <replaceable>option_value</replaceable> ] [, ...] ) ]</term>
+ <listitem>
+ <para>
+ Instructs server to start streaming WAL for logical replication,
+ starting at either WAL location <replaceable
+ class="parameter">XXX/XXX</replaceable> or the slot's
+ <literal>confirmed_flush_lsn</literal> (see <xref
+ linkend="view-pg-replication-slots"/>), whichever is greater. This
+ behavior makes it easier for clients to avoid updating their local LSN
+ status when there is no data to process. However, starting at a
+ different LSN than requested might not catch certain kinds of client
+ errors; so the client may wish to check that
+ <literal>confirmed_flush_lsn</literal> matches its expectations before
+ issuing <literal>START_REPLICATION</literal>.
+ </para>
+
+ <para>
+ The server can reply with an error, for example if the
+ slot does not exist. On success, the server responds with a CopyBothResponse
+ message, and then starts to stream WAL to the frontend.
+ </para>
+
+ <para>
+ The messages inside the CopyBothResponse messages are of the same format
+ documented for <literal>START_REPLICATION ... PHYSICAL</literal>, including
+ two CommandComplete messages.
+ </para>
+
+ <para>
+ The output plugin associated with the selected slot is used
+ to process the output for streaming.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable></term>
+ <listitem>
+ <para>
+ The name of the slot to stream changes from. This parameter is required,
+ and must correspond to an existing logical replication slot created
+ with <literal>CREATE_REPLICATION_SLOT</literal> in
+ <literal>LOGICAL</literal> mode.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable class="parameter">XXX/XXX</replaceable></term>
+ <listitem>
+ <para>
+ The WAL location to begin streaming at.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable class="parameter">option_name</replaceable></term>
+ <listitem>
+ <para>
+ The name of an option passed to the slot's logical decoding plugin.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable class="parameter">option_value</replaceable></term>
+ <listitem>
+ <para>
+ Optional value, in the form of a string constant, associated with the
+ specified option.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-replication-drop-replication-slot">
+ <term>
+ <literal>DROP_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable> <optional> <literal>WAIT</literal> </optional>
+ <indexterm><primary>DROP_REPLICATION_SLOT</primary></indexterm>
+ </term>
+ <listitem>
+ <para>
+ Drops a replication slot, freeing any reserved server-side resources.
+ If the slot is a logical slot that was created in a database other than
+ the database the walsender is connected to, this command fails.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><replaceable class="parameter">slot_name</replaceable></term>
+ <listitem>
+ <para>
+ The name of the slot to drop.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>WAIT</literal></term>
+ <listitem>
+ <para>
+ This option causes the command to wait if the slot is active until
+ it becomes inactive, instead of the default behavior of raising an
+ error.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-replication-base-backup" xreflabel="BASE_BACKUP">
+ <term><literal>BASE_BACKUP</literal> [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ]
+ <indexterm><primary>BASE_BACKUP</primary></indexterm>
+ </term>
+ <listitem>
+ <para>
+ Instructs the server to start streaming a base backup.
+ The system will automatically be put in backup mode before the backup
+ is started, and taken out of it when the backup is complete. The
+ following options are accepted:
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>LABEL</literal> <replaceable>'label'</replaceable></term>
+ <listitem>
+ <para>
+ Sets the label of the backup. If none is specified, a backup label
+ of <literal>base backup</literal> will be used. The quoting rules
+ for the label are the same as a standard SQL string with
+ <xref linkend="guc-standard-conforming-strings"/> turned on.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>TARGET</literal> <replaceable>'target'</replaceable></term>
+ <listitem>
+ <para>
+ Tells the server where to send the backup. If the target is
+ <literal>client</literal>, which is the default, the backup data is
+ sent to the client. If it is <literal>server</literal>, the backup
+ data is written to the server at the pathname specified by the
+ <literal>TARGET_DETAIL</literal> option. If it is
+ <literal>blackhole</literal>, the backup data is not sent
+ anywhere; it is simply discarded.
+ </para>
+
+ <para>
+ The <literal>server</literal> target requires superuser privilege or
+ being granted the <literal>pg_write_server_files</literal> role.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>TARGET_DETAIL</literal> <replaceable>'detail'</replaceable></term>
+ <listitem>
+ <para>
+ Provides additional information about the backup target.
+ </para>
+
+ <para>
+ Currently, this option can only be used when the backup target is
+ <literal>server</literal>. It specifies the server directory
+ to which the backup should be written.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>PROGRESS [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
+ <listitem>
+ <para>
+ If set to true, request information required to generate a progress
+ report. This will send back an approximate size in the header of each
+ tablespace, which can be used to calculate how far along the stream
+ is done. This is calculated by enumerating all the file sizes once
+ before the transfer is even started, and might as such have a
+ negative impact on the performance. In particular, it might take
+ longer before the first data
+ is streamed. Since the database files can change during the backup,
+ the size is only approximate and might both grow and shrink between
+ the time of approximation and the sending of the actual files.
+ The default is false.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>CHECKPOINT { 'fast' | 'spread' }</literal></term>
+ <listitem>
+ <para>
+ Sets the type of checkpoint to be performed at the beginning of the
+ base backup. The default is <literal>spread</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>WAL [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
+ <listitem>
+ <para>
+ If set to true, include the necessary WAL segments in the backup.
+ This will include all the files between start and stop backup in the
+ <filename>pg_wal</filename> directory of the base directory tar
+ file. The default is false.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>WAIT [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
+ <listitem>
+ <para>
+ If set to true, the backup will wait until the last required WAL
+ segment has been archived, or emit a warning if log archiving is
+ not enabled. If false, the backup will neither wait nor warn,
+ leaving the client responsible for ensuring the required log is
+ available. The default is true.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>COMPRESSION</literal> <replaceable>'method'</replaceable></term>
+ <listitem>
+ <para>
+ Instructs the server to compress the backup using the specified
+ method. Currently, the supported methods are <literal>gzip</literal>,
+ <literal>lz4</literal>, and <literal>zstd</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>COMPRESSION_DETAIL</literal> <replaceable>detail</replaceable></term>
+ <listitem>
+ <para>
+ Specifies details for the chosen compression method. This should only
+ be used in conjunction with the <literal>COMPRESSION</literal>
+ option. If the value is an integer, it specifies the compression
+ level. Otherwise, it should be a comma-separated list of items,
+ each of the form <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>
+ When the backup is started, the server will first send two
+ ordinary result sets, followed by one or more CopyOutResponse
+ results.
+ </para>
+
+ <para>
+ The first ordinary result set contains the starting position of the
+ backup, in a single row with two columns. The first column contains
+ the start position given in XLogRecPtr format, and the second column
+ contains the corresponding timeline ID.
+ </para>
+
+ <para>
+ The second ordinary result set has one row for each tablespace.
+ The fields in this row are:
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>spcoid</literal> (<type>oid</type>)</term>
+ <listitem>
+ <para>
+ The OID of the tablespace, or null if it's the base
+ directory.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>spclocation</literal> (<type>text</type>)</term>
+ <listitem>
+ <para>
+ The full path of the tablespace directory, or null
+ if it's the base directory.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>size</literal> (<type>int8</type>)</term>
+ <listitem>
+ <para>
+ The approximate size of the tablespace, in kilobytes (1024 bytes),
+ if progress report has been requested; otherwise it's null.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ After the second regular result set, a CopyOutResponse will be sent.
+ The payload of each CopyData message will contain a message in one of
+ the following formats:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>new archive (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('n')</term>
+ <listitem><para>
+ 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>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem><para>
+ For the main data directory, an empty string. For other
+ tablespaces, the full path to the directory from which this
+ archive was created.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>manifest (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('m')</term>
+ <listitem><para>
+ Identifes the message as indicating the start of the backup
+ manifest.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>archive or manifest data (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('d')</term>
+ <listitem><para>
+ 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>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>progress report (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <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>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ After the CopyOutResponse, or all such responses, have been sent, a
+ final ordinary result set will be sent, containing the WAL end position
+ of the backup, in the same format as the start position.
+ </para>
+
+ <para>
+ The tar archive for the data directory and each tablespace will contain
+ all files in the directories, regardless of whether they are
+ <productname>PostgreSQL</productname> files or other files added to the same
+ directory. The only excluded files are:
+
+ <itemizedlist spacing="compact" mark="bullet">
+ <listitem>
+ <para>
+ <filename>postmaster.pid</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>postmaster.opts</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>pg_internal.init</filename> (found in multiple directories)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Various temporary files and directories created during the operation
+ of the PostgreSQL server, such as any file or directory beginning
+ with <filename>pgsql_tmp</filename> and temporary relations.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Unlogged relations, except for the init fork which is required to
+ recreate the (empty) unlogged relation on recovery.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>pg_wal</filename>, including subdirectories. If the backup is run
+ with WAL files included, a synthesized version of <filename>pg_wal</filename> will be
+ included, but it will only contain the files necessary for the
+ backup to work, not the rest of the contents.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>pg_dynshmem</filename>, <filename>pg_notify</filename>,
+ <filename>pg_replslot</filename>, <filename>pg_serial</filename>,
+ <filename>pg_snapshots</filename>, <filename>pg_stat_tmp</filename>, and
+ <filename>pg_subtrans</filename> are copied as empty directories (even if
+ they are symbolic links).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Files other than regular files and directories, such as symbolic
+ links (other than for the directories listed above) and special
+ device files, are skipped. (Symbolic links
+ in <filename>pg_tblspc</filename> are maintained.)
+ </para>
+ </listitem>
+ </itemizedlist>
+ Owner, group, and file mode are set if the underlying file system on
+ the server supports it.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect1>
+
+<sect1 id="protocol-logical-replication">
+ <title>Logical Streaming Replication Protocol</title>
+
+ <para>
+ This section describes the logical replication protocol, which is the message
+ flow started by the <literal>START_REPLICATION</literal>
+ <literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable>
+ <literal>LOGICAL</literal> replication command.
+ </para>
+
+ <para>
+ The logical streaming replication protocol builds on the primitives of
+ the physical streaming replication protocol.
+ </para>
+
+ <sect2 id="protocol-logical-replication-params">
+ <title>Logical Streaming Replication Parameters</title>
+
+ <para>
+ The logical replication <literal>START_REPLICATION</literal> command
+ accepts following parameters:
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ proto_version
+ </term>
+ <listitem>
+ <para>
+ Protocol version. Currently versions <literal>1</literal>, <literal>2</literal>,
+ and <literal>3</literal> are supported.
+ </para>
+ <para>
+ Version <literal>2</literal> is supported only for server version 14
+ and above, and it allows streaming of large in-progress transactions.
+ </para>
+ <para>
+ Version <literal>3</literal> is supported only for server version 15
+ and above, and it allows streaming of two-phase transactions.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ publication_names
+ </term>
+ <listitem>
+ <para>
+ Comma separated list of publication names for which to subscribe
+ (receive changes). The individual publication names are treated
+ as standard objects names and can be quoted the same as needed.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+ </sect2>
+
+ <sect2 id="protocol-logical-messages">
+ <title>Logical Replication Protocol Messages</title>
+
+ <para>
+ The individual protocol messages are discussed in the following
+ subsections. Individual messages are described in
+ <xref linkend="protocol-logicalrep-message-formats"/>.
+ </para>
+
+ <para>
+ All top-level protocol messages begin with a message type byte.
+ While represented in code as a character, this is a signed byte with no
+ associated encoding.
+ </para>
+
+ <para>
+ Since the streaming replication protocol supplies a message length there
+ is no need for top-level protocol messages to embed a length in their
+ header.
+ </para>
+
+ </sect2>
+
+ <sect2 id="protocol-logical-messages-flow">
+ <title>Logical Replication Protocol Message Flow</title>
+
+ <para>
+ With the exception of the <literal>START_REPLICATION</literal> command and
+ the replay progress messages, all information flows only from the backend
+ to the frontend.
+ </para>
+
+ <para>
+ The logical replication protocol sends individual transactions one by one.
+ This means that all messages between a pair of Begin and Commit messages
+ belong to the same transaction. Similarly, all messages between a pair of
+ Begin Prepare and Prepare messages belong to the same transaction.
+ It also sends changes of large in-progress transactions between a pair of
+ Stream Start and Stream Stop messages. The last stream of such a transaction
+ contains a Stream Commit or Stream Abort message.
+ </para>
+
+ <para>
+ Every sent transaction contains zero or more DML messages (Insert,
+ Update, Delete). In case of a cascaded setup it can also contain Origin
+ messages. The origin message indicates that the transaction originated on
+ different replication node. Since a replication node in the scope of logical
+ replication protocol can be pretty much anything, the only identifier
+ is the origin name. It's downstream's responsibility to handle this as
+ needed (if needed). The Origin message is always sent before any DML
+ messages in the transaction.
+ </para>
+
+ <para>
+ Every DML message contains a relation OID, identifying the publisher's
+ relation that was acted on. Before the first DML message for a given
+ relation OID, a Relation message will be sent, describing the schema of
+ that relation. Subsequently, a new Relation message will be sent if
+ the relation's definition has changed since the last Relation message
+ was sent for it. (The protocol assumes that the client is capable of
+ remembering this metadata for as many relations as needed.)
+ </para>
+
+ <para>
+ Relation messages identify column types by their OIDs. In the case
+ of a built-in type, it is assumed that the client can look up that
+ type OID locally, so no additional data is needed. For a non-built-in
+ type OID, a Type message will be sent before the Relation message,
+ to provide the type name associated with that OID. Thus, a client that
+ needs to specifically identify the types of relation columns should
+ cache the contents of Type messages, and first consult that cache to
+ see if the type OID is defined there. If not, look up the type OID
+ locally.
+ </para>
+ </sect2>
+</sect1>
+
+ <sect1 id="protocol-message-types">
+ <title>Message Data Types</title>
+
+ <para>
+ This section describes the base data types used in messages.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Int<replaceable>n</replaceable>(<replaceable>i</replaceable>)</term>
+ <listitem>
+ <para>
+ An <replaceable>n</replaceable>-bit integer in network byte
+ order (most significant byte first).
+ If <replaceable>i</replaceable> is specified it
+ is the exact value that will appear, otherwise the value
+ is variable. Eg. Int16, Int32(42).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int<replaceable>n</replaceable>[<replaceable>k</replaceable>]</term>
+ <listitem>
+ <para>
+ An array of <replaceable>k</replaceable>
+ <replaceable>n</replaceable>-bit integers, each in network
+ byte order. The array length <replaceable>k</replaceable>
+ is always determined by an earlier field in the message.
+ Eg. Int16[M].
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String(<replaceable>s</replaceable>)</term>
+ <listitem>
+ <para>
+ A null-terminated string (C-style string). There is no
+ specific length limitation on strings.
+ If <replaceable>s</replaceable> is specified it is the exact
+ value that will appear, otherwise the value is variable.
+ Eg. String, String("user").
+ </para>
+
+ <note>
+ <para>
+ <emphasis>There is no predefined limit</emphasis> on the length of a string
+ that can be returned by the backend. Good coding strategy for a frontend
+ is to use an expandable buffer so that anything that fits in memory can be
+ accepted. If that's not feasible, read the full string and discard trailing
+ characters that don't fit into your fixed-size buffer.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte<replaceable>n</replaceable>(<replaceable>c</replaceable>)</term>
+ <listitem>
+ <para>
+ Exactly <replaceable>n</replaceable> bytes. If the field
+ width <replaceable>n</replaceable> is not a constant, it is
+ always determinable from an earlier field in the message.
+ If <replaceable>c</replaceable> is specified it is the exact
+ value. Eg. Byte2, Byte1('\n').
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+
+ <sect1 id="protocol-message-formats">
+ <title>Message Formats</title>
+
+ <para>
+ This section describes the detailed format of each message. Each is marked to
+ indicate that it can be sent by a frontend (F), a backend (B), or both
+ (F & B).
+ Notice that although each message includes a byte count at the beginning,
+ the message format is defined so that the message end can be found without
+ reference to the byte count. This aids validity checking. (The CopyData
+ message is an exception, because it forms part of a data stream; the contents
+ of any individual CopyData message cannot be interpretable on their own.)
+ </para>
+
+ <variablelist>
+ <varlistentry id="protocol-message-formats-AuthenticationOk">
+ <term>AuthenticationOk (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('R')</term>
+ <listitem>
+ <para>
+ Identifies the message as an authentication request.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(8)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(0)</term>
+ <listitem>
+ <para>
+ Specifies that the authentication was successful.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-AuthenticationKerberosV5">
+ <term>AuthenticationKerberosV5 (B)</term>
+ <listitem>
+
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('R')</term>
+ <listitem>
+ <para>
+ Identifies the message as an authentication request.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(8)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(2)</term>
+ <listitem>
+ <para>
+ Specifies that Kerberos V5 authentication is required.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-AuthenticationCleartextPassword">
+ <term>AuthenticationCleartextPassword (B)</term>
+ <listitem>
+
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('R')</term>
+ <listitem>
+ <para>
+ Identifies the message as an authentication request.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(8)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(3)</term>
+ <listitem>
+ <para>
+ Specifies that a clear-text password is required.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-AuthenticationMD5Password">
+ <term>AuthenticationMD5Password (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('R')</term>
+ <listitem>
+ <para>
+ Identifies the message as an authentication request.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(12)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(5)</term>
+ <listitem>
+ <para>
+ Specifies that an MD5-encrypted password is required.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte4</term>
+ <listitem>
+ <para>
+ The salt to use when encrypting the password.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-AuthenticationSCMCredential">
+ <term>AuthenticationSCMCredential (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('R')</term>
+ <listitem>
+ <para>
+ Identifies the message as an authentication request.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(8)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(6)</term>
+ <listitem>
+ <para>
+ Specifies that an SCM credentials message is required.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-AuthenticationGSS">
+ <term>AuthenticationGSS (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('R')</term>
+ <listitem>
+ <para>
+ Identifies the message as an authentication request.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Int32(8)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(7)</term>
+ <listitem>
+ <para>
+ Specifies that GSSAPI authentication is required.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-AuthenticationGSSContinue">
+ <term>AuthenticationGSSContinue (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('R')</term>
+ <listitem>
+ <para>
+ Identifies the message as an authentication request.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(8)</term>
+ <listitem>
+ <para>
+ Specifies that this message contains GSSAPI or SSPI data.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte<replaceable>n</replaceable></term>
+ <listitem>
+ <para>
+ GSSAPI or SSPI authentication data.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-AuthenticationSSPI">
+ <term>AuthenticationSSPI (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('R')</term>
+ <listitem>
+ <para>
+ Identifies the message as an authentication request.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(8)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(9)</term>
+ <listitem>
+ <para>
+ Specifies that SSPI authentication is required.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-AuthenticationSASL">
+ <term>AuthenticationSASL (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('R')</term>
+ <listitem>
+ <para>
+ Identifies the message as an authentication request.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(10)</term>
+ <listitem>
+ <para>
+ Specifies that SASL authentication is required.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The message body is a list of SASL authentication mechanisms, in the
+ server's order of preference. A zero byte is required as terminator after
+ the last authentication mechanism name. For each mechanism, there is the
+ following:
+
+ <variablelist>
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ Name of a SASL authentication mechanism.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-AuthenticationSASLContinue">
+ <term>AuthenticationSASLContinue (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('R')</term>
+ <listitem>
+ <para>
+ Identifies the message as an authentication request.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(11)</term>
+ <listitem>
+ <para>
+ Specifies that this message contains a SASL challenge.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte<replaceable>n</replaceable></term>
+ <listitem>
+ <para>
+ SASL data, specific to the SASL mechanism being used.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-AuthenticationSASLFinal">
+ <term>AuthenticationSASLFinal (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('R')</term>
+ <listitem>
+ <para>
+ Identifies the message as an authentication request.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(12)</term>
+ <listitem>
+ <para>
+ Specifies that SASL authentication has completed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte<replaceable>n</replaceable></term>
+ <listitem>
+ <para>
+ SASL outcome "additional data", specific to the SASL mechanism
+ being used.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-BackendKeyData">
+ <term>BackendKeyData (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('K')</term>
+ <listitem>
+ <para>
+ Identifies the message as cancellation key data.
+ The frontend must save these values if it wishes to be
+ able to issue CancelRequest messages later.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(12)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ The process ID of this backend.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ The secret key of this backend.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-Bind">
+ <term>Bind (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('B')</term>
+ <listitem>
+ <para>
+ Identifies the message as a Bind command.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The name of the destination portal
+ (an empty string selects the unnamed portal).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The name of the source prepared statement
+ (an empty string selects the unnamed prepared statement).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16</term>
+ <listitem>
+ <para>
+ The number of parameter format codes that follow
+ (denoted <replaceable>C</replaceable> below).
+ This can be zero to indicate that there are no parameters
+ or that the parameters all use the default format (text);
+ or one, in which case the specified format code is applied
+ to all parameters; or it can equal the actual number of
+ parameters.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16[<replaceable>C</replaceable>]</term>
+ <listitem>
+ <para>
+ The parameter format codes. Each must presently be
+ zero (text) or one (binary).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16</term>
+ <listitem>
+ <para>
+ The number of parameter values that follow (possibly zero).
+ This must match the number of parameters needed by the query.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Next, the following pair of fields appear for each parameter:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ The length of the parameter value, in bytes (this count
+ does not include itself). Can be zero.
+ As a special case, -1 indicates a NULL parameter value.
+ No value bytes follow in the NULL case.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte<replaceable>n</replaceable></term>
+ <listitem>
+ <para>
+ The value of the parameter, in the format indicated by the
+ associated format code.
+ <replaceable>n</replaceable> is the above length.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ After the last parameter, the following fields appear:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Int16</term>
+ <listitem>
+ <para>
+ The number of result-column format codes that follow
+ (denoted <replaceable>R</replaceable> below).
+ This can be zero to indicate that there are no result columns
+ or that the result columns should all use the default format
+ (text);
+ or one, in which case the specified format code is applied
+ to all result columns (if any); or it can equal the actual
+ number of result columns of the query.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16[<replaceable>R</replaceable>]</term>
+ <listitem>
+ <para>
+ The result-column format codes. Each must presently be
+ zero (text) or one (binary).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-BindComplete">
+ <term>BindComplete (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('2')</term>
+ <listitem>
+ <para>
+ Identifies the message as a Bind-complete indicator.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(4)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-CancelRequest">
+ <term>CancelRequest (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Int32(16)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(80877102)</term>
+ <listitem>
+ <para>
+ The cancel request code. The value is chosen to contain
+ <literal>1234</literal> in the most significant 16 bits, and <literal>5678</literal> in the
+ least significant 16 bits. (To avoid confusion, this code
+ must not be the same as any protocol version number.)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ The process ID of the target backend.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ The secret key for the target backend.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-Close">
+ <term>Close (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('C')</term>
+ <listitem>
+ <para>
+ Identifies the message as a Close command.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte1</term>
+ <listitem>
+ <para>
+ '<literal>S</literal>' to close a prepared statement; or
+ '<literal>P</literal>' to close a portal.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The name of the prepared statement or portal to close
+ (an empty string selects the unnamed prepared statement
+ or portal).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-CloseComplete">
+ <term>CloseComplete (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('3')</term>
+ <listitem>
+ <para>
+ Identifies the message as a Close-complete indicator.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(4)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-CommandComplete">
+ <term>CommandComplete (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('C')</term>
+ <listitem>
+ <para>
+ Identifies the message as a command-completed response.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The command tag. This is usually a single
+ word that identifies which SQL command was completed.
+ </para>
+
+ <para>
+ For an <command>INSERT</command> command, the tag is
+ <literal>INSERT <replaceable>oid</replaceable>
+ <replaceable>rows</replaceable></literal>, where
+ <replaceable>rows</replaceable> is the number of rows
+ inserted. <replaceable>oid</replaceable> used to be the object ID
+ of the inserted row if <replaceable>rows</replaceable> was 1
+ and the target table had OIDs, but OIDs system columns are
+ not supported anymore; therefore <replaceable>oid</replaceable>
+ is always 0.
+ </para>
+
+ <para>
+ For a <command>DELETE</command> command, the tag is
+ <literal>DELETE <replaceable>rows</replaceable></literal> where
+ <replaceable>rows</replaceable> is the number of rows deleted.
+ </para>
+
+ <para>
+ For an <command>UPDATE</command> command, the tag is
+ <literal>UPDATE <replaceable>rows</replaceable></literal> where
+ <replaceable>rows</replaceable> is the number of rows updated.
+ </para>
+
+ <para>
+ For a <command>SELECT</command> or <command>CREATE TABLE AS</command>
+ command, the tag is <literal>SELECT <replaceable>rows</replaceable></literal>
+ where <replaceable>rows</replaceable> is the number of rows retrieved.
+ </para>
+
+ <para>
+ For a <command>MOVE</command> command, the tag is
+ <literal>MOVE <replaceable>rows</replaceable></literal> where
+ <replaceable>rows</replaceable> is the number of rows the
+ cursor's position has been changed by.
+ </para>
+
+ <para>
+ For a <command>FETCH</command> command, the tag is
+ <literal>FETCH <replaceable>rows</replaceable></literal> where
+ <replaceable>rows</replaceable> is the number of rows that
+ have been retrieved from the cursor.
+ </para>
+
+ <para>
+ For a <command>COPY</command> command, the tag is
+ <literal>COPY <replaceable>rows</replaceable></literal> where
+ <replaceable>rows</replaceable> is the number of rows copied.
+ (Note: the row count appears only in
+ <productname>PostgreSQL</productname> 8.2 and later.)
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-CopyData">
+ <term>CopyData (F & B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('d')</term>
+ <listitem>
+ <para>
+ Identifies the message as <command>COPY</command> data.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte<replaceable>n</replaceable></term>
+ <listitem>
+ <para>
+ Data that forms part of a <command>COPY</command> data stream. Messages sent
+ from the backend will always correspond to single data rows,
+ but messages sent by frontends might divide the data stream
+ arbitrarily.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-CopyDone">
+ <term>CopyDone (F & B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('c')</term>
+ <listitem>
+ <para>
+ Identifies the message as a <command>COPY</command>-complete indicator.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(4)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-CopyFail">
+ <term>CopyFail (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('f')</term>
+ <listitem>
+ <para>
+ Identifies the message as a <command>COPY</command>-failure indicator.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ An error message to report as the cause of failure.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-CopyInResponse">
+ <term>CopyInResponse (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('G')</term>
+ <listitem>
+ <para>
+ Identifies the message as a Start Copy In response.
+ The frontend must now send copy-in data (if not
+ prepared to do so, send a CopyFail message).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int8</term>
+ <listitem>
+ <para>
+ 0 indicates the overall <command>COPY</command> format is textual (rows
+ separated by newlines, columns separated by separator
+ characters, etc).
+ 1 indicates the overall copy format is binary (similar
+ to DataRow format).
+ See <xref linkend="sql-copy"/>
+ for more information.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16</term>
+ <listitem>
+ <para>
+ The number of columns in the data to be copied
+ (denoted <replaceable>N</replaceable> below).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16[<replaceable>N</replaceable>]</term>
+ <listitem>
+ <para>
+ The format codes to be used for each column.
+ Each must presently be zero (text) or one (binary).
+ All must be zero if the overall copy format is textual.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-CopyOutResponse">
+ <term>CopyOutResponse (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('H')</term>
+ <listitem>
+ <para>
+ Identifies the message as a Start Copy Out response.
+ This message will be followed by copy-out data.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int8</term>
+ <listitem>
+ <para>
+ 0 indicates the overall <command>COPY</command> format
+ is textual (rows separated by newlines, columns
+ separated by separator characters, etc). 1 indicates
+ the overall copy format is binary (similar to DataRow
+ format). See <xref linkend="sql-copy"/> for more information.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16</term>
+ <listitem>
+ <para>
+ The number of columns in the data to be copied
+ (denoted <replaceable>N</replaceable> below).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16[<replaceable>N</replaceable>]</term>
+ <listitem>
+ <para>
+ The format codes to be used for each column.
+ Each must presently be zero (text) or one (binary).
+ All must be zero if the overall copy format is textual.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-CopyBothResponse">
+ <term>CopyBothResponse (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('W')</term>
+ <listitem>
+ <para>
+ Identifies the message as a Start Copy Both response.
+ This message is used only for Streaming Replication.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int8</term>
+ <listitem>
+ <para>
+ 0 indicates the overall <command>COPY</command> format
+ is textual (rows separated by newlines, columns
+ separated by separator characters, etc). 1 indicates
+ the overall copy format is binary (similar to DataRow
+ format). See <xref linkend="sql-copy"/> for more information.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16</term>
+ <listitem>
+ <para>
+ The number of columns in the data to be copied
+ (denoted <replaceable>N</replaceable> below).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16[<replaceable>N</replaceable>]</term>
+ <listitem>
+ <para>
+ The format codes to be used for each column.
+ Each must presently be zero (text) or one (binary).
+ All must be zero if the overall copy format is textual.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-DataRow">
+ <term>DataRow (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('D')</term>
+ <listitem>
+ <para>
+ Identifies the message as a data row.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16</term>
+ <listitem>
+ <para>
+ The number of column values that follow (possibly zero).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Next, the following pair of fields appear for each column:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ The length of the column value, in bytes (this count
+ does not include itself). Can be zero.
+ As a special case, -1 indicates a NULL column value.
+ No value bytes follow in the NULL case.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte<replaceable>n</replaceable></term>
+ <listitem>
+ <para>
+ The value of the column, in the format indicated by the
+ associated format code.
+ <replaceable>n</replaceable> is the above length.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-Describe">
+ <term>Describe (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('D')</term>
+ <listitem>
+ <para>
+ Identifies the message as a Describe command.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte1</term>
+ <listitem>
+ <para>
+ '<literal>S</literal>' to describe a prepared statement; or
+ '<literal>P</literal>' to describe a portal.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The name of the prepared statement or portal to describe
+ (an empty string selects the unnamed prepared statement
+ or portal).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-EmptyQueryResponse">
+ <term>EmptyQueryResponse (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('I')</term>
+ <listitem>
+ <para>
+ Identifies the message as a response to an empty query string.
+ (This substitutes for CommandComplete.)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(4)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-ErrorResponse">
+ <term>ErrorResponse (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('E')</term>
+ <listitem>
+ <para>
+ Identifies the message as an error.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The message body consists of one or more identified fields,
+ followed by a zero byte as a terminator. Fields can appear in
+ any order. For each field there is the following:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Byte1</term>
+ <listitem>
+ <para>
+ A code identifying the field type; if zero, this is
+ the message terminator and no string follows.
+ The presently defined field types are listed in
+ <xref linkend="protocol-error-fields"/>.
+ Since more field types might be added in future,
+ frontends should silently ignore fields of unrecognized
+ type.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The field value.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-Execute">
+ <term>Execute (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('E')</term>
+ <listitem>
+ <para>
+ Identifies the message as an Execute command.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The name of the portal to execute
+ (an empty string selects the unnamed portal).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Maximum number of rows to return, if portal contains
+ a query that returns rows (ignored otherwise). Zero
+ denotes <quote>no limit</quote>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-Flush">
+ <term>Flush (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('H')</term>
+ <listitem>
+ <para>
+ Identifies the message as a Flush command.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(4)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-FunctionCall">
+ <term>FunctionCall (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('F')</term>
+ <listitem>
+ <para>
+ Identifies the message as a function call.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Specifies the object ID of the function to call.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16</term>
+ <listitem>
+ <para>
+ The number of argument format codes that follow
+ (denoted <replaceable>C</replaceable> below).
+ This can be zero to indicate that there are no arguments
+ or that the arguments all use the default format (text);
+ or one, in which case the specified format code is applied
+ to all arguments; or it can equal the actual number of
+ arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16[<replaceable>C</replaceable>]</term>
+ <listitem>
+ <para>
+ The argument format codes. Each must presently be
+ zero (text) or one (binary).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16</term>
+ <listitem>
+ <para>
+ Specifies the number of arguments being supplied to the
+ function.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Next, the following pair of fields appear for each argument:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ The length of the argument value, in bytes (this count
+ does not include itself). Can be zero.
+ As a special case, -1 indicates a NULL argument value.
+ No value bytes follow in the NULL case.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte<replaceable>n</replaceable></term>
+ <listitem>
+ <para>
+ The value of the argument, in the format indicated by the
+ associated format code.
+ <replaceable>n</replaceable> is the above length.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ After the last argument, the following field appears:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Int16</term>
+ <listitem>
+ <para>
+ The format code for the function result. Must presently be
+ zero (text) or one (binary).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-FunctionCallResponse">
+ <term>FunctionCallResponse (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('V')</term>
+ <listitem>
+ <para>
+ Identifies the message as a function call result.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ The length of the function result value, in bytes (this count
+ does not include itself). Can be zero.
+ As a special case, -1 indicates a NULL function result.
+ No value bytes follow in the NULL case.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte<replaceable>n</replaceable></term>
+ <listitem>
+ <para>
+ The value of the function result, in the format indicated by
+ the associated format code.
+ <replaceable>n</replaceable> is the above length.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-GSSENCRequest">
+ <term>GSSENCRequest (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Int32(8)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(80877104)</term>
+ <listitem>
+ <para>
+ The <acronym>GSSAPI</acronym> Encryption request code. The value is chosen to contain
+ <literal>1234</literal> in the most significant 16 bits, and <literal>5680</literal> in the
+ least significant 16 bits. (To avoid confusion, this code
+ must not be the same as any protocol version number.)
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-GSSResponse">
+ <term>GSSResponse (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('p')</term>
+ <listitem>
+ <para>
+ Identifies the message as a GSSAPI or SSPI response. Note that
+ this is also used for SASL and password response messages.
+ The exact message type can be deduced from the context.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte<replaceable>n</replaceable></term>
+ <listitem>
+ <para>
+ GSSAPI/SSPI specific message data.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-NegotiateProtocolVersion">
+ <term>NegotiateProtocolVersion (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('v')</term>
+ <listitem>
+ <para>
+ Identifies the message as a protocol version negotiation
+ message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Newest minor protocol version supported by the server
+ for the major protocol version requested by the client.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Number of protocol options not recognized by the server.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Then, for protocol option not recognized by the server, there
+ is the following:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The option name.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-NoData">
+ <term>NoData (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('n')</term>
+ <listitem>
+ <para>
+ Identifies the message as a no-data indicator.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(4)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-NoticeResponse">
+ <term>NoticeResponse (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('N')</term>
+ <listitem>
+ <para>
+ Identifies the message as a notice.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The message body consists of one or more identified fields,
+ followed by a zero byte as a terminator. Fields can appear in
+ any order. For each field there is the following:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Byte1</term>
+ <listitem>
+ <para>
+ A code identifying the field type; if zero, this is
+ the message terminator and no string follows.
+ The presently defined field types are listed in
+ <xref linkend="protocol-error-fields"/>.
+ Since more field types might be added in future,
+ frontends should silently ignore fields of unrecognized
+ type.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The field value.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-NotificationResponse">
+ <term>NotificationResponse (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('A')</term>
+ <listitem>
+ <para>
+ Identifies the message as a notification response.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ The process ID of the notifying backend process.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The name of the channel that the notify has been raised on.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The <quote>payload</quote> string passed from the notifying process.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-ParameterDescription">
+ <term>ParameterDescription (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('t')</term>
+ <listitem>
+ <para>
+ Identifies the message as a parameter description.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16</term>
+ <listitem>
+ <para>
+ The number of parameters used by the statement
+ (can be zero).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Then, for each parameter, there is the following:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Specifies the object ID of the parameter data type.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-ParameterStatus">
+ <term>ParameterStatus (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('S')</term>
+ <listitem>
+ <para>
+ Identifies the message as a run-time parameter status report.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The name of the run-time parameter being reported.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The current value of the parameter.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-Parse">
+ <term>Parse (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('P')</term>
+ <listitem>
+ <para>
+ Identifies the message as a Parse command.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The name of the destination prepared statement
+ (an empty string selects the unnamed prepared statement).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The query string to be parsed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16</term>
+ <listitem>
+ <para>
+ The number of parameter data types specified
+ (can be zero). Note that this is not an indication of
+ the number of parameters that might appear in the
+ query string, only the number that the frontend wants to
+ prespecify types for.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Then, for each parameter, there is the following:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Specifies the object ID of the parameter data type.
+ Placing a zero here is equivalent to leaving the type
+ unspecified.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-ParseComplete">
+ <term>ParseComplete (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('1')</term>
+ <listitem>
+ <para>
+ Identifies the message as a Parse-complete indicator.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(4)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-PasswordMessage">
+ <term>PasswordMessage (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('p')</term>
+ <listitem>
+ <para>
+ Identifies the message as a password response. Note that
+ this is also used for GSSAPI, SSPI and SASL response messages.
+ The exact message type can be deduced from the context.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The password (encrypted, if requested).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-PortalSuspended">
+ <term>PortalSuspended (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('s')</term>
+ <listitem>
+ <para>
+ Identifies the message as a portal-suspended indicator.
+ Note this only appears if an Execute message's row-count limit
+ was reached.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(4)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-Query">
+ <term>Query (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('Q')</term>
+ <listitem>
+ <para>
+ Identifies the message as a simple query.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The query string itself.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-ReadyForQuery">
+ <term>ReadyForQuery (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('Z')</term>
+ <listitem>
+ <para>
+ Identifies the message type. ReadyForQuery is sent
+ whenever the backend is ready for a new query cycle.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(5)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte1</term>
+ <listitem>
+ <para>
+ Current backend transaction status indicator.
+ Possible values are '<literal>I</literal>' if idle (not in
+ a transaction block); '<literal>T</literal>' if in a transaction
+ block; or '<literal>E</literal>' if in a failed transaction
+ block (queries will be rejected until block is ended).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-RowDescription">
+ <term>RowDescription (B)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('T')</term>
+ <listitem>
+ <para>
+ Identifies the message as a row description.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16</term>
+ <listitem>
+ <para>
+ Specifies the number of fields in a row (can be zero).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Then, for each field, there is the following:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The field name.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ If the field can be identified as a column of a specific
+ table, the object ID of the table; otherwise zero.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16</term>
+ <listitem>
+ <para>
+ If the field can be identified as a column of a specific
+ table, the attribute number of the column; otherwise zero.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ The object ID of the field's data type.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16</term>
+ <listitem>
+ <para>
+ The data type size (see <varname>pg_type.typlen</varname>).
+ Note that negative values denote variable-width types.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ The type modifier (see <varname>pg_attribute.atttypmod</varname>).
+ The meaning of the modifier is type-specific.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16</term>
+ <listitem>
+ <para>
+ The format code being used for the field. Currently will
+ be zero (text) or one (binary). In a RowDescription
+ returned from the statement variant of Describe, the
+ format code is not yet known and will always be zero.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-SASLInitialResponse">
+ <term>SASLInitialResponse (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('p')</term>
+ <listitem>
+ <para>
+ Identifies the message as an initial SASL response. Note that
+ this is also used for GSSAPI, SSPI and password response messages.
+ The exact message type is deduced from the context.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ Name of the SASL authentication mechanism that the client
+ selected.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of SASL mechanism specific "Initial Client Response" that
+ follows, or -1 if there is no Initial Response.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte<replaceable>n</replaceable></term>
+ <listitem>
+ <para>
+ SASL mechanism specific "Initial Response".
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-SASLResponse">
+ <term>SASLResponse (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('p')</term>
+ <listitem>
+ <para>
+ Identifies the message as a SASL response. Note that
+ this is also used for GSSAPI, SSPI and password response messages.
+ The exact message type can be deduced from the context.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte<replaceable>n</replaceable></term>
+ <listitem>
+ <para>
+ SASL mechanism specific message data.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-SSLRequest">
+ <term>SSLRequest (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Int32(8)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(80877103)</term>
+ <listitem>
+ <para>
+ The <acronym>SSL</acronym> request code. The value is chosen to contain
+ <literal>1234</literal> in the most significant 16 bits, and <literal>5679</literal> in the
+ least significant 16 bits. (To avoid confusion, this code
+ must not be the same as any protocol version number.)
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-StartupMessage">
+ <term>StartupMessage (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(196608)</term>
+ <listitem>
+ <para>
+ The protocol version number. The most significant 16 bits are
+ the major version number (3 for the protocol described here).
+ The least significant 16 bits are the minor version number
+ (0 for the protocol described here).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The protocol version number is followed by one or more pairs of
+ parameter name and value strings. A zero byte is required as a
+ terminator after the last name/value pair.
+ Parameters can appear in any
+ order. <literal>user</literal> is required, others are optional.
+ Each parameter is specified as:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The parameter name. Currently recognized names are:
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>user</literal></term>
+ <listitem>
+ <para>
+ The database user name to connect as. Required;
+ there is no default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>database</literal></term>
+ <listitem>
+ <para>
+ The database to connect to. Defaults to the user name.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>options</literal></term>
+ <listitem>
+ <para>
+ Command-line arguments for the backend. (This is
+ deprecated in favor of setting individual run-time
+ parameters.) Spaces within this string are
+ considered to separate arguments, unless escaped with
+ a backslash (<literal>\</literal>); write <literal>\\</literal> to
+ represent a literal backslash.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>replication</literal></term>
+ <listitem>
+ <para>
+ Used to connect in streaming replication mode, where
+ a small set of replication commands can be issued
+ instead of SQL statements. Value can be
+ <literal>true</literal>, <literal>false</literal>, or
+ <literal>database</literal>, and the default is
+ <literal>false</literal>. See
+ <xref linkend="protocol-replication"/> for details.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ In addition to the above, other parameters may be listed.
+ Parameter names beginning with <literal>_pq_.</literal> are
+ reserved for use as protocol extensions, while others are
+ treated as run-time parameters to be set at backend start
+ time. Such settings will be applied during backend start
+ (after parsing the command-line arguments if any) and will
+ act as session defaults.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The parameter value.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-Sync">
+ <term>Sync (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('S')</term>
+ <listitem>
+ <para>
+ Identifies the message as a Sync command.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(4)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-message-formats-Terminate">
+ <term>Terminate (F)</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('X')</term>
+ <listitem>
+ <para>
+ Identifies the message as a termination.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32(4)</term>
+ <listitem>
+ <para>
+ Length of message contents in bytes, including self.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+
+ <sect1 id="protocol-error-fields">
+ <title>Error and Notice Message Fields</title>
+
+ <para>
+ This section describes the fields that can appear in ErrorResponse and
+ NoticeResponse messages. Each field type has a single-byte identification
+ token. Note that any given field type should appear at most once per
+ message.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>S</literal></term>
+ <listitem>
+ <para>
+ Severity: the field contents are
+ <literal>ERROR</literal>, <literal>FATAL</literal>, or
+ <literal>PANIC</literal> (in an error message), or
+ <literal>WARNING</literal>, <literal>NOTICE</literal>, <literal>DEBUG</literal>,
+ <literal>INFO</literal>, or <literal>LOG</literal> (in a notice message),
+ or a localized translation of one of these. Always present.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>V</literal></term>
+ <listitem>
+ <para>
+ Severity: the field contents are
+ <literal>ERROR</literal>, <literal>FATAL</literal>, or
+ <literal>PANIC</literal> (in an error message), or
+ <literal>WARNING</literal>, <literal>NOTICE</literal>, <literal>DEBUG</literal>,
+ <literal>INFO</literal>, or <literal>LOG</literal> (in a notice message).
+ This is identical to the <literal>S</literal> field except
+ that the contents are never localized. This is present only in
+ messages generated by <productname>PostgreSQL</productname> versions 9.6
+ and later.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>C</literal></term>
+ <listitem>
+ <para>
+ Code: the SQLSTATE code for the error (see <xref
+ linkend="errcodes-appendix"/>). Not localizable. Always present.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>M</literal></term>
+ <listitem>
+ <para>
+ Message: the primary human-readable error message.
+ This should be accurate but terse (typically one line).
+ Always present.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>D</literal></term>
+ <listitem>
+ <para>
+ Detail: an optional secondary error message carrying more
+ detail about the problem. Might run to multiple lines.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>H</literal></term>
+ <listitem>
+ <para>
+ Hint: an optional suggestion what to do about the problem.
+ This is intended to differ from Detail in that it offers advice
+ (potentially inappropriate) rather than hard facts.
+ Might run to multiple lines.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>P</literal></term>
+ <listitem>
+ <para>
+ Position: the field value is a decimal ASCII integer, indicating
+ an error cursor position as an index into the original query string.
+ The first character has index 1, and positions are measured in
+ characters not bytes.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>p</literal></term>
+ <listitem>
+ <para>
+ Internal position: this is defined the same as the <literal>P</literal>
+ field, but it is used when the cursor position refers to an internally
+ generated command rather than the one submitted by the client.
+ The <literal>q</literal> field will always appear when this field appears.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>q</literal></term>
+ <listitem>
+ <para>
+ Internal query: the text of a failed internally-generated command.
+ This could be, for example, an SQL query issued by a PL/pgSQL function.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>W</literal></term>
+ <listitem>
+ <para>
+ Where: an indication of the context in which the error occurred.
+ Presently this includes a call stack traceback of active
+ procedural language functions and internally-generated queries.
+ The trace is one entry per line, most recent first.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>s</literal></term>
+ <listitem>
+ <para>
+ Schema name: if the error was associated with a specific database
+ object, the name of the schema containing that object, if any.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>t</literal></term>
+ <listitem>
+ <para>
+ Table name: if the error was associated with a specific table, the
+ name of the table. (Refer to the schema name field for the name of
+ the table's schema.)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>c</literal></term>
+ <listitem>
+ <para>
+ Column name: if the error was associated with a specific table column,
+ the name of the column. (Refer to the schema and table name fields to
+ identify the table.)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>d</literal></term>
+ <listitem>
+ <para>
+ Data type name: if the error was associated with a specific data type,
+ the name of the data type. (Refer to the schema name field for the
+ name of the data type's schema.)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>n</literal></term>
+ <listitem>
+ <para>
+ Constraint name: if the error was associated with a specific
+ constraint, the name of the constraint. Refer to fields listed above
+ for the associated table or domain. (For this purpose, indexes are
+ treated as constraints, even if they weren't created with constraint
+ syntax.)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>F</literal></term>
+ <listitem>
+ <para>
+ File: the file name of the source-code location where the error
+ was reported.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>L</literal></term>
+ <listitem>
+ <para>
+ Line: the line number of the source-code location where the error
+ was reported.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>R</literal></term>
+ <listitem>
+ <para>
+ Routine: the name of the source-code routine reporting the error.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <note>
+ <para>
+ The fields for schema name, table name, column name, data type name, and
+ constraint name are supplied only for a limited number of error types;
+ see <xref linkend="errcodes-appendix"/>. Frontends should not assume that
+ the presence of any of these fields guarantees the presence of another
+ field. Core error sources observe the interrelationships noted above, but
+ user-defined functions may use these fields in other ways. In the same
+ vein, clients should not assume that these fields denote contemporary
+ objects in the current database.
+ </para>
+ </note>
+
+ <para>
+ The client is responsible for formatting displayed information to meet its
+ needs; in particular it should break long lines as needed. Newline characters
+ appearing in the error message fields should be treated as paragraph breaks,
+ not line breaks.
+ </para>
+ </sect1>
+
+ <sect1 id="protocol-logicalrep-message-formats">
+ <title>Logical Replication Message Formats</title>
+
+ <para>
+ This section describes the detailed format of each logical replication
+ message. These messages are either returned by the replication slot SQL
+ interface or are sent by a walsender. In the case of a walsender, they are
+ encapsulated inside replication protocol WAL messages as described in
+ <xref linkend="protocol-replication"/>, and generally obey the same message
+ flow as physical replication.
+ </para>
+
+ <variablelist>
+ <varlistentry id="protocol-logicalrep-message-formats-Begin">
+ <term>Begin</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('B')</term>
+ <listitem>
+ <para>
+ Identifies the message as a begin message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64 (XLogRecPtr)</term>
+ <listitem>
+ <para>
+ The final LSN of the transaction.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64 (TimestampTz)</term>
+ <listitem>
+ <para>
+ Commit timestamp of the transaction. The value is in number
+ of microseconds since PostgreSQL epoch (2000-01-01).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32 (TransactionId)</term>
+ <listitem>
+ <para>
+ Xid of the transaction.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-logicalrep-message-formats-Message">
+ <term>Message</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('M')</term>
+ <listitem>
+ <para>
+ Identifies the message as a logical decoding message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32 (TransactionId)</term>
+ <listitem>
+ <para>
+ Xid of the transaction (only present for streamed transactions).
+ This field is available since protocol version 2.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int8</term>
+ <listitem>
+ <para>
+ Flags; Either 0 for no flags or 1 if the logical decoding
+ message is transactional.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64 (XLogRecPtr)</term>
+ <listitem>
+ <para>
+ The LSN of the logical decoding message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The prefix of the logical decoding message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of the content.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte<replaceable>n</replaceable></term>
+ <listitem>
+ <para>
+ The content of the logical decoding message.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-logicalrep-message-formats-Commit">
+ <term>Commit</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('C')</term>
+ <listitem>
+ <para>
+ Identifies the message as a commit message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int8(0)</term>
+ <listitem>
+ <para>
+ Flags; currently unused.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64 (XLogRecPtr)</term>
+ <listitem>
+ <para>
+ The LSN of the commit.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64 (XLogRecPtr)</term>
+ <listitem>
+ <para>
+ The end LSN of the transaction.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64 (TimestampTz)</term>
+ <listitem>
+ <para>
+ Commit timestamp of the transaction. The value is in number
+ of microseconds since PostgreSQL epoch (2000-01-01).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-logicalrep-message-formats-Origin">
+ <term>Origin</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('O')</term>
+ <listitem>
+ <para>
+ Identifies the message as an origin message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64 (XLogRecPtr)</term>
+ <listitem>
+ <para>
+ The LSN of the commit on the origin server.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ Name of the origin.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Note that there can be multiple Origin messages inside a single transaction.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-logicalrep-message-formats-Relation">
+ <term>Relation</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('R')</term>
+ <listitem>
+ <para>
+ Identifies the message as a relation message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32 (TransactionId)</term>
+ <listitem>
+ <para>
+ Xid of the transaction (only present for streamed transactions).
+ This field is available since protocol version 2.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32 (Oid)</term>
+ <listitem>
+ <para>
+ OID of the relation.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ Namespace (empty string for <literal>pg_catalog</literal>).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ Relation name.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int8</term>
+ <listitem>
+ <para>
+ Replica identity setting for the relation (same as
+ <structfield>relreplident</structfield> in <structname>pg_class</structname>).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int16</term>
+ <listitem>
+ <para>
+ Number of columns.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Next, the following message part appears for each column included in
+ the publication (except generated columns):
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Int8</term>
+ <listitem>
+ <para>
+ Flags for the column. Currently can be either 0 for no flags
+ or 1 which marks the column as part of the key.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ Name of the column.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32 (Oid)</term>
+ <listitem>
+ <para>
+ OID of the column's data type.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Type modifier of the column (<structfield>atttypmod</structfield>).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-logicalrep-message-formats-Type">
+ <term>Type</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('Y')</term>
+ <listitem>
+ <para>
+ Identifies the message as a type message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32 (TransactionId)</term>
+ <listitem>
+ <para>
+ Xid of the transaction (only present for streamed transactions).
+ This field is available since protocol version 2.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32 (Oid)</term>
+ <listitem>
+ <para>
+ OID of the data type.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ Namespace (empty string for <literal>pg_catalog</literal>).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ Name of the data type.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-logicalrep-message-formats-Insert">
+ <term>Insert</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('I')</term>
+ <listitem>
+ <para>
+ Identifies the message as an insert message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32 (TransactionId)</term>
+ <listitem>
+ <para>
+ Xid of the transaction (only present for streamed transactions).
+ This field is available since protocol version 2.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32 (Oid)</term>
+ <listitem>
+ <para>
+ OID of the relation corresponding to the ID in the relation
+ message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte1('N')</term>
+ <listitem>
+ <para>
+ Identifies the following TupleData message as a new tuple.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>TupleData</term>
+ <listitem>
+ <para>
+ TupleData message part representing the contents of new tuple.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-logicalrep-message-formats-Update">
+ <term>Update</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('U')</term>
+ <listitem>
+ <para>
+ Identifies the message as an update message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32 (TransactionId)</term>
+ <listitem>
+ <para>
+ Xid of the transaction (only present for streamed transactions).
+ This field is available since protocol version 2.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32 (Oid)</term>
+ <listitem>
+ <para>
+ OID of the relation corresponding to the ID in the relation
+ message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte1('K')</term>
+ <listitem>
+ <para>
+ Identifies the following TupleData submessage as a key.
+ This field is optional and is only present if
+ the update changed data in any of the column(s) that are
+ part of the REPLICA IDENTITY index.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte1('O')</term>
+ <listitem>
+ <para>
+ Identifies the following TupleData submessage as an old tuple.
+ This field is optional and is only present if table in which
+ the update happened has REPLICA IDENTITY set to FULL.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>TupleData</term>
+ <listitem>
+ <para>
+ TupleData message part representing the contents of the old tuple
+ or primary key. Only present if the previous 'O' or 'K' part
+ is present.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte1('N')</term>
+ <listitem>
+ <para>
+ Identifies the following TupleData message as a new tuple.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>TupleData</term>
+ <listitem>
+ <para>
+ TupleData message part representing the contents of a new tuple.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The Update message may contain either a 'K' message part or an 'O' message part
+ or neither of them, but never both of them.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-logicalrep-message-formats-Delete">
+ <term>Delete</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('D')</term>
+ <listitem>
+ <para>
+ Identifies the message as a delete message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32 (TransactionId)</term>
+ <listitem>
+ <para>
+ Xid of the transaction (only present for streamed transactions).
+ This field is available since protocol version 2.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32 (Oid)</term>
+ <listitem>
+ <para>
+ OID of the relation corresponding to the ID in the relation
+ message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte1('K')</term>
+ <listitem>
+ <para>
+ Identifies the following TupleData submessage as a key.
+ This field is present if the table in which the delete has
+ happened uses an index as REPLICA IDENTITY.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Byte1('O')</term>
+ <listitem>
+ <para>
+ Identifies the following TupleData message as an old tuple.
+ This field is present if the table in which the delete
+ happened has REPLICA IDENTITY set to FULL.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>TupleData</term>
+ <listitem>
+ <para>
+ TupleData message part representing the contents of the old tuple
+ or primary key, depending on the previous field.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The Delete message may contain either a 'K' message part or an 'O' message part,
+ but never both of them.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-logicalrep-message-formats-Truncate">
+ <term>Truncate</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('T')</term>
+ <listitem>
+ <para>
+ Identifies the message as a truncate message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32 (TransactionId)</term>
+ <listitem>
+ <para>
+ Xid of the transaction (only present for streamed transactions).
+ This field is available since protocol version 2.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Number of relations
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int8</term>
+ <listitem>
+ <para>
+ Option bits for <command>TRUNCATE</command>:
+ 1 for <literal>CASCADE</literal>, 2 for <literal>RESTART IDENTITY</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32 (Oid)</term>
+ <listitem>
+ <para>
+ OID of the relation corresponding to the ID in the relation
+ message. This field is repeated for each relation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The following messages (Stream Start, Stream Stop, Stream Commit, and
+ Stream Abort) are available since protocol version 2.
+ </para>
+
+ <variablelist>
+ <varlistentry id="protocol-logicalrep-message-formats-Stream-Start">
+ <term>Stream Start</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('S')</term>
+ <listitem>
+ <para>
+ Identifies the message as a stream start message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int32 (TransactionId)</term>
+ <listitem>
+ <para>
+ Xid of the transaction.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int8</term>
+ <listitem>
+ <para>
+ A value of 1 indicates this is the first stream segment for
+ this XID, 0 for any other stream segment.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-logicalrep-message-formats-Stream-Stop">
+ <term>Stream Stop</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('E')</term>
+ <listitem>
+ <para>
+ Identifies the message as a stream stop message.
+ </para>
+ </listitem>
</varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="protocol-logicalrep-message-formats-Stream-Commit">
+ <term>Stream Commit</term>
+ <listitem>
+ <variablelist>
<varlistentry>
- <term>
- Int64
- </term>
- <listitem>
- <para>
- The server's system clock at the time of transmission, as
- microseconds since midnight on 2000-01-01.
- </para>
- </listitem>
+ <term>Byte1('c')</term>
+ <listitem>
+ <para>
+ Identifies the message as a stream commit message.
+ </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>
+ <term>Int32 (TransactionId)</term>
+ <listitem>
+ <para>
+ Xid of the transaction.
+ </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>
+ <term>Int8(0)</term>
+ <listitem>
+ <para>
+ Flags; currently unused.
+ </para>
+ </listitem>
</varlistentry>
+
<varlistentry>
- <term>
- Int64
- </term>
- <listitem>
- <para>
- The current end of WAL on the server.
- </para>
- </listitem>
+ <term>Int64 (XLogRecPtr)</term>
+ <listitem>
+ <para>
+ The LSN of the commit.
+ </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>
+ <term>Int64 (XLogRecPtr)</term>
+ <listitem>
+ <para>
+ The end LSN of the transaction.
+ </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>
+ <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>
-
- <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>
+ </listitem>
+ </varlistentry>
- <para>
- <variablelist>
- <varlistentry id="protocol-replication-standby-status-update">
- <term>
- Standby status update (F)
- </term>
- <listitem>
- <para>
- <variablelist>
+ <varlistentry id="protocol-logicalrep-message-formats-Stream-Abort">
+ <term>Stream Abort</term>
+ <listitem>
+ <variablelist>
<varlistentry>
- <term>
- Byte1('r')
- </term>
- <listitem>
- <para>
- Identifies the message as a receiver status update.
- </para>
- </listitem>
+ <term>Byte1('A')</term>
+ <listitem>
+ <para>
+ Identifies the message as a stream abort message.
+ </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>
+ <term>Int32 (TransactionId)</term>
+ <listitem>
+ <para>
+ Xid of the transaction.
+ </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>
+ <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>
- Int64
- </term>
- <listitem>
- <para>
- The location of the last WAL byte + 1 applied in the standby.
- </para>
- </listitem>
+ <term>Byte1('b')</term>
+ <listitem>
+ <para>
+ Identifies the message as the beginning of a two-phase transaction 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>
+ <term>Int64 (XLogRecPtr)</term>
+ <listitem>
+ <para>
+ The LSN of the prepare.
+ </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>
+ <term>Int64 (XLogRecPtr)</term>
+ <listitem>
+ <para>
+ The end LSN of the prepared transaction.
+ </para>
+ </listitem>
</varlistentry>
- </variablelist>
- </para>
- <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>
+ <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
- </term>
- <listitem>
- <para>
- The client's system clock at the time of transmission, as
- microseconds since midnight on 2000-01-01.
- </para>
- </listitem>
+ <term>Int32 (TransactionId)</term>
+ <listitem>
+ <para>
+ Xid of the transaction.
+ </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>
+ <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>
- Int32
- </term>
- <listitem>
- <para>
- The epoch of the global xmin xid on the standby.
- </para>
- </listitem>
+ <term>Byte1('P')</term>
+ <listitem>
+ <para>
+ Identifies the message as a two-phase prepared transaction message.
+ </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>
+ <term>Int8(0)</term>
+ <listitem>
+ <para>
+ Flags; currently unused.
+ </para>
+ </listitem>
</varlistentry>
+
<varlistentry>
- <term>
- Int32
- </term>
- <listitem>
- <para>
- The epoch of the catalog_xmin xid on the standby.
- </para>
- </listitem>
+ <term>Int64 (XLogRecPtr)</term>
+ <listitem>
+ <para>
+ The LSN of the prepare.
+ </para>
+ </listitem>
</varlistentry>
- </variablelist>
- </para>
- </listitem>
+
+ <varlistentry>
+ <term>Int64 (XLogRecPtr)</term>
+ <listitem>
+ <para>
+ The end LSN of the prepared transaction.
+ </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>
+ <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>
- <para>
- The messages inside the CopyBothResponse messages are of the same format
- documented for <literal>START_REPLICATION ... PHYSICAL</literal>, including
- two CommandComplete messages.
- </para>
+ <varlistentry>
+ <term>Int32 (TransactionId)</term>
+ <listitem>
+ <para>
+ Xid of the transaction.
+ </para>
+ </listitem>
+ </varlistentry>
- <para>
- The output plugin associated with the selected slot is used
- to process the output for streaming.
- </para>
+ <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><literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable></term>
+ <term>Byte1('K')</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>
+ <para>
+ Identifies the message as the commit of a two-phase transaction message.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><replaceable class="parameter">XXX/XXX</replaceable></term>
+ <term>Int8(0)</term>
<listitem>
<para>
- The WAL location to begin streaming at.
+ Flags; currently unused.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><replaceable class="parameter">option_name</replaceable></term>
+ <term>Int64 (XLogRecPtr)</term>
<listitem>
<para>
- The name of an option passed to the slot's logical decoding plugin.
+ The LSN of the commit prepared.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
- <term><replaceable class="parameter">option_value</replaceable></term>
+ <term>Int64 (XLogRecPtr)</term>
<listitem>
<para>
- Optional value, in the form of a string constant, associated with the
- specified option.
+ The end LSN of the commit prepared transaction.
</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>
+ <term>Int64 (TimestampTz)</term>
<listitem>
- <para>
- The name of the slot to drop.
- </para>
+ <para>
+ Commit timestamp of the transaction. The value is in number
+ of microseconds since PostgreSQL epoch (2000-01-01).
+ </para>
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>WAIT</literal></term>
+ <term>Int32 (TransactionId)</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.
+ 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>
- <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>
+ <varlistentry id="protocol-logicalrep-message-formats-Rollback-Prepared">
+ <term>Rollback Prepared</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>.
+ <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>
- 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>
+ Flags; currently unused.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Int64 (XLogRecPtr)</term>
+ <listitem>
<para>
- The <literal>workers</literal> keyword sets the number of threads
- that should be used for parallel compression. Parallel compression
- is supported only for <literal>zstd</literal>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>MAX_RATE</literal> <replaceable>rate</replaceable></term>
- <listitem>
- <para>
- Limit (throttle) the maximum amount of data transferred from server
- to client per unit of time. The expected unit is kilobytes per second.
- If this option is specified, the value must either be equal to zero
- or it must fall within the range from 32 kB through 1 GB (inclusive).
- If zero is passed or the option is not specified, no restriction is
- imposed on the transfer.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>TABLESPACE_MAP [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
- <listitem>
- <para>
- If true, include information about symbolic links present in the
- directory <filename>pg_tblspc</filename> in a file named
- <filename>tablespace_map</filename>. The tablespace map file includes
- each symbolic link name as it exists in the directory
- <filename>pg_tblspc/</filename> and the full path of that symbolic link.
- The default is false.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>VERIFY_CHECKSUMS [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
- <listitem>
- <para>
- If true, checksums are verified during a base backup if they are
- enabled. If false, this is skipped. The default is true.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>MANIFEST</literal> <replaceable>manifest_option</replaceable></term>
- <listitem>
- <para>
- When this option is specified with a value of <literal>yes</literal>
- or <literal>force-encode</literal>, a backup manifest is created
- and sent along with the backup. The manifest is a list of every
- file present in the backup with the exception of any WAL files that
- may be included. It also stores the size, last modification time, and
- optionally a checksum for each file.
- A value of <literal>force-encode</literal> forces all filenames
- to be hex-encoded; otherwise, this type of encoding is performed only
- for files whose names are non-UTF8 octet sequences.
- <literal>force-encode</literal> is intended primarily for testing
- purposes, to be sure that clients which read the backup manifest
- can handle this case. For compatibility with previous releases,
- the default is <literal>MANIFEST 'no'</literal>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>MANIFEST_CHECKSUMS</literal> <replaceable>checksum_algorithm</replaceable></term>
- <listitem>
- <para>
- Specifies the checksum algorithm that should be applied to each file included
- in the backup manifest. Currently, the available
- algorithms are <literal>NONE</literal>, <literal>CRC32C</literal>,
- <literal>SHA224</literal>, <literal>SHA256</literal>,
- <literal>SHA384</literal>, and <literal>SHA512</literal>.
- The default is <literal>CRC32C</literal>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- <para>
- When the backup is started, the server will first send two
- ordinary result sets, followed by one or more CopyOutResponse
- results.
- </para>
- <para>
- The first ordinary result set contains the starting position of the
- backup, in a single row with two columns. The first column contains
- the start position given in XLogRecPtr format, and the second column
- contains the corresponding timeline ID.
- </para>
- <para>
- The second ordinary result set has one row for each tablespace.
- The fields in this row are:
- <variablelist>
- <varlistentry>
- <term><literal>spcoid</literal> (<type>oid</type>)</term>
- <listitem>
- <para>
- The OID of the tablespace, or null if it's the base
- directory.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>spclocation</literal> (<type>text</type>)</term>
- <listitem>
- <para>
- The full path of the tablespace directory, or null
- if it's the base directory.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>size</literal> (<type>int8</type>)</term>
- <listitem>
- <para>
- The approximate size of the tablespace, in kilobytes (1024 bytes),
- if progress report has been requested; otherwise it's null.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <para>
- After the second regular result set, a CopyOutResponse will be sent.
- The payload of each CopyData message will contain a message in one of
- the following formats:
- </para>
-
- <para>
- <variablelist>
+ The end LSN of the prepared transaction.
+ </para>
+ </listitem>
+ </varlistentry>
<varlistentry>
- <term>new archive (B)</term>
- <listitem><para><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>
- </varlistentry>
- <varlistentry>
- <term>String</term>
- <listitem><para>
- The file name for this archive.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>String</term>
- <listitem><para>
- For the main data directory, an empty string. For other
- tablespaces, the full path to the directory from which this
- archive was created.
- </para></listitem>
- </varlistentry>
- </variablelist></para></listitem>
+ <term>Int64 (XLogRecPtr)</term>
+ <listitem>
+ <para>
+ The end LSN of the rollback prepared transaction.
+ </para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term>manifest (B)</term>
- <listitem><para><variablelist>
- <varlistentry>
- <term>Byte1('m')</term>
- <listitem><para>
- Identifes the message as indicating the start of the backup
- manifest.
- </para></listitem>
- </varlistentry>
- </variablelist></para></listitem>
+ <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>archive or manifest data (B)</term>
- <listitem><para><variablelist>
- <varlistentry>
- <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>
- </varlistentry>
- </variablelist></para></listitem>
+ <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>progress report (B)</term>
- <listitem><para><variablelist>
- <varlistentry>
- <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>
- </varlistentry>
- </variablelist></para></listitem>
+ <term>Int32 (TransactionId)</term>
+ <listitem>
+ <para>
+ Xid of the transaction.
+ </para>
+ </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>
+ <varlistentry>
+ <term>String</term>
+ <listitem>
+ <para>
+ The user defined GID of the two-phase transaction.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
- <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">
+ <varlistentry id="protocol-logicalrep-message-formats-Stream-Prepare">
+ <term>Stream Prepare</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term>Byte1('p')</term>
<listitem>
<para>
- <filename>postmaster.pid</filename>
+ Identifies the message as a two-phase stream prepare message.
</para>
</listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int8(0)</term>
<listitem>
<para>
- <filename>postmaster.opts</filename>
+ Flags; currently unused.
</para>
</listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64 (XLogRecPtr)</term>
<listitem>
<para>
- <filename>pg_internal.init</filename> (found in multiple directories)
+ The LSN of the prepare.
</para>
</listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64 (XLogRecPtr)</term>
<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.
+ The end LSN of the prepare transaction.
</para>
</listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Int64 (TimestampTz)</term>
<listitem>
<para>
- Unlogged relations, except for the init fork which is required to
- recreate the (empty) unlogged relation on recovery.
+ 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>
- <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.
+ Xid of the transaction.
</para>
</listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>String</term>
<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).
+ 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>
- 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.)
+ Number of columns.
</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>
+ </varlistentry>
+ </variablelist>
-</sect1>
+ <para>
+ Next, one of the following submessages appears for each column (except generated columns):
-<sect1 id="protocol-logical-replication">
- <title>Logical Streaming Replication Protocol</title>
+ <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>
- <para>
- This section describes the logical replication protocol, which is the message
- flow started by the <literal>START_REPLICATION</literal>
- <literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable>
- <literal>LOGICAL</literal> replication command.
- </para>
+ <varlistentry>
+ <term>Int32</term>
+ <listitem>
+ <para>
+ Length of the column value.
+ </para>
+ </listitem>
+ </varlistentry>
- <para>
- The logical streaming replication protocol builds on the primitives of
- the physical streaming replication protocol.
- </para>
+ <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>
- <sect2 id="protocol-logical-replication-params">
- <title>Logical Streaming Replication Parameters</title>
+ <sect1 id="protocol-changes">
+ <title>Summary of Changes since Protocol 2.0</title>
<para>
- The logical replication <literal>START_REPLICATION</literal> command
- accepts following parameters:
-
- <variablelist>
- <varlistentry>
- <term>
- proto_version
- </term>
- <listitem>
- <para>
- Protocol version. Currently versions <literal>1</literal>, <literal>2</literal>,
- and <literal>3</literal> are supported.
- </para>
- <para>
- Version <literal>2</literal> is supported only for server version 14
- and above, and it allows streaming of large in-progress transactions.
- </para>
- <para>
- Version <literal>3</literal> is supported only for server version 15
- and above, and it allows streaming of two-phase transactions.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- publication_names
- </term>
- <listitem>
- <para>
- Comma separated list of publication names for which to subscribe
- (receive changes). The individual publication names are treated
- as standard objects names and can be quoted the same as needed.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
+ This section provides a quick checklist of changes, for the benefit of
+ developers trying to update existing client libraries to protocol 3.0.
</para>
- </sect2>
-
- <sect2 id="protocol-logical-messages">
- <title>Logical Replication Protocol Messages</title>
<para>
- The individual protocol messages are discussed in the following
- subsections. Individual messages are described in
- <xref linkend="protocol-logicalrep-message-formats"/>.
+ 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 top-level protocol messages begin with a message type byte.
- While represented in code as a character, this is a signed byte with no
- associated encoding.
+ 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>
- Since the streaming replication protocol supplies a message length there
- is no need for top-level protocol messages to embed a length in their
- header.
+ 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>
- </sect2>
-
- <sect2 id="protocol-logical-messages-flow">
- <title>Logical Replication Protocol Message Flow</title>
-
<para>
- With the exception of the <literal>START_REPLICATION</literal> command and
- the replay progress messages, all information flows only from the backend
- to the frontend.
+ The ReadyForQuery ('<literal>Z</literal>') message includes a transaction status
+ indicator.
</para>
<para>
- The logical replication protocol sends individual transactions one by one.
- This means that all messages between a pair of Begin and Commit messages
- belong to the same transaction. Similarly, all messages between a pair of
- Begin Prepare and Prepare messages belong to the same transaction.
- It also sends changes of large in-progress transactions between a pair of
- Stream Start and Stream Stop messages. The last stream of such a transaction
- contains a Stream Commit or Stream Abort message.
+ 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>
- Every sent transaction contains zero or more DML messages (Insert,
- Update, Delete). In case of a cascaded setup it can also contain Origin
- messages. The origin message indicates that the transaction originated on
- different replication node. Since a replication node in the scope of logical
- replication protocol can be pretty much anything, the only identifier
- is the origin name. It's downstream's responsibility to handle this as
- needed (if needed). The Origin message is always sent before any DML
- messages in the transaction.
+ 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>
- Every DML message contains a relation OID, identifying the publisher's
- relation that was acted on. Before the first DML message for a given
- relation OID, a Relation message will be sent, describing the schema of
- that relation. Subsequently, a new Relation message will be sent if
- the relation's definition has changed since the last Relation message
- was sent for it. (The protocol assumes that the client is capable of
- remembering this metadata for as many relations as needed.)
+ <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>
- Relation messages identify column types by their OIDs. In the case
- of a built-in type, it is assumed that the client can look up that
- type OID locally, so no additional data is needed. For a non-built-in
- type OID, a Type message will be sent before the Relation message,
- to provide the type name associated with that OID. Thus, a client that
- needs to specifically identify the types of relation columns should
- cache the contents of Type messages, and first consult that cache to
- see if the type OID is defined there. If not, look up the type OID
- locally.
+ 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>
- </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-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>
- <para>
- The command tag. This is usually a single
- word that identifies which SQL command was completed.
- </para>
-
- <para>
- For an <command>INSERT</command> command, the tag is
- <literal>INSERT <replaceable>oid</replaceable>
- <replaceable>rows</replaceable></literal>, where
- <replaceable>rows</replaceable> is the number of rows
- inserted. <replaceable>oid</replaceable> used to be the object ID
- of the inserted row if <replaceable>rows</replaceable> was 1
- and the target table had OIDs, but OIDs system columns are
- not supported anymore; therefore <replaceable>oid</replaceable>
- is always 0.
- </para>
-
- <para>
- For a <command>DELETE</command> command, the tag is
- <literal>DELETE <replaceable>rows</replaceable></literal> where
- <replaceable>rows</replaceable> is the number of rows deleted.
- </para>
-
- <para>
- For an <command>UPDATE</command> command, the tag is
- <literal>UPDATE <replaceable>rows</replaceable></literal> where
- <replaceable>rows</replaceable> is the number of rows updated.
- </para>
-
- <para>
- For a <command>SELECT</command> or <command>CREATE TABLE AS</command>
- command, the tag is <literal>SELECT <replaceable>rows</replaceable></literal>
- where <replaceable>rows</replaceable> is the number of rows retrieved.
- </para>
-
- <para>
- For a <command>MOVE</command> command, the tag is
- <literal>MOVE <replaceable>rows</replaceable></literal> where
- <replaceable>rows</replaceable> is the number of rows the
- cursor's position has been changed by.
- </para>
-
- <para>
- For a <command>FETCH</command> command, the tag is
- <literal>FETCH <replaceable>rows</replaceable></literal> where
- <replaceable>rows</replaceable> is the number of rows that
- have been retrieved from the cursor.
- </para>
-
- <para>
- For a <command>COPY</command> command, the tag is
- <literal>COPY <replaceable>rows</replaceable></literal> where
- <replaceable>rows</replaceable> is the number of rows copied.
- (Note: the row count appears only in
- <productname>PostgreSQL</productname> 8.2 and later.)
- </para>
-
-</listitem>
-</varlistentry>
-</variablelist>
-
-</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>
-
-</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>
-<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>
+ <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>
-</sect1>
+ <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>
-<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>
+ <para>
+ The CursorResponse ('<literal>P</literal>') message is no longer generated by
+ the backend.
+ </para>
-</sect1>
+ <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>
projects / postgresql.git / commitdiff