This section describes the logical replication protocol, which is the message flow started by the START_REPLICATION SLOT slot_name LOGICAL replication command.
The logical streaming replication protocol builds on the primitives of the physical streaming replication protocol.
\nThe logical replication START_REPLICATION command accepts following parameters:
Protocol version. Currently only version 1 is supported.
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.
\nThe individual protocol messages are discussed in the following subsections. Individual messages are described in Section\u00a052.9.
\nAll 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.
\nSince the streaming replication protocol supplies a message length there is no need for top-level protocol messages to embed a length in their header.
\nWith the exception of the START_REPLICATION command and the replay progress messages, all information flows only from the backend to the frontend.
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.
\nEvery 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.
\nEvery 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.)
\nRelation 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.
\nThis section describes the logical replication protocol, which is the message flow started by the START_REPLICATION SLOT slot_name LOGICAL replication command.
The logical streaming replication protocol builds on the primitives of the physical streaming replication protocol.
\nThe logical replication START_REPLICATION command accepts following parameters:
Protocol version. Currently only version 1 is supported.
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.
\nThe individual protocol messages are discussed in the following subsections. Individual messages are described in Section\u00a053.9.
\nAll 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.
\nSince the streaming replication protocol supplies a message length there is no need for top-level protocol messages to embed a length in their header.
\nWith the exception of the START_REPLICATION command and the replay progress messages, all information flows only from the backend to the frontend.
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.
\nEvery 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.
\nEvery 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.)
\nRelation 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.
\nThis section describes the logical replication protocol, which is the message flow started by the START_REPLICATION SLOT slot_name LOGICAL replication command.
The logical streaming replication protocol builds on the primitives of the physical streaming replication protocol.
\nPostgreSQL logical decoding supports output plugins. pgoutput is the standard one used for the built-in logical replication.
Using the START_REPLICATION command, pgoutput accepts the following options:
Protocol version. Currently only version 1 is supported. A valid version is required.
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. At least one publication name is required.
\nThe individual protocol messages are discussed in the following subsections. Individual messages are described in Section\u00a052.9.
\nAll 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.
\nSince the streaming replication protocol supplies a message length there is no need for top-level protocol messages to embed a length in their header.
\nWith the exception of the START_REPLICATION command and the replay progress messages, all information flows only from the backend to the frontend.
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.
\nEvery 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.
\nEvery 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.)
\nRelation 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.
\nThis section describes the logical replication protocol, which is the message flow started by the START_REPLICATION SLOT slot_name LOGICAL replication command.
The logical streaming replication protocol builds on the primitives of the physical streaming replication protocol.
\nPostgreSQL logical decoding supports output plugins. pgoutput is the standard one used for the built-in logical replication.
Using the START_REPLICATION command, pgoutput accepts the following options:
Protocol version. Currently only version 1 is supported. A valid version is required.
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. At least one publication name is required.
\nThe individual protocol messages are discussed in the following subsections. Individual messages are described in Section\u00a052.9.
\nAll 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.
\nSince the streaming replication protocol supplies a message length there is no need for top-level protocol messages to embed a length in their header.
\nWith the exception of the START_REPLICATION command and the replay progress messages, all information flows only from the backend to the frontend.
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.
\nEvery 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.
\nEvery 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.)
\nRelation 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.
\nThis section describes the logical replication protocol, which is the message flow started by the START_REPLICATION SLOT slot_name LOGICAL replication command.
The logical streaming replication protocol builds on the primitives of the physical streaming replication protocol.
\nPostgreSQL logical decoding supports output plugins. pgoutput is the standard one used for the built-in logical replication.
Using the START_REPLICATION command, pgoutput accepts the following options:
Protocol version. Currently versions 1 and 2 are supported. A valid version is required. The version 2 is supported only for server version 14 and above, and it allows streaming of large in-progress transactions.
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. At least one publication name is required.
\nBoolean option to use binary transfer mode. Binary mode is faster than the text mode but slightly less robust.
\nBoolean option to enable sending the messages that are written by pg_logical_emit_message.
Boolean option to enable streaming of in-progress transactions. Minimum protocol version 2 is required to turn it on.
\nThe individual protocol messages are discussed in the following subsections. Individual messages are described in Section\u00a053.9.
\nAll 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.
\nSince the streaming replication protocol supplies a message length there is no need for top-level protocol messages to embed a length in their header.
\nWith the exception of the START_REPLICATION command and the replay progress messages, all information flows only from the backend to the frontend.
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. 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 Stream Commit or Stream Abort message.
\nEvery 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.
\nEvery 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.)
\nRelation 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.
\nThis section describes the logical replication protocol, which is the message flow started by the START_REPLICATION SLOT slot_name LOGICAL replication command.
The logical streaming replication protocol builds on the primitives of the physical streaming replication protocol.
\nPostgreSQL logical decoding supports output plugins. pgoutput is the standard one used for the built-in logical replication.
Using the START_REPLICATION command, pgoutput accepts the following options:
Protocol version. Currently versions 1, 2, and 3 are supported. A valid version is required.
Version 2 is supported only for server version 14 and above, and it allows streaming of large in-progress transactions.
Version 3 is supported only for server version 15 and above, and it allows streaming of two-phase commits.
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. At least one publication name is required.
\nBoolean option to use binary transfer mode. Binary mode is faster than the text mode but slightly less robust.
\nBoolean option to enable sending the messages that are written by pg_logical_emit_message.
Boolean option to enable streaming of in-progress transactions. Minimum protocol version 2 is required to turn it on.
\nBoolean option to enable two-phase transactions. Minimum protocol version 3 is required to turn it on.
\nThe individual protocol messages are discussed in the following subsections. Individual messages are described in Section\u00a055.9.
\nAll 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.
\nSince the streaming replication protocol supplies a message length there is no need for top-level protocol messages to embed a length in their header.
\nWith the exception of the START_REPLICATION command and the replay progress messages, all information flows only from the backend to the frontend.
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.
\nEvery 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.
\nEvery 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.)
\nRelation 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.
\nThis section describes the logical replication protocol, which is the message flow started by the START_REPLICATION SLOT slot_name LOGICAL replication command.
The logical streaming replication protocol builds on the primitives of the physical streaming replication protocol.
\nPostgreSQL logical decoding supports output plugins. pgoutput is the standard one used for the built-in logical replication.
Using the START_REPLICATION command, pgoutput accepts the following options:
Protocol version. Currently versions 1, 2, 3, and 4 are supported. A valid version is required.
Version 2 is supported only for server version 14 and above, and it allows streaming of large in-progress transactions.
Version 3 is supported only for server version 15 and above, and it allows streaming of two-phase commits.
Version 4 is supported only for server version 16 and above, and it allows streams of large in-progress transactions to be applied in parallel.
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. At least one publication name is required.
\nBoolean option to use binary transfer mode. Binary mode is faster than the text mode but slightly less robust.
\nBoolean option to enable sending the messages that are written by pg_logical_emit_message.
Option to enable streaming of in-progress transactions. Valid values are off (the default), on and parallel. The setting parallel enables sending extra information with some messages to be used for parallelization. Minimum protocol version 2 is required to turn it on. Minimum protocol version 4 is required for the parallel value.
Boolean option to enable two-phase transactions. Minimum protocol version 3 is required to turn it on.
\nOption to send changes by their origin. Possible values are \"none\" to only send the changes that have no origin associated, or \"any\" to send the changes regardless of their origin. This can be used to avoid loops (infinite replication of the same data) among replication nodes.
\nThe individual protocol messages are discussed in the following subsections. Individual messages are described in Section\u00a055.9.
\nAll 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.
\nSince the streaming replication protocol supplies a message length there is no need for top-level protocol messages to embed a length in their header.
\nWith the exception of the START_REPLICATION command and the replay progress messages, all information flows only from the backend to the frontend.
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.
\nEvery 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.
\nEvery 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.)
\nRelation 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.
\nThis section describes the logical replication protocol, which is the message flow started by the START_REPLICATION SLOT slot_name LOGICAL replication command.
The logical streaming replication protocol builds on the primitives of the physical streaming replication protocol.
\nPostgreSQL logical decoding supports output plugins. pgoutput is the standard one used for the built-in logical replication.
Using the START_REPLICATION command, pgoutput accepts the following options:
Protocol version. Currently versions 1, 2, 3, and 4 are supported. A valid version is required.
Version 2 is supported only for server version 14 and above, and it allows streaming of large in-progress transactions.
Version 3 is supported only for server version 15 and above, and it allows streaming of two-phase commits.
Version 4 is supported only for server version 16 and above, and it allows streams of large in-progress transactions to be applied in parallel.
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. At least one publication name is required.
\nBoolean option to use binary transfer mode. Binary mode is faster than the text mode but slightly less robust.
\nBoolean option to enable sending the messages that are written by pg_logical_emit_message.
Option to enable streaming of in-progress transactions. Valid values are off (the default), on and parallel. The setting parallel enables sending extra information with some messages to be used for parallelization. Minimum protocol version 2 is required to turn it on. Minimum protocol version 4 is required for the parallel value.
Boolean option to enable two-phase transactions. Minimum protocol version 3 is required to turn it on.
\nOption to send changes by their origin. Possible values are \"none\" to only send the changes that have no origin associated, or \"any\" to send the changes regardless of their origin. This can be used to avoid loops (infinite replication of the same data) among replication nodes.
\nThe individual protocol messages are discussed in the following subsections. Individual messages are described in Section\u00a053.9.
\nAll 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.
\nSince the streaming replication protocol supplies a message length there is no need for top-level protocol messages to embed a length in their header.
\nWith the exception of the START_REPLICATION command and the replay progress messages, all information flows only from the backend to the frontend.
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.
\nEvery 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.
\nEvery 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.)
\nRelation 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.
\nThis section describes the logical replication protocol, which is the message flow started by the START_REPLICATION SLOT slot_name LOGICAL replication command.
The logical streaming replication protocol builds on the primitives of the physical streaming replication protocol.
\nPostgreSQL logical decoding supports output plugins. pgoutput is the standard one used for the built-in logical replication.
Using the START_REPLICATION command, pgoutput accepts the following options:
Protocol version. Currently versions 1, 2, 3, and 4 are supported. A valid version is required.
Version 2 is supported only for server version 14 and above, and it allows streaming of large in-progress transactions.
Version 3 is supported only for server version 15 and above, and it allows streaming of two-phase commits.
Version 4 is supported only for server version 16 and above, and it allows streams of large in-progress transactions to be applied in parallel.
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. At least one publication name is required.
\nBoolean option to use binary transfer mode. Binary mode is faster than the text mode but slightly less robust.
\nBoolean option to enable sending the messages that are written by pg_logical_emit_message.
Option to enable streaming of in-progress transactions. Valid values are off (the default), on and parallel. The setting parallel enables sending extra information with some messages to be used for parallelization. Minimum protocol version 2 is required to turn it on. Minimum protocol version 4 is required for the parallel value.
Boolean option to enable two-phase transactions. Minimum protocol version 3 is required to turn it on.
\nOption to send changes by their origin. Possible values are none to only send the changes that have no origin associated, or any to send the changes regardless of their origin. This can be used to avoid loops (infinite replication of the same data) among replication nodes.
The individual protocol messages are discussed in the following subsections. Individual messages are described in Section\u00a054.9.
\nAll 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.
\nSince the streaming replication protocol supplies a message length there is no need for top-level protocol messages to embed a length in their header.
\nWith the exception of the START_REPLICATION command and the replay progress messages, all information flows only from the backend to the frontend.
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.
\nEvery 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.
\nEvery 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.)
\nRelation 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.
\nThis section describes the logical replication protocol, which is the message flow started by the START_REPLICATION SLOT slot_name LOGICAL replication command.
The logical streaming replication protocol builds on the primitives of the physical streaming replication protocol.
\nThe START_REPLICATION command can pass options to the logical decoding output plugin associated with the specified replication slot. See Section\u00a047.6.1.1 for options that are accepted by the standard (pgoutput) plugin.
The individual protocol messages are discussed in the following subsections. Individual messages are described in Section\u00a054.9.
\nAll 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.
\nSince the streaming replication protocol supplies a message length there is no need for top-level protocol messages to embed a length in their header.
\nWith the exception of the START_REPLICATION command and the replay progress messages, all information flows only from the backend to the frontend.
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.
\nEvery 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.
\nEvery 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.)
\nRelation 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.
\nThis section describes the logical replication protocol, which is the message flow started by the START_REPLICATION SLOT slot_name LOGICAL replication command.
The logical streaming replication protocol builds on the primitives of the physical streaming replication protocol.
\nThe START_REPLICATION command can pass options to the logical decoding output plugin associated with the specified replication slot. See Section\u00a047.6.1.1 for options that are accepted by the standard (pgoutput) plugin.
The individual protocol messages are discussed in the following subsections. Individual messages are described in Section\u00a054.9.
\nAll 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.
\nSince the streaming replication protocol supplies a message length there is no need for top-level protocol messages to embed a length in their header.
\nWith the exception of the START_REPLICATION command and the replay progress messages, all information flows only from the backend to the frontend.
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.
\nEvery 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.
\nEvery 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.)
\nRelation 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.
\nThis section describes the logical replication protocol, which is the message flow started by the START_REPLICATION SLOT slot_name LOGICAL replication command.
The logical streaming replication protocol builds on the primitives of the physical streaming replication protocol.
\nPostgreSQL logical decoding supports output plugins. pgoutput is the standard one used for the built-in logical replication.
Using the START_REPLICATION command, pgoutput accepts the following options:
Protocol version. Currently versions 1, 2, 3, and 4 are supported. A valid version is required.
Version 2 is supported only for server version 14 and above, and it allows streaming of large in-progress transactions.
Version 3 is supported only for server version 15 and above, and it allows streaming of two-phase commits.
Version 4 is supported only for server version 16 and above, and it allows streams of large in-progress transactions to be applied in parallel.
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. At least one publication name is required.
\nBoolean option to use binary transfer mode. Binary mode is faster than the text mode but slightly less robust.
\nBoolean option to enable sending the messages that are written by pg_logical_emit_message.
Option to enable streaming of in-progress transactions. Valid values are off (the default), on and parallel. The setting parallel enables sending extra information with some messages to be used for parallelization. Minimum protocol version 2 is required to turn it on. Minimum protocol version 4 is required for the parallel value.
Boolean option to enable two-phase transactions. Minimum protocol version 3 is required to turn it on.
\nOption to send changes by their origin. Possible values are none to only send the changes that have no origin associated, or any to send the changes regardless of their origin. This can be used to avoid loops (infinite replication of the same data) among replication nodes.
The individual protocol messages are discussed in the following subsections. Individual messages are described in Section\u00a054.9.
\nAll 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.
\nSince the streaming replication protocol supplies a message length there is no need for top-level protocol messages to embed a length in their header.
\nWith the exception of the START_REPLICATION command and the replay progress messages, all information flows only from the backend to the frontend.
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.
\nEvery 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.
\nEvery 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.)
\nRelation 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.
\n