diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 75a7a76a558..a155370a3c4 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1597,1455 +1597,1416 @@ SELCT 1/0; - -SASL Authentication - - -SASL is a framework for authentication in connection-oriented -protocols. At the moment, PostgreSQL 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. - - - -SASL Authentication Message Flow - - - - 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. - - - - - - 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. - - - - - - 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. - - - - - - 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. - - - - - -On error, the server can abort the authentication at any stage, and send an -ErrorMessage. - - - - SCRAM-SHA-256 Authentication + + SASL Authentication - The implemented SASL mechanisms at the moment - are SCRAM-SHA-256 and its variant with channel - binding SCRAM-SHA-256-PLUS. They are described in - detail in RFC 7677 - and RFC 5802. + SASL is a framework for authentication in connection-oriented + protocols. At the moment, PostgreSQL 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. + + + + SASL Authentication Message Flow + + + + 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. + + + + + + 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. + + + + + + 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. + + + + + + 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. + + + + + + On error, the server can abort the authentication at any stage, and send an + ErrorMessage. + + + + SCRAM-SHA-256 Authentication + + + The implemented SASL mechanisms at the moment + are SCRAM-SHA-256 and its variant with channel + binding SCRAM-SHA-256-PLUS. They are described in + detail in RFC 7677 + and RFC 5802. + + + + When SCRAM-SHA-256 is used in PostgreSQL, the server will ignore the user name + that the client sends in the client-first-message. The user name + that was already sent in the startup message is used instead. + PostgreSQL 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. + + + + The SCRAM specification dictates that the password is also in UTF-8, and is + processed with the SASLprep algorithm. + PostgreSQL, 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. + + + + Channel binding is supported in PostgreSQL builds with + SSL support. The SASL mechanism name for SCRAM with channel binding is + SCRAM-SHA-256-PLUS. The channel binding type used by + PostgreSQL is tls-server-end-point. + + + + In SCRAM 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. + + + + SCRAM 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. + + + + Example + + + The server sends an AuthenticationSASL message. It includes a list of + SASL authentication mechanisms that the server can accept. + This will be SCRAM-SHA-256-PLUS + and SCRAM-SHA-256 if the server is built with SSL + support, or else just the latter. + + + + + + The client responds by sending a SASLInitialResponse message, which + indicates the chosen mechanism, SCRAM-SHA-256 or + SCRAM-SHA-256-PLUS. (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 client-first-message. + The client-first-message also contains the channel + binding type chosen by the client. + + + + + + Server sends an AuthenticationSASLContinue message, with a SCRAM + server-first-message as the content. + + + + + + Client sends a SASLResponse message, with SCRAM + client-final-message as the content. + + + + + + Server sends an AuthenticationSASLFinal message, with the SCRAM + server-final-message, followed immediately by + an AuthenticationOk message. + + + + + + + + Streaming Replication Protocol + + + To initiate streaming replication, the frontend sends the + replication parameter in the startup message. A Boolean + value of true (or on, + yes, 1) 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. -When SCRAM-SHA-256 is used in PostgreSQL, the server will ignore the user name -that the client sends in the client-first-message. The user name -that was already sent in the startup message is used instead. -PostgreSQL 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. + Passing database as the value for the + replication parameter instructs the backend to go into + logical replication walsender mode, connecting to the database specified in + the dbname parameter. In logical replication walsender + mode, the replication commands shown below as well as normal SQL commands can + be issued. -The SCRAM specification dictates that the password is also in UTF-8, and is -processed with the SASLprep algorithm. -PostgreSQL, 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. + In either physical replication or logical replication walsender mode, only the + simple query protocol can be used. -Channel binding is supported in PostgreSQL builds with -SSL support. The SASL mechanism name for SCRAM with channel binding is -SCRAM-SHA-256-PLUS. The channel binding type used by -PostgreSQL is tls-server-end-point. - - - - In SCRAM 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. - - - - SCRAM 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. - - - -Example - - - The server sends an AuthenticationSASL message. It includes a list of - SASL authentication mechanisms that the server can accept. - This will be SCRAM-SHA-256-PLUS - and SCRAM-SHA-256 if the server is built with SSL - support, or else just the latter. - - - - - The client responds by sending a SASLInitialResponse message, which - indicates the chosen mechanism, SCRAM-SHA-256 or - SCRAM-SHA-256-PLUS. (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 client-first-message. - The client-first-message also contains the channel - binding type chosen by the client. - - - - - Server sends an AuthenticationSASLContinue message, with a SCRAM - server-first-message as the content. - - - - - Client sends a SASLResponse message, with SCRAM - client-final-message as the content. - - - - - Server sends an AuthenticationSASLFinal message, with the SCRAM - server-final-message, followed immediately by - an AuthenticationOk message. - - - - - - - -Streaming Replication Protocol - - -To initiate streaming replication, the frontend sends the -replication parameter in the startup message. A Boolean -value of true (or on, -yes, 1) 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. - - - -Passing database as the value for the -replication parameter instructs the backend to go into -logical replication walsender mode, connecting to the database specified in -the dbname parameter. In logical replication walsender -mode, the replication commands shown below as well as normal SQL commands can -be issued. - - - -In either physical replication or logical replication walsender mode, only the -simple query protocol can be used. - - - - For the purpose of testing replication commands, you can make a replication - connection via psql or any other - libpq-using tool with a connection string including - the replication option, - e.g.: + For the purpose of testing replication commands, you can make a replication + connection via psql or any other + libpq-using tool with a connection string including + the replication option, + e.g.: psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - However, it is often more useful to use - (for physical replication) or - (for logical replication). - + However, it is often more useful to use + (for physical replication) or + (for logical replication). + - -Replication commands are logged in the server log when - is enabled. - + + Replication commands are logged in the server log when + is enabled. + - -The commands accepted in replication mode are: - - - IDENTIFY_SYSTEM - IDENTIFY_SYSTEM - - - - Requests the server to identify itself. Server replies with a result - set of a single row, containing four fields: - + + The commands accepted in replication mode are: + + + + IDENTIFY_SYSTEM + IDENTIFY_SYSTEM + + + + Requests the server to identify itself. Server replies with a result + set of a single row, containing four fields: + - - - - systemid (text) - - - - 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. - - - + + systemid (text) + + + 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. + + + - - - timeline (int4) - - - - Current timeline ID. Also useful to check that the standby is - consistent with the primary. - - - + + timeline (int4) + + + Current timeline ID. Also useful to check that the standby is + consistent with the primary. + + + - - - xlogpos (text) - - - - Current WAL flush location. Useful to get a known location in the - write-ahead log where streaming can start. - - - - - - - dbname (text) - - - - Database connected to or null. - - - + + xlogpos (text) + + + Current WAL flush location. Useful to get a known location in the + write-ahead log where streaming can start. + + + + + dbname (text) + + + Database connected to or null. + + + - - - + + - - SHOW name - SHOW - - - - Requests the server to send the current setting of a run-time parameter. - This is similar to the SQL command . - + + SHOW name + SHOW + + + + Requests the server to send the current setting of a run-time parameter. + This is similar to the SQL command . + - - - name - + + + name + The name of a run-time parameter. Available parameters are documented in . - - - - - - - - TIMELINE_HISTORY tli - TIMELINE_HISTORY - - - - Requests the server to send over the timeline history file for timeline - tli. Server replies with a - result set of a single row, containing two fields. While the fields - are labeled as text, they effectively return raw bytes, - with no encoding conversion: - - - - - - - filename (text) - - - - File name of the timeline history file, e.g., 00000002.history. - - - - - - - content (text) - - - - Contents of the timeline history file. - - - - + + - - - + + - - CREATE_REPLICATION_SLOT slot_name [ TEMPORARY ] { PHYSICAL | LOGICAL } [ ( option [, ...] ) ] - CREATE_REPLICATION_SLOT - - - - Create a physical or logical replication - slot. See for more about - replication slots. - - - - slot_name - + + TIMELINE_HISTORY tli + TIMELINE_HISTORY + + + + Requests the server to send over the timeline history file for timeline + tli. Server replies with a + result set of a single row, containing two fields. While the fields + are labeled as text, they effectively return raw bytes, + with no encoding conversion: + + + + + filename (text) + + + File name of the timeline history file, e.g., 00000002.history. + + + + + + content (text) + + + Contents of the timeline history file. + + + + + + + + + CREATE_REPLICATION_SLOT slot_name [ TEMPORARY ] { PHYSICAL | LOGICAL } [ ( option [, ...] ) ] + CREATE_REPLICATION_SLOT + + + + Create a physical or logical replication + slot. See for more about + replication slots. + + + + + slot_name + The name of the slot to create. Must be a valid replication slot name (see ). - - + + - - output_plugin - + + output_plugin + The name of the output plugin used for logical decoding (see ). - - - - - TEMPORARY - - - 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. - - - - - - The following options are supported: - - - - TWO_PHASE [ boolean ] - - - If true, this logical replication slot supports decoding of two-phase - transactions. With this option, two-phase commands like - PREPARE TRANSACTION, COMMIT PREPARED - and ROLLBACK PREPARED are decoded and transmitted. - The transaction will be decoded and transmitted at - PREPARE TRANSACTION time. - The default is false. - - - - - - RESERVE_WAL [ boolean ] - - - If true, this physical replication slot reserves WAL - immediately. Otherwise, WAL is only reserved upon - connection from a streaming replication client. - The default is false. - - - - - - SNAPSHOT { 'export' | 'use' | 'nothing' } - - - Decides what to do with the snapshot created during logical slot - initialization. 'export', which is the default, - will export the snapshot for use in other sessions. This option can't - be used inside a transaction. 'use' will use the - snapshot for the current transaction executing the command. This - option must be used in a transaction, and - CREATE_REPLICATION_SLOT must be the first command - run in that transaction. Finally, 'nothing' will - just use the snapshot for logical decoding as normal but won't do - anything else with it. - - - - - - - In response to this command, the server will send a one-row result set - containing the following fields: - - - - slot_name (text) - - - The name of the newly-created replication slot. - - consistent_point (text) + TEMPORARY - The WAL location at which the slot became consistent. This is the - earliest location from which streaming can start on this replication - slot. - - - - - - snapshot_name (text) - - - 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. - - - - - - output_plugin (text) - - - The name of the output plugin used by the newly-created replication - slot. Null if the created slot is physical. + 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. - - - - - CREATE_REPLICATION_SLOT slot_name [ TEMPORARY ] { PHYSICAL [ RESERVE_WAL ] | LOGICAL output_plugin [ EXPORT_SNAPSHOT | NOEXPORT_SNAPSHOT | USE_SNAPSHOT | TWO_PHASE ] } - - - - For compatibility with older releases, this alternative syntax for - the CREATE_REPLICATION_SLOT command is still supported. - - - + The following options are supported: - - READ_REPLICATION_SLOT slot_name + + + TWO_PHASE [ boolean ] + + + If true, this logical replication slot supports decoding of two-phase + transactions. With this option, two-phase commands like + PREPARE TRANSACTION, COMMIT PREPARED + and ROLLBACK PREPARED are decoded and transmitted. + The transaction will be decoded and transmitted at + PREPARE TRANSACTION time. + The default is false. + + + + + + RESERVE_WAL [ boolean ] + + + If true, this physical replication slot reserves WAL + immediately. Otherwise, WAL is only reserved upon + connection from a streaming replication client. + The default is false. + + + + + + SNAPSHOT { 'export' | 'use' | 'nothing' } + + + Decides what to do with the snapshot created during logical slot + initialization. 'export', which is the default, + will export the snapshot for use in other sessions. This option can't + be used inside a transaction. 'use' will use the + snapshot for the current transaction executing the command. This + option must be used in a transaction, and + CREATE_REPLICATION_SLOT must be the first command + run in that transaction. Finally, 'nothing' will + just use the snapshot for logical decoding as normal but won't do + anything else with it. + + + + + + + In response to this command, the server will send a one-row result set + containing the following fields: + + + + slot_name (text) + + + The name of the newly-created replication slot. + + + + + + consistent_point (text) + + + The WAL location at which the slot became consistent. This is the + earliest location from which streaming can start on this replication + slot. + + + + + + snapshot_name (text) + + + 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. + + + + + + output_plugin (text) + + + The name of the output plugin used by the newly-created replication + slot. Null if the created slot is physical. + + + + + + + + + + CREATE_REPLICATION_SLOT slot_name [ TEMPORARY ] { PHYSICAL [ RESERVE_WAL ] | LOGICAL output_plugin [ EXPORT_SNAPSHOT | NOEXPORT_SNAPSHOT | USE_SNAPSHOT | TWO_PHASE ] } + + + + For compatibility with older releases, this alternative syntax for + the CREATE_REPLICATION_SLOT command is still supported. + + + + + + READ_REPLICATION_SLOT slot_name READ_REPLICATION_SLOT - - - - Read some information associated with a replication slot. Returns a tuple - with NULL values if the replication slot does not - exist. This command is currently only supported for physical replication - slots. - - - In response to this command, the server will return a one-row result set, - containing the following fields: + + + + Read some information associated with a replication slot. Returns a tuple + with NULL values if the replication slot does not + exist. This command is currently only supported for physical replication + slots. + + + + In response to this command, the server will return a one-row result set, + containing the following fields: + + + slot_type (text) + + + The replication slot's type, either physical or + NULL. + + + + + + restart_lsn (text) + + + The replication slot's restart_lsn. + + + + + + restart_tli (int8) + + + The timeline ID associated with restart_lsn, + following the current timeline history. + + + + + + + + + + START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ] + START_REPLICATION + + + + Instructs server to start streaming WAL, starting at + WAL location XXX/XXX. + If TIMELINE option is specified, + streaming starts on timeline tli; + 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. + + + + If a slot's name is provided + via slot_name, it will be updated + as replication progresses so that the server knows which WAL segments, + and if hot_standby_feedback is on which transactions, + are still needed by the standby. + + + + 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. + + + + 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 int8), and the + second column is the WAL location where the switch happened (type text). 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 START_REPLICATION itself), and + is ready to accept a new command. + + + + 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: + + - - slot_type (text) + + XLogData (B) - - The replication slot's type, either physical or - NULL. - + + + Byte1('w') + + + Identifies the message as WAL data. + + + + + + Int64 + + + The starting point of the WAL data in this message. + + + + + + Int64 + + + The current end of WAL on the server. + + + + + + Int64 + + + The server's system clock at the time of transmission, as + microseconds since midnight on 2000-01-01. + + + + + + Byten + + + A section of the WAL data stream. + + + + 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. + + + + - - restart_lsn (text) + + Primary keepalive message (B) - - The replication slot's restart_lsn. - - - + + + Byte1('k') + + + Identifies the message as a sender keepalive. + + + - - restart_tli (int8) - - - The timeline ID associated with restart_lsn, - following the current timeline history. - + + Int64 + + + The current end of WAL on the server. + + + + + + Int64 + + + The server's system clock at the time of transmission, as + microseconds since midnight on 2000-01-01. + + + + + + Byte1 + + + 1 means that the client should reply to this message as soon as + possible, to avoid a timeout disconnect. 0 otherwise. + + + + - - - - - START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ] - START_REPLICATION - - - - Instructs server to start streaming WAL, starting at - WAL location XXX/XXX. - If TIMELINE option is specified, - streaming starts on timeline tli; - 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. - - - - If a slot's name is provided - via slot_name, it will be updated - as replication progresses so that the server knows which WAL segments, - and if hot_standby_feedback is on which transactions, - are still needed by the standby. - - - - 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. - - - - 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 int8), and the - second column is the WAL location where the switch happened (type text). 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 START_REPLICATION itself), and - is ready to accept a new command. - - - - 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: - - - - - - - XLogData (B) - - - - - - Byte1('w') - - - - Identifies the message as WAL data. - - - - - - Int64 - - - - The starting point of the WAL data in this message. - - - - - - Int64 - - - - The current end of WAL on the server. - - - - - - Int64 - - - - The server's system clock at the time of transmission, as - microseconds since midnight on 2000-01-01. - - - - - - Byten - - - - A section of the WAL data stream. - - - 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. - - - - - - - - - - Primary keepalive message (B) - - - - - - - Byte1('k') - - - - Identifies the message as a sender keepalive. - - - - - - Int64 - - - - The current end of WAL on the server. - - - - - - Int64 - - - - The server's system clock at the time of transmission, as - microseconds since midnight on 2000-01-01. - - - - - - Byte1 - - - - 1 means that the client should reply to this message as soon as - possible, to avoid a timeout disconnect. 0 otherwise. - - - - - - - - - - - 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): - + - - - - Standby status update (F) - - + + Standby status update (F) + + + + Byte1('r') + + + Identifies the message as a receiver status update. + + + + + + Int64 + + + The location of the last WAL byte + 1 received and written to disk + in the standby. + + + + + + Int64 + + + The location of the last WAL byte + 1 flushed to disk in + the standby. + + + + + + Int64 + + + The location of the last WAL byte + 1 applied in the standby. + + + + + + Int64 + + + The client's system clock at the time of transmission, as + microseconds since midnight on 2000-01-01. + + + + + + Byte1 + + + 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. + + + + + + + + + Hot standby feedback message (F) + + + + Byte1('h') + + + Identifies the message as a hot standby feedback message. + + + + + + Int64 + + + The client's system clock at the time of transmission, as + microseconds since midnight on 2000-01-01. + + + + + + Int32 + + + 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. + + + + + + Int32 + + + The epoch of the global xmin xid on the standby. + + + + + + Int32 + + + 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. + + + + + + Int32 + + + The epoch of the catalog_xmin xid on the standby. + + + + + + + + + + + + START_REPLICATION SLOT slot_name LOGICAL XXX/XXX [ ( option_name [ option_value ] [, ...] ) ] + + Instructs server to start streaming WAL for logical replication, + starting at either WAL location XXX/XXX or the slot's + confirmed_flush_lsn (see ), 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 + confirmed_flush_lsn matches its expectations before + issuing START_REPLICATION. + + + + 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. + + + + The messages inside the CopyBothResponse messages are of the same format + documented for START_REPLICATION ... PHYSICAL, including + two CommandComplete messages. + + + + The output plugin associated with the selected slot is used + to process the output for streaming. + + - - - Byte1('r') - - - - Identifies the message as a receiver status update. - - - - - - Int64 - - - - The location of the last WAL byte + 1 received and written to disk - in the standby. - - - - - - Int64 - - - - The location of the last WAL byte + 1 flushed to disk in - the standby. - - - - - - Int64 - - - - The location of the last WAL byte + 1 applied in the standby. - - - - - - Int64 - - - - The client's system clock at the time of transmission, as - microseconds since midnight on 2000-01-01. - - - - - - Byte1 - - - - 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. - - - - - - - - - - - - - - - Hot standby feedback message (F) - - - - - - - Byte1('h') - - - - Identifies the message as a hot standby feedback message. - - - - - - Int64 - - - - The client's system clock at the time of transmission, as - microseconds since midnight on 2000-01-01. - - - - - - Int32 - - - - 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. - - - - - - Int32 - - - - The epoch of the global xmin xid on the standby. - - - - - - Int32 - - - - 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. - - - - - - Int32 - - - - The epoch of the catalog_xmin xid on the standby. - - - - - - - - - - - - - START_REPLICATION SLOT slot_name LOGICAL XXX/XXX [ ( option_name [ option_value ] [, ...] ) ] - - - Instructs server to start streaming WAL for logical replication, - starting at either WAL location XXX/XXX or the slot's - confirmed_flush_lsn (see ), 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 - confirmed_flush_lsn matches its expectations before - issuing START_REPLICATION. - - - - 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. - - - - The messages inside the CopyBothResponse messages are of the same format - documented for START_REPLICATION ... PHYSICAL, including - two CommandComplete messages. - - - - The output plugin associated with the selected slot is used - to process the output for streaming. - - - - - SLOT slot_name - + + SLOT slot_name + The name of the slot to stream changes from. This parameter is required, and must correspond to an existing logical replication slot created with CREATE_REPLICATION_SLOT in LOGICAL mode. - - - - XXX/XXX - - - The WAL location to begin streaming at. - - - - - option_name - - - The name of an option passed to the slot's logical decoding plugin. - - - - - option_value - - - Optional value, in the form of a string constant, associated with the - specified option. - - - - - - + + - - - DROP_REPLICATION_SLOT slot_name WAIT - DROP_REPLICATION_SLOT - - - - 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. - - - - slot_name - + + XXX/XXX + + + The WAL location to begin streaming at. + + + + + + option_name + + + The name of an option passed to the slot's logical decoding plugin. + + + + + + option_value + + + Optional value, in the form of a string constant, associated with the + specified option. + + + + + + + + + + DROP_REPLICATION_SLOT slot_name WAIT + DROP_REPLICATION_SLOT + + + + 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. + + + + + slot_name + The name of the slot to drop. - - - - - WAIT - - - 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. - - - - - - - - - BASE_BACKUP [ ( option [, ...] ) ] - BASE_BACKUP - - - - 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: - - - LABEL 'label' - - - Sets the label of the backup. If none is specified, a backup label - of base backup will be used. The quoting rules - for the label are the same as a standard SQL string with - turned on. - - TARGET 'target' + WAIT - Tells the server where to send the backup. If the target is - client, which is the default, the backup data is - sent to the client. If it is server, the backup - data is written to the server at the pathname specified by the - TARGET_DETAIL option. If it is - blackhole, the backup data is not sent - anywhere; it is simply discarded. - - - - The server target requires superuser privilege or - being granted the pg_write_server_files role. - - - - - - TARGET_DETAIL 'detail' - - - Provides additional information about the backup target. - - - - Currently, this option can only be used when the backup target is - server. It specifies the server directory - to which the backup should be written. - - - - - - PROGRESS [ boolean ] - - - 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. - - - - - - CHECKPOINT { 'fast' | 'spread' } - - - Sets the type of checkpoint to be performed at the beginning of the - base backup. The default is spread. - - - - - - WAL [ boolean ] - - - 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 - pg_wal directory of the base directory tar - file. The default is false. - - - - - - WAIT [ boolean ] - - - 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. - - - - - - COMPRESSION 'method' - - - Instructs the server to compress the backup using the specified - method. Currently, the supported methods are gzip, - lz4, and zstd. - - - - - - COMPRESSION_DETAIL detail - - - Specifies details for the chosen compression method. This should only - be used in conjunction with the COMPRESSION - 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 keyword or - keyword=value. Currently, the supported keywords - are level and workers. - - - - The level keyword sets the compression level. - For gzip the compression level should be an - integer between 1 and 9, for lz4 an integer - between 1 and 12, and for zstd an integer - between 1 and 22. - - - - The workers keyword sets the number of threads - that should be used for parallel compression. Parallel compression - is supported only for zstd. - - - - - - MAX_RATE rate - - - 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. - - - - - - TABLESPACE_MAP [ boolean ] - - - If true, include information about symbolic links present in the - directory pg_tblspc in a file named - tablespace_map. The tablespace map file includes - each symbolic link name as it exists in the directory - pg_tblspc/ and the full path of that symbolic link. - The default is false. - - - - - - VERIFY_CHECKSUMS [ boolean ] - - - If true, checksums are verified during a base backup if they are - enabled. If false, this is skipped. The default is true. - - - - - - MANIFEST manifest_option - - - When this option is specified with a value of yes - or force-encode, 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 force-encode forces all filenames - to be hex-encoded; otherwise, this type of encoding is performed only - for files whose names are non-UTF8 octet sequences. - force-encode 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 MANIFEST 'no'. - - - - - - MANIFEST_CHECKSUMS checksum_algorithm - - - Specifies the checksum algorithm that should be applied to each file included - in the backup manifest. Currently, the available - algorithms are NONE, CRC32C, - SHA224, SHA256, - SHA384, and SHA512. - The default is CRC32C. + 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. - - - When the backup is started, the server will first send two - ordinary result sets, followed by one or more CopyOutResponse - results. - - - 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. - - - The second ordinary result set has one row for each tablespace. - The fields in this row are: + + + + + BASE_BACKUP [ ( option [, ...] ) ] + BASE_BACKUP + + + + 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: + + + + LABEL 'label' + + + Sets the label of the backup. If none is specified, a backup label + of base backup will be used. The quoting rules + for the label are the same as a standard SQL string with + turned on. + + + + + + TARGET 'target' + + + Tells the server where to send the backup. If the target is + client, which is the default, the backup data is + sent to the client. If it is server, the backup + data is written to the server at the pathname specified by the + TARGET_DETAIL option. If it is + blackhole, the backup data is not sent + anywhere; it is simply discarded. + + + + The server target requires superuser privilege or + being granted the pg_write_server_files role. + + + + + + TARGET_DETAIL 'detail' + + + Provides additional information about the backup target. + + + + Currently, this option can only be used when the backup target is + server. It specifies the server directory + to which the backup should be written. + + + + + + PROGRESS [ boolean ] + + + 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. + + + + + + CHECKPOINT { 'fast' | 'spread' } + + + Sets the type of checkpoint to be performed at the beginning of the + base backup. The default is spread. + + + + + + WAL [ boolean ] + + + 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 + pg_wal directory of the base directory tar + file. The default is false. + + + + + + WAIT [ boolean ] + + + 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. + + + + + + COMPRESSION 'method' + + + Instructs the server to compress the backup using the specified + method. Currently, the supported methods are gzip, + lz4, and zstd. + + + + + + COMPRESSION_DETAIL detail + + + Specifies details for the chosen compression method. This should only + be used in conjunction with the COMPRESSION + 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 keyword or + keyword=value. Currently, the supported keywords + are level and workers. + + + + The level keyword sets the compression level. + For gzip the compression level should be an + integer between 1 and 9, for lz4 an integer + between 1 and 12, and for zstd an integer + between 1 and 22. + + + + The workers keyword sets the number of threads + that should be used for parallel compression. Parallel compression + is supported only for zstd. + + + + + + MAX_RATE rate + + + 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. + + + + + + TABLESPACE_MAP [ boolean ] + + + If true, include information about symbolic links present in the + directory pg_tblspc in a file named + tablespace_map. The tablespace map file includes + each symbolic link name as it exists in the directory + pg_tblspc/ and the full path of that symbolic link. + The default is false. + + + + + + VERIFY_CHECKSUMS [ boolean ] + + + If true, checksums are verified during a base backup if they are + enabled. If false, this is skipped. The default is true. + + + + + + MANIFEST manifest_option + + + When this option is specified with a value of yes + or force-encode, 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 force-encode forces all filenames + to be hex-encoded; otherwise, this type of encoding is performed only + for files whose names are non-UTF8 octet sequences. + force-encode 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 MANIFEST 'no'. + + + + + + MANIFEST_CHECKSUMS checksum_algorithm + + + Specifies the checksum algorithm that should be applied to each file included + in the backup manifest. Currently, the available + algorithms are NONE, CRC32C, + SHA224, SHA256, + SHA384, and SHA512. + The default is CRC32C. + + + + + + + + When the backup is started, the server will first send two + ordinary result sets, followed by one or more CopyOutResponse + results. + + + + 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. + + + + The second ordinary result set has one row for each tablespace. + The fields in this row are: + + + + spcoid (oid) + + + The OID of the tablespace, or null if it's the base + directory. + + + + + + spclocation (text) + + + The full path of the tablespace directory, or null + if it's the base directory. + + + + + + size (int8) + + + The approximate size of the tablespace, in kilobytes (1024 bytes), + if progress report has been requested; otherwise it's null. + + + + + + + + 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: + + - spcoid (oid) - - - The OID of the tablespace, or null if it's the base - directory. - - - - - spclocation (text) - - - The full path of the tablespace directory, or null - if it's the base directory. - - - - - size (int8) - - - The approximate size of the tablespace, in kilobytes (1024 bytes), - if progress report has been requested; otherwise it's null. - - - - - - - - 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: - - - - - - new archive (B) - + + - Byte1('n') - - 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 ustar interchange format specified - in the POSIX 1003.1-2008 standard). - + Byte1('n') + + 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 ustar interchange format specified + in the POSIX 1003.1-2008 standard). + - - String - - The file name for this archive. - - - - String - - For the main data directory, an empty string. For other - tablespaces, the full path to the directory from which this - archive was created. - - - - - + + String + + The file name for this archive. + + + + + String + + For the main data directory, an empty string. For other + tablespaces, the full path to the directory from which this + archive was created. + + + + + + + manifest (B) - + + - Byte1('m') - - Identifes the message as indicating the start of the backup - manifest. - + Byte1('m') + + Identifes the message as indicating the start of the backup + manifest. + - - + + + - + archive or manifest data (B) - + + - Byte1('d') - - Identifes the message as containing archive or manifest data. - + Byte1('d') + + Identifes the message as containing archive or manifest data. + - - Byten - - Data bytes. - - - - - + + Byten + + Data bytes. + + + + + + + progress report (B) - + + - Byte1('p') - - Identifes the message as a progress report. - + Byte1('p') + + Identifes the message as a progress report. + - - Int64 - - The number of bytes from the current tablespace for which - processing has been completed. - - - - + + Int64 + + The number of bytes from the current tablespace for which + processing has been completed. + + + + + - - - 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. - + + 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. + - - The tar archive for the data directory and each tablespace will contain - all files in the directories, regardless of whether they are - PostgreSQL files or other files added to the same - directory. The only excluded files are: - - - - postmaster.pid - - - - - postmaster.opts - - - - - pg_internal.init (found in multiple directories) - - - - - Various temporary files and directories created during the operation - of the PostgreSQL server, such as any file or directory beginning - with pgsql_tmp and temporary relations. - - - - - Unlogged relations, except for the init fork which is required to - recreate the (empty) unlogged relation on recovery. - - - - - pg_wal, including subdirectories. If the backup is run - with WAL files included, a synthesized version of pg_wal will be - included, but it will only contain the files necessary for the - backup to work, not the rest of the contents. - - - - - pg_dynshmem, pg_notify, - pg_replslot, pg_serial, - pg_snapshots, pg_stat_tmp, and - pg_subtrans are copied as empty directories (even if - they are symbolic links). - - - - - 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 pg_tblspc are maintained.) - - - - Owner, group, and file mode are set if the underlying file system on - the server supports it. - - - - + + The tar archive for the data directory and each tablespace will contain + all files in the directories, regardless of whether they are + PostgreSQL files or other files added to the same + directory. The only excluded files are: - - - + + + + postmaster.pid + + + + + postmaster.opts + + + + + pg_internal.init (found in multiple directories) + + + + + Various temporary files and directories created during the operation + of the PostgreSQL server, such as any file or directory beginning + with pgsql_tmp and temporary relations. + + + + + Unlogged relations, except for the init fork which is required to + recreate the (empty) unlogged relation on recovery. + + + + + pg_wal, including subdirectories. If the backup is run + with WAL files included, a synthesized version of pg_wal will be + included, but it will only contain the files necessary for the + backup to work, not the rest of the contents. + + + + + pg_dynshmem, pg_notify, + pg_replslot, pg_serial, + pg_snapshots, pg_stat_tmp, and + pg_subtrans are copied as empty directories (even if + they are symbolic links). + + + + + 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 pg_tblspc are maintained.) + + + + Owner, group, and file mode are set if the underlying file system on + the server supports it. + + + + + + Logical Streaming Replication Protocol @@ -3184,1083 +3145,877 @@ The commands accepted in replication mode are: - -Message Data Types - - -This section describes the base data types used in messages. - - - - - - Intn(i) - - - - An n-bit integer in network byte - order (most significant byte first). - If i is specified it - is the exact value that will appear, otherwise the value - is variable. Eg. Int16, Int32(42). - - - - - - - Intn[k] - - - - An array of k - n-bit integers, each in network - byte order. The array length k - is always determined by an earlier field in the message. - Eg. Int16[M]. - - - - - - - String(s) - - - - A null-terminated string (C-style string). There is no - specific length limitation on strings. - If s is specified it is the exact - value that will appear, otherwise the value is variable. - Eg. String, String("user"). - - - - -There is no predefined limit 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. - - - - - - - - Byten(c) - - - - Exactly n bytes. If the field - width n is not a constant, it is - always determinable from an earlier field in the message. - If c is specified it is the exact - value. Eg. Byte2, Byte1('\n'). - - - - - - - - - -Message Formats - - -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.) - - - - - - - -AuthenticationOk (B) - - - - - - - - Byte1('R') - - - - Identifies the message as an authentication request. - - - - - - Int32(8) - - - - Length of message contents in bytes, including self. - - - - - - Int32(0) - - - - Specifies that the authentication was successful. - - - - - - - - - - - - -AuthenticationKerberosV5 (B) - - - - - - - - Byte1('R') - - - - Identifies the message as an authentication request. - - - - - - Int32(8) - - - - Length of message contents in bytes, including self. - - - - - - Int32(2) - - - - Specifies that Kerberos V5 authentication is required. - - - - - - - - - - - -AuthenticationCleartextPassword (B) - - - - - - - - Byte1('R') - - - - Identifies the message as an authentication request. - - - - - - Int32(8) - - - - Length of message contents in bytes, including self. - - - - - - Int32(3) - - - - Specifies that a clear-text password is required. - - - - - - - - - - - -AuthenticationMD5Password (B) - - - - - - - - Byte1('R') - - - - Identifies the message as an authentication request. - - - - - - Int32(12) - - - - Length of message contents in bytes, including self. - - - - - - Int32(5) - - - - Specifies that an MD5-encrypted password is required. - - - - - - Byte4 - - - - The salt to use when encrypting the password. - - - - - - - - - - - - -AuthenticationSCMCredential (B) - - - - - - - - Byte1('R') - - - - Identifies the message as an authentication request. - - - - - - Int32(8) - - - - Length of message contents in bytes, including self. - - - - - - Int32(6) - - - - Specifies that an SCM credentials message is required. - - - - - - - - - - - - -AuthenticationGSS (B) - - - - - - - - Byte1('R') - - - - Identifies the message as an authentication request. - - - - - - Int32(8) - - - - Length of message contents in bytes, including self. - - - - - - Int32(7) - - - - Specifies that GSSAPI authentication is required. - - - - - - - - - - - - -AuthenticationGSSContinue (B) - - - - - - - - Byte1('R') - - - - Identifies the message as an authentication request. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Int32(8) - - - - Specifies that this message contains GSSAPI or SSPI data. - - - - - - Byten - - - - GSSAPI or SSPI authentication data. - - - - - - - - - - - - -AuthenticationSSPI (B) - - - - - - - - Byte1('R') - - - - Identifies the message as an authentication request. - - - - - - Int32(8) - - - - Length of message contents in bytes, including self. - - - - - - Int32(9) - - - - Specifies that SSPI authentication is required. - - - - - - - - - - - - -AuthenticationSASL (B) - - - - - - - - Byte1('R') - - - - Identifies the message as an authentication request. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Int32(10) - - - - Specifies that SASL authentication is required. - - - - -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: - - - - String - - - - Name of a SASL authentication mechanism. - - - - - - - - - - - - -AuthenticationSASLContinue (B) - - - - - - - - Byte1('R') - - - - Identifies the message as an authentication request. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Int32(11) - - - - Specifies that this message contains a SASL challenge. - - - - - - Byten - - - - SASL data, specific to the SASL mechanism being used. - - - - - - - - - - - - -AuthenticationSASLFinal (B) - - - - - - - - Byte1('R') - - - - Identifies the message as an authentication request. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Int32(12) - - - - Specifies that SASL authentication has completed. - - - - - - Byten - - - - SASL outcome "additional data", specific to the SASL mechanism - being used. - - - - - - - - - - - - -BackendKeyData (B) - - - - - - - - Byte1('K') - - - - Identifies the message as cancellation key data. - The frontend must save these values if it wishes to be - able to issue CancelRequest messages later. - - - - - - Int32(12) - - - - Length of message contents in bytes, including self. - - - - - - Int32 - - - - The process ID of this backend. - - - - - - Int32 - - - - The secret key of this backend. - - - - - - - - - - - - -Bind (F) - - - - - - - - Byte1('B') - - - - Identifies the message as a Bind command. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - String - - - - The name of the destination portal - (an empty string selects the unnamed portal). - - - - - - String - - - - The name of the source prepared statement - (an empty string selects the unnamed prepared statement). - - - - - - Int16 - - - - The number of parameter format codes that follow - (denoted C 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. - - - - - - Int16[C] - - - - The parameter format codes. Each must presently be - zero (text) or one (binary). - - - - - - Int16 - - - - The number of parameter values that follow (possibly zero). - This must match the number of parameters needed by the query. - - - - - Next, the following pair of fields appear for each parameter: - - - - Int32 - - - - 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. - - - - - - Byten - - - - The value of the parameter, in the format indicated by the - associated format code. - n is the above length. - - - - - After the last parameter, the following fields appear: - - - - Int16 - - - - The number of result-column format codes that follow - (denoted R 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. - - - - - - Int16[R] - - - - The result-column format codes. Each must presently be - zero (text) or one (binary). - - - - - - - - - - - -BindComplete (B) - - - - - - - - Byte1('2') - - - - Identifies the message as a Bind-complete indicator. - - - - - - Int32(4) - - - - Length of message contents in bytes, including self. - - - - - - - - - - - - -CancelRequest (F) - - - - - - - - Int32(16) - - - - Length of message contents in bytes, including self. - - - - - - Int32(80877102) - - - - The cancel request code. The value is chosen to contain - 1234 in the most significant 16 bits, and 5678 in the - least significant 16 bits. (To avoid confusion, this code - must not be the same as any protocol version number.) - - - - - - Int32 - - - - The process ID of the target backend. - - - - - - Int32 - - - - The secret key for the target backend. - - - - - - - - - - - - -Close (F) - - - - - - - - Byte1('C') - - - - Identifies the message as a Close command. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Byte1 - - - - 'S' to close a prepared statement; or - 'P' to close a portal. - - - - - - String - - - - The name of the prepared statement or portal to close - (an empty string selects the unnamed prepared statement - or portal). - - - - - - - - - - - -CloseComplete (B) - - - - - - - - Byte1('3') - - - - Identifies the message as a Close-complete indicator. - - - - - - Int32(4) - - - - Length of message contents in bytes, including self. - - - - - - - - - - - - -CommandComplete (B) - - - - - - - - Byte1('C') - - - - Identifies the message as a command-completed response. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - String - - + + Message Data Types + + + This section describes the base data types used in messages. + + + + + Intn(i) + + + An n-bit integer in network byte + order (most significant byte first). + If i is specified it + is the exact value that will appear, otherwise the value + is variable. Eg. Int16, Int32(42). + + + + + + Intn[k] + + + An array of k + n-bit integers, each in network + byte order. The array length k + is always determined by an earlier field in the message. + Eg. Int16[M]. + + + + + + String(s) + + + A null-terminated string (C-style string). There is no + specific length limitation on strings. + If s is specified it is the exact + value that will appear, otherwise the value is variable. + Eg. String, String("user"). + + + + + There is no predefined limit 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. + + + + + + + Byten(c) + + + Exactly n bytes. If the field + width n is not a constant, it is + always determinable from an earlier field in the message. + If c is specified it is the exact + value. Eg. Byte2, Byte1('\n'). + + + + + + + + Message Formats + + + 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.) + + + + + AuthenticationOk (B) + + + + Byte1('R') + + + Identifies the message as an authentication request. + + + + + + Int32(8) + + + Length of message contents in bytes, including self. + + + + + + Int32(0) + + + Specifies that the authentication was successful. + + + + + + + + + AuthenticationKerberosV5 (B) + + + + + Byte1('R') + + + Identifies the message as an authentication request. + + + + + + Int32(8) + + + Length of message contents in bytes, including self. + + + + + + Int32(2) + + + Specifies that Kerberos V5 authentication is required. + + + + + + + + + AuthenticationCleartextPassword (B) + + + + + Byte1('R') + + + Identifies the message as an authentication request. + + + + + + Int32(8) + + + Length of message contents in bytes, including self. + + + + + + Int32(3) + + + Specifies that a clear-text password is required. + + + + + + + + + AuthenticationMD5Password (B) + + + + Byte1('R') + + + Identifies the message as an authentication request. + + + + + + Int32(12) + + + Length of message contents in bytes, including self. + + + + + + Int32(5) + + + Specifies that an MD5-encrypted password is required. + + + + + + Byte4 + + + The salt to use when encrypting the password. + + + + + + + + + AuthenticationSCMCredential (B) + + + + Byte1('R') + + + Identifies the message as an authentication request. + + + + + + Int32(8) + + + Length of message contents in bytes, including self. + + + + + + Int32(6) + + + Specifies that an SCM credentials message is required. + + + + + + + + + AuthenticationGSS (B) + + + + Byte1('R') + + + Identifies the message as an authentication request. + + + + + Int32(8) + + + Length of message contents in bytes, including self. + + + + + + Int32(7) + + + Specifies that GSSAPI authentication is required. + + + + + + + + + AuthenticationGSSContinue (B) + + + + Byte1('R') + + + Identifies the message as an authentication request. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Int32(8) + + + Specifies that this message contains GSSAPI or SSPI data. + + + + + + Byten + + + GSSAPI or SSPI authentication data. + + + + + + + + + AuthenticationSSPI (B) + + + + Byte1('R') + + + Identifies the message as an authentication request. + + + + + + Int32(8) + + + Length of message contents in bytes, including self. + + + + + + Int32(9) + + + Specifies that SSPI authentication is required. + + + + + + + + + AuthenticationSASL (B) + + + + Byte1('R') + + + Identifies the message as an authentication request. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Int32(10) + + + Specifies that SASL authentication is required. + + + + + + + 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: + + + + String + + + Name of a SASL authentication mechanism. + + + + + + + + + + AuthenticationSASLContinue (B) + + + + Byte1('R') + + + Identifies the message as an authentication request. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Int32(11) + + + Specifies that this message contains a SASL challenge. + + + + + + Byten + + + SASL data, specific to the SASL mechanism being used. + + + + + + + + + AuthenticationSASLFinal (B) + + + + Byte1('R') + + + Identifies the message as an authentication request. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Int32(12) + + + Specifies that SASL authentication has completed. + + + + + + Byten + + + SASL outcome "additional data", specific to the SASL mechanism + being used. + + + + + + + + + BackendKeyData (B) + + + + Byte1('K') + + + Identifies the message as cancellation key data. + The frontend must save these values if it wishes to be + able to issue CancelRequest messages later. + + + + + + Int32(12) + + + Length of message contents in bytes, including self. + + + + + + Int32 + + + The process ID of this backend. + + + + + + Int32 + + + The secret key of this backend. + + + + + + + + + Bind (F) + + + + Byte1('B') + + + Identifies the message as a Bind command. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + String + + + The name of the destination portal + (an empty string selects the unnamed portal). + + + + + + String + + + The name of the source prepared statement + (an empty string selects the unnamed prepared statement). + + + + + + Int16 + + + The number of parameter format codes that follow + (denoted C 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. + + + + + + Int16[C] + + + The parameter format codes. Each must presently be + zero (text) or one (binary). + + + + + + Int16 + + + The number of parameter values that follow (possibly zero). + This must match the number of parameters needed by the query. + + + + + + + Next, the following pair of fields appear for each parameter: + + + + + Int32 + + + 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. + + + + + + Byten + + + The value of the parameter, in the format indicated by the + associated format code. + n is the above length. + + + + + + + After the last parameter, the following fields appear: + + + + + Int16 + + + The number of result-column format codes that follow + (denoted R 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. + + + + + + Int16[R] + + + The result-column format codes. Each must presently be + zero (text) or one (binary). + + + + + + + + + BindComplete (B) + + + + Byte1('2') + + + Identifies the message as a Bind-complete indicator. + + + + + + Int32(4) + + + Length of message contents in bytes, including self. + + + + + + + + + + CancelRequest (F) + + + + Int32(16) + + + Length of message contents in bytes, including self. + + + + + + Int32(80877102) + + + The cancel request code. The value is chosen to contain + 1234 in the most significant 16 bits, and 5678 in the + least significant 16 bits. (To avoid confusion, this code + must not be the same as any protocol version number.) + + + + + + Int32 + + + The process ID of the target backend. + + + + + + Int32 + + + The secret key for the target backend. + + + + + + + + + Close (F) + + + + Byte1('C') + + + Identifies the message as a Close command. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Byte1 + + + 'S' to close a prepared statement; or + 'P' to close a portal. + + + + + + String + + + The name of the prepared statement or portal to close + (an empty string selects the unnamed prepared statement + or portal). + + + + + + + + + CloseComplete (B) + + + + Byte1('3') + + + Identifies the message as a Close-complete indicator. + + + + + + Int32(4) + + + Length of message contents in bytes, including self. + + + + + + + + + CommandComplete (B) + + + + Byte1('C') + + + Identifies the message as a command-completed response. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + String + The command tag. This is usually a single word that identifies which SQL command was completed. @@ -4317,3959 +4072,3312 @@ CommandComplete (B) (Note: the row count appears only in PostgreSQL 8.2 and later.) - - - - - - - - - - - - -CopyData (F & B) - - - - - - - Byte1('d') - - - - Identifies the message as COPY data. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Byten - - - - Data that forms part of a COPY 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. - - - - - - - - - - - -CopyDone (F & B) - - - - - - - - Byte1('c') - - - - Identifies the message as a COPY-complete indicator. - - - - - - Int32(4) - - - - Length of message contents in bytes, including self. - - - - - - - - - - - - -CopyFail (F) - - - - - - - - Byte1('f') - - - - Identifies the message as a COPY-failure indicator. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - String - - - - An error message to report as the cause of failure. - - - - - - - - - - - - -CopyInResponse (B) - - - - - - - - Byte1('G') - - - - 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). - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Int8 - - - - 0 indicates the overall COPY 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 - for more information. - - - - - - Int16 - - - - The number of columns in the data to be copied - (denoted N below). - - - - - - Int16[N] - - - - 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. - - - - - - - - - - - - -CopyOutResponse (B) - - - - - - - - Byte1('H') - - - - Identifies the message as a Start Copy Out response. - This message will be followed by copy-out data. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Int8 - - - - 0 indicates the overall COPY 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 for more information. - - - - - - Int16 - - - - The number of columns in the data to be copied - (denoted N below). - - - - - - Int16[N] - - - - 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. - - - - - - - - - - - - -CopyBothResponse (B) - - - - - - - - Byte1('W') - - - - Identifies the message as a Start Copy Both response. - This message is used only for Streaming Replication. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Int8 - - - - 0 indicates the overall COPY 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 for more information. - - - - - - Int16 - - - - The number of columns in the data to be copied - (denoted N below). - - - - - - Int16[N] - - - - 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. - - - - - - - - - - - - -DataRow (B) - - - - - - - Byte1('D') - - - - Identifies the message as a data row. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Int16 - - - - The number of column values that follow (possibly zero). - - - - - Next, the following pair of fields appear for each column: - - - - Int32 - - - - 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. - - - - - - Byten - - - - The value of the column, in the format indicated by the - associated format code. - n is the above length. - - - - - - - - - - - - -Describe (F) - - - - - - - - Byte1('D') - - - - Identifies the message as a Describe command. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Byte1 - - - - 'S' to describe a prepared statement; or - 'P' to describe a portal. - - - - - - String - - - - The name of the prepared statement or portal to describe - (an empty string selects the unnamed prepared statement - or portal). - - - - - - - - - - - -EmptyQueryResponse (B) - - - - - - - - Byte1('I') - - - - Identifies the message as a response to an empty query string. - (This substitutes for CommandComplete.) - - - - - - Int32(4) - - - - Length of message contents in bytes, including self. - - - - - - - - - - - - -ErrorResponse (B) - - - - - - - - Byte1('E') - - - - Identifies the message as an error. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - 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: - - - - Byte1 - - - - 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 - . - Since more field types might be added in future, - frontends should silently ignore fields of unrecognized - type. - - - - - - String - - - - The field value. - - - - - - - - - - - - -Execute (F) - - - - - - - - Byte1('E') - - - - Identifies the message as an Execute command. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - String - - - - The name of the portal to execute - (an empty string selects the unnamed portal). - - - - - - Int32 - - - - Maximum number of rows to return, if portal contains - a query that returns rows (ignored otherwise). Zero - denotes no limit. - - - - - - - - - - - -Flush (F) - - - - - - - - Byte1('H') - - - - Identifies the message as a Flush command. - - - - - - Int32(4) - - - - Length of message contents in bytes, including self. - - - - - - - - - - - - -FunctionCall (F) - - - - - - - - Byte1('F') - - - - Identifies the message as a function call. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Int32 - - - - Specifies the object ID of the function to call. - - - - - - Int16 - - - - The number of argument format codes that follow - (denoted C 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. - - - - - - Int16[C] - - - - The argument format codes. Each must presently be - zero (text) or one (binary). - - - - - - Int16 - - - - Specifies the number of arguments being supplied to the - function. - - - - - Next, the following pair of fields appear for each argument: - - - - Int32 - - - - 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. - - - - - - Byten - - - - The value of the argument, in the format indicated by the - associated format code. - n is the above length. - - - - - After the last argument, the following field appears: - - - - Int16 - - - - The format code for the function result. Must presently be - zero (text) or one (binary). - - - - - - - - - - - - -FunctionCallResponse (B) - - - - - - - - Byte1('V') - - - - Identifies the message as a function call result. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Int32 - - - - 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. - - - - - - Byten - - - - The value of the function result, in the format indicated by - the associated format code. - n is the above length. - - - - - - - - - - - - -GSSENCRequest (F) - - - - - - - - Int32(8) - - - - Length of message contents in bytes, including self. - - - - - - Int32(80877104) - - - - The GSSAPI Encryption request code. The value is chosen to contain - 1234 in the most significant 16 bits, and 5680 in the - least significant 16 bits. (To avoid confusion, this code - must not be the same as any protocol version number.) - - - - - - - - - - - - -GSSResponse (F) - - - - - - - - Byte1('p') - - - - 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. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Byten - - - - GSSAPI/SSPI specific message data. - - - - - - - - - - -NegotiateProtocolVersion (B) - - - - - - - - Byte1('v') - - - - Identifies the message as a protocol version negotiation - message. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Int32 - - - - Newest minor protocol version supported by the server - for the major protocol version requested by the client. - - - - - - Int32 - - - - Number of protocol options not recognized by the server. - - - - - Then, for protocol option not recognized by the server, there - is the following: - - - - String - - - - The option name. - - - - - - - - - - -NoData (B) - - - - - - - - Byte1('n') - - - - Identifies the message as a no-data indicator. - - - - - - Int32(4) - - - - Length of message contents in bytes, including self. - - - - - - - - - - - - -NoticeResponse (B) - - - - - - - - Byte1('N') - - - - Identifies the message as a notice. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - 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: - - - - Byte1 - - - - 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 - . - Since more field types might be added in future, - frontends should silently ignore fields of unrecognized - type. - - - - - - String - - - - The field value. - - - - - - - - - - - - -NotificationResponse (B) - - - - - - - - Byte1('A') - - - - Identifies the message as a notification response. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Int32 - - - - The process ID of the notifying backend process. - - - - - - String - - - - The name of the channel that the notify has been raised on. - - - - - - String - - - - The payload string passed from the notifying process. - - - - - - - - - - - - -ParameterDescription (B) - - - - - - - - Byte1('t') - - - - Identifies the message as a parameter description. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Int16 - - - - The number of parameters used by the statement - (can be zero). - - - - - Then, for each parameter, there is the following: - - - - Int32 - - - - Specifies the object ID of the parameter data type. - - - - - - - - - - - -ParameterStatus (B) - - - - - - - - Byte1('S') - - - - Identifies the message as a run-time parameter status report. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - String - - - - The name of the run-time parameter being reported. - - - - - - String - - - - The current value of the parameter. - - - - - - - - - - - -Parse (F) - - - - - - - - Byte1('P') - - - - Identifies the message as a Parse command. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - String - - - - The name of the destination prepared statement - (an empty string selects the unnamed prepared statement). - - - - - - String - - - - The query string to be parsed. - - - - - - Int16 - - - - 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. - - - - - Then, for each parameter, there is the following: - - - - Int32 - - - - Specifies the object ID of the parameter data type. - Placing a zero here is equivalent to leaving the type - unspecified. - - - - - - - - - - - -ParseComplete (B) - - - - - - - - Byte1('1') - - - - Identifies the message as a Parse-complete indicator. - - - - - - Int32(4) - - - - Length of message contents in bytes, including self. - - - - - - - - - - - - -PasswordMessage (F) - - - - - - - - Byte1('p') - - - - 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. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - String - - - - The password (encrypted, if requested). - - - - - - - - - - - -PortalSuspended (B) - - - - - - - - Byte1('s') - - - - Identifies the message as a portal-suspended indicator. - Note this only appears if an Execute message's row-count limit - was reached. - - - - - - Int32(4) - - - - Length of message contents in bytes, including self. - - - - - - - - - - - - -Query (F) - - - - - - - - Byte1('Q') - - - - Identifies the message as a simple query. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - String - - - - The query string itself. - - - - - - - - - - - - -ReadyForQuery (B) - - - - - - - - Byte1('Z') - - - - Identifies the message type. ReadyForQuery is sent - whenever the backend is ready for a new query cycle. - - - - - - Int32(5) - - - - Length of message contents in bytes, including self. - - - - - - Byte1 - - - - Current backend transaction status indicator. - Possible values are 'I' if idle (not in - a transaction block); 'T' if in a transaction - block; or 'E' if in a failed transaction - block (queries will be rejected until block is ended). - - - - - - - - - - - - -RowDescription (B) - - - - - - - - Byte1('T') - - - - Identifies the message as a row description. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Int16 - - - - Specifies the number of fields in a row (can be zero). - - - - - Then, for each field, there is the following: - - - - String - - - - The field name. - - - - - - Int32 - - - - If the field can be identified as a column of a specific - table, the object ID of the table; otherwise zero. - - - - - - Int16 - - - - If the field can be identified as a column of a specific - table, the attribute number of the column; otherwise zero. - - - - - - Int32 - - - - The object ID of the field's data type. - - - - - - Int16 - - - - The data type size (see pg_type.typlen). - Note that negative values denote variable-width types. - - - - - - Int32 - - - - The type modifier (see pg_attribute.atttypmod). - The meaning of the modifier is type-specific. - - - - - - Int16 - - - - 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. - - - - - - - - - - - - -SASLInitialResponse (F) - - - - - - - - Byte1('p') - - - - 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. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - String - - - - Name of the SASL authentication mechanism that the client - selected. - - - - - - Int32 - - - - Length of SASL mechanism specific "Initial Client Response" that - follows, or -1 if there is no Initial Response. - - - - - - Byten - - - - SASL mechanism specific "Initial Response". - - - - - - - - - - - -SASLResponse (F) - - - - - - - - Byte1('p') - - - - 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. - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Byten - - - - SASL mechanism specific message data. - - - - - - - - - - - -SSLRequest (F) - - - - - - - - Int32(8) - - - - Length of message contents in bytes, including self. - - - - - - Int32(80877103) - - - - The SSL request code. The value is chosen to contain - 1234 in the most significant 16 bits, and 5679 in the - least significant 16 bits. (To avoid confusion, this code - must not be the same as any protocol version number.) - - - - - - - - - - - - -StartupMessage (F) - - - - - - - - Int32 - - - - Length of message contents in bytes, including self. - - - - - - Int32(196608) - - - - 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). - - - - - 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. user is required, others are optional. - Each parameter is specified as: - - - - String - - - - The parameter name. Currently recognized names are: - - - - - user - - - - The database user name to connect as. Required; - there is no default. - - - - - - database - - - - The database to connect to. Defaults to the user name. - - - - - - options - - - - 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 (\); write \\ to - represent a literal backslash. - - - - - - replication - - - - Used to connect in streaming replication mode, where - a small set of replication commands can be issued - instead of SQL statements. Value can be - true, false, or - database, and the default is - false. See - for details. - - - - - - In addition to the above, other parameters may be listed. - Parameter names beginning with _pq_. 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. - - - - - - String - - - - The parameter value. - - - - - - - - - - - - -Sync (F) - - - - - - - - Byte1('S') - - - - Identifies the message as a Sync command. - - - - - - Int32(4) - - - - Length of message contents in bytes, including self. - - - - - - - - - - - - -Terminate (F) - - - - - - - - Byte1('X') - - - - Identifies the message as a termination. - - - - - - Int32(4) - - - - Length of message contents in bytes, including self. - - - - - - - - - - - - - - - - -Error and Notice Message Fields - - -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. - - - - - - -S - - - - Severity: the field contents are - ERROR, FATAL, or - PANIC (in an error message), or - WARNING, NOTICE, DEBUG, - INFO, or LOG (in a notice message), - or a localized translation of one of these. Always present. - - - - - - -V - - - - Severity: the field contents are - ERROR, FATAL, or - PANIC (in an error message), or - WARNING, NOTICE, DEBUG, - INFO, or LOG (in a notice message). - This is identical to the S field except - that the contents are never localized. This is present only in - messages generated by PostgreSQL versions 9.6 - and later. - - - - - - -C - - - - Code: the SQLSTATE code for the error (see ). Not localizable. Always present. - - - - - - -M - - - - Message: the primary human-readable error message. - This should be accurate but terse (typically one line). - Always present. - - - - - - -D - - - - Detail: an optional secondary error message carrying more - detail about the problem. Might run to multiple lines. - - - - - - -H - - - - 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. - - - - - - -P - - - - 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. - - - - - - -p - - - - Internal position: this is defined the same as the P - field, but it is used when the cursor position refers to an internally - generated command rather than the one submitted by the client. - The q field will always appear when this field appears. - - - - - - -q - - - - Internal query: the text of a failed internally-generated command. - This could be, for example, an SQL query issued by a PL/pgSQL function. - - - - - - -W - - - - 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. - - - - - - -s - - - - Schema name: if the error was associated with a specific database - object, the name of the schema containing that object, if any. - - - - - - -t - - - - 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.) - - - - - - -c - - - - 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.) - - - - - - -d - - - - 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.) - - - - - - -n - - - - 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.) - - - - - - -F - - - - File: the file name of the source-code location where the error - was reported. - - - - - - -L - - - - Line: the line number of the source-code location where the error - was reported. - - - - - - -R - - - - Routine: the name of the source-code routine reporting the error. - - - - - - - - - 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 . 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. - - - - -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. - - - - - -Logical Replication Message Formats - - -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 -, and generally obey the same message -flow as physical replication. - - - - - - -Begin - - - - - - - - Byte1('B') - - - - Identifies the message as a begin message. - - - - - - Int64 (XLogRecPtr) - - - - The final LSN of the transaction. - - - - - - Int64 (TimestampTz) - - - - Commit timestamp of the transaction. The value is in number - of microseconds since PostgreSQL epoch (2000-01-01). - - - - - - Int32 (TransactionId) - - - - Xid of the transaction. - - - - - - - - - - - -Message - - - - - - - - Byte1('M') - - - - Identifies the message as a logical decoding message. - - - - - - Int32 (TransactionId) - - - - Xid of the transaction (only present for streamed transactions). - This field is available since protocol version 2. - - - - - - Int8 - - - - Flags; Either 0 for no flags or 1 if the logical decoding - message is transactional. - - - - - - Int64 (XLogRecPtr) - - - - The LSN of the logical decoding message. - - - - - - String - - - - The prefix of the logical decoding message. - - - - - - - Int32 - - - - Length of the content. - - - - - - - Byten - - - - The content of the logical decoding message. - - - - - - - - - - - -Commit - - - - - - - - Byte1('C') - - - - Identifies the message as a commit message. - - - - - - Int8(0) - - - - Flags; currently unused. - - - - - - Int64 (XLogRecPtr) - - - - The LSN of the commit. - - - - - - Int64 (XLogRecPtr) - - - - The end LSN of the transaction. - - - - - - Int64 (TimestampTz) - - - - Commit timestamp of the transaction. The value is in number - of microseconds since PostgreSQL epoch (2000-01-01). - - - - - - - - - - - -Origin - - - - - - - - Byte1('O') - - - - Identifies the message as an origin message. - - - - - - Int64 (XLogRecPtr) - - - - The LSN of the commit on the origin server. - - - - - - String - - - - Name of the origin. - - - - - - - - - Note that there can be multiple Origin messages inside a single transaction. - - - - - - - -Relation - - - - - - - - Byte1('R') - - - - Identifies the message as a relation message. - - - - - - Int32 (TransactionId) - - - - Xid of the transaction (only present for streamed transactions). - This field is available since protocol version 2. - - - - - - Int32 (Oid) - - - - OID of the relation. - - - - - - String - - - - Namespace (empty string for pg_catalog). - - - - - - String - - - - Relation name. - - - - - - - Int8 - - - - Replica identity setting for the relation (same as - relreplident in pg_class). - - - - - - - Int16 - - - - Number of columns. - - - - - Next, the following message part appears for each column included in - the publication (except generated columns): - - - - Int8 - - - - Flags for the column. Currently can be either 0 for no flags - or 1 which marks the column as part of the key. - - - - - - String - - - - Name of the column. - - - - - - Int32 (Oid) - - - - OID of the column's data type. - - - - - - Int32 - - - - Type modifier of the column (atttypmod). - - - - - - - - - - - -Type - - - - - - - - Byte1('Y') - - - - Identifies the message as a type message. - - - - - - Int32 (TransactionId) - - - - Xid of the transaction (only present for streamed transactions). - This field is available since protocol version 2. - - - - - - Int32 (Oid) - - - - OID of the data type. - - - - - - String - - - - Namespace (empty string for pg_catalog). - - - - - - String - - - - Name of the data type. - - - - - - - - - - - -Insert - - - - - - - - Byte1('I') - - - - Identifies the message as an insert message. - - - - - - Int32 (TransactionId) - - - - Xid of the transaction (only present for streamed transactions). - This field is available since protocol version 2. - - - - - - Int32 (Oid) - - - - OID of the relation corresponding to the ID in the relation - message. - - - - - - Byte1('N') - - - - Identifies the following TupleData message as a new tuple. - - - - - - - TupleData - - - - TupleData message part representing the contents of new tuple. - - - - - - - - - - - -Update - - - - - - - - Byte1('U') - - - - Identifies the message as an update message. - - - - - - Int32 (TransactionId) - - - - Xid of the transaction (only present for streamed transactions). - This field is available since protocol version 2. - - - - - - Int32 (Oid) - - - - OID of the relation corresponding to the ID in the relation - message. - - - - - - - Byte1('K') - - - - 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. - - - - - - - Byte1('O') - - - - 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. - - - - - - - TupleData - - - - TupleData message part representing the contents of the old tuple - or primary key. Only present if the previous 'O' or 'K' part - is present. - - - - - - - Byte1('N') - - - - Identifies the following TupleData message as a new tuple. - - - - - - - TupleData - - - - TupleData message part representing the contents of a new tuple. - - - - - - - - - The Update message may contain either a 'K' message part or an 'O' message part - or neither of them, but never both of them. - - - - - - - -Delete - - - - - - - - Byte1('D') - - - - Identifies the message as a delete message. - - - - - - Int32 (TransactionId) - - - - Xid of the transaction (only present for streamed transactions). - This field is available since protocol version 2. - - - - - - Int32 (Oid) - - - - OID of the relation corresponding to the ID in the relation - message. - - - - - - - Byte1('K') - - - - 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. - - - - - - - Byte1('O') - - - - 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. - - - - - - - TupleData - - - - TupleData message part representing the contents of the old tuple - or primary key, depending on the previous field. - - - - - - - - The Delete message may contain either a 'K' message part or an 'O' message part, - but never both of them. - - - - - - - -Truncate - - - - - - - - Byte1('T') - - - - Identifies the message as a truncate message. - - - - - - Int32 (TransactionId) - - - - Xid of the transaction (only present for streamed transactions). - This field is available since protocol version 2. - - - - - - Int32 - - - - Number of relations - - - - - - Int8 - - - - Option bits for TRUNCATE: - 1 for CASCADE, 2 for RESTART IDENTITY - - - - - - Int32 (Oid) - - - - OID of the relation corresponding to the ID in the relation - message. This field is repeated for each relation. - - - - - - - - - - - - - -The following messages (Stream Start, Stream Stop, Stream Commit, and -Stream Abort) are available since protocol version 2. - - - - - - - -Stream Start - - - - - - - - Byte1('S') - - - - Identifies the message as a stream start message. - - - - - - Int32 (TransactionId) - - - - Xid of the transaction. - - - - - - Int8 - - - - A value of 1 indicates this is the first stream segment for - this XID, 0 for any other stream segment. - - - - - - - - - - - -Stream Stop - - - - - - - - Byte1('E') - - - - Identifies the message as a stream stop message. - - - - - - - - - - - -Stream Commit - - - - - - - - Byte1('c') - - - - Identifies the message as a stream commit message. - - - - - - Int32 (TransactionId) - - - - Xid of the transaction. - - - - - - Int8(0) - - - - Flags; currently unused. - - - - - - Int64 (XLogRecPtr) - - - - The LSN of the commit. - - - - - - Int64 (XLogRecPtr) - - - - The end LSN of the transaction. - - - - - - Int64 (TimestampTz) - - - - Commit timestamp of the transaction. The value is in number - of microseconds since PostgreSQL epoch (2000-01-01). - - - - - - - - - - - -Stream Abort - - - - - - - - Byte1('A') - - - - Identifies the message as a stream abort message. - - - - - - Int32 (TransactionId) - - - - Xid of the transaction. - - - - - - Int32 (TransactionId) - - - - Xid of the subtransaction (will be same as xid of the transaction for top-level - transactions). - - - - - - - - - - - - -The following messages (Begin Prepare, Prepare, Commit Prepared, Rollback Prepared, Stream Prepare) -are available since protocol version 3. - - - - - - -Begin Prepare - - - - - - -Byte1('b') - - Identifies the message as the beginning of a two-phase transaction message. - - - - - - Int64 (XLogRecPtr) - - - The LSN of the prepare. - - - - - - Int64 (XLogRecPtr) - - - The end LSN of the prepared transaction. - - - - - - Int64 (TimestampTz) - - - Prepare timestamp of the transaction. The value is in number - of microseconds since PostgreSQL epoch (2000-01-01). - - - - - - Int32 (TransactionId) - - - Xid of the transaction. - - - - -String - - The user defined GID of the two-phase transaction. - - - - - - - - - - - -Prepare - - - - - - -Byte1('P') - - Identifies the message as a two-phase prepared transaction message. - - - - - - Int8(0) - - - Flags; currently unused. - - - - - - Int64 (XLogRecPtr) - - - The LSN of the prepare. - - - - - - Int64 (XLogRecPtr) - - - The end LSN of the prepared transaction. - - - - - - Int64 (TimestampTz) - - - Prepare timestamp of the transaction. The value is in number - of microseconds since PostgreSQL epoch (2000-01-01). - - - - - - Int32 (TransactionId) - - - Xid of the transaction. - - - - -String - - The user defined GID of the two-phase transaction. - - - - - - - - - - - -Commit Prepared - - - - - - -Byte1('K') - - Identifies the message as the commit of a two-phase transaction message. - - - - - - Int8(0) - - - Flags; currently unused. - - - - - - Int64 (XLogRecPtr) - - - The LSN of the commit prepared. - - - - - - Int64 (XLogRecPtr) - - - The end LSN of the commit prepared transaction. - - - - - - Int64 (TimestampTz) - - - Commit timestamp of the transaction. The value is in number - of microseconds since PostgreSQL epoch (2000-01-01). - - - - - - Int32 (TransactionId) - - - Xid of the transaction. - - - - -String - - The user defined GID of the two-phase transaction. - - - - - - - - - - - -Rollback Prepared - - - - - - -Byte1('r') - - Identifies the message as the rollback of a two-phase transaction message. - - - - - - Int8(0) - - - Flags; currently unused. - - - - - - Int64 (XLogRecPtr) - - - The end LSN of the prepared transaction. - - - - - - Int64 (XLogRecPtr) - - - The end LSN of the rollback prepared transaction. - - - - - - Int64 (TimestampTz) - - - Prepare timestamp of the transaction. The value is in number - of microseconds since PostgreSQL epoch (2000-01-01). - - - - - - Int64 (TimestampTz) - - - Rollback timestamp of the transaction. The value is in number - of microseconds since PostgreSQL epoch (2000-01-01). - - - - - - Int32 (TransactionId) - - - Xid of the transaction. - - - - -String - - The user defined GID of the two-phase transaction. - - - - - - - - - - - -Stream Prepare - - - - - - -Byte1('p') - - Identifies the message as a two-phase stream prepare message. - - - - - - Int8(0) - - - Flags; currently unused. - - - - - - Int64 (XLogRecPtr) - - - The LSN of the prepare. - - - - - - Int64 (XLogRecPtr) - - - The end LSN of the prepare transaction. - - - - - - Int64 (TimestampTz) - - - Prepare timestamp of the transaction. The value is in number - of microseconds since PostgreSQL epoch (2000-01-01). - - - - - - Int32 (TransactionId) - - - Xid of the transaction. - - - - -String - - The user defined GID of the two-phase transaction. - - - - - - - - - - - - - -The following message parts are shared by the above messages. - - - - - - - -TupleData - - - - - - - - Int16 - - - - Number of columns. - - - - - Next, one of the following submessages appears for each column (except generated columns): - - - - Byte1('n') - - - - Identifies the data as NULL value. - - - - - Or - - - - Byte1('u') - - - - Identifies unchanged TOASTed value (the actual value is not - sent). - - - - - Or - - - - Byte1('t') - - - - Identifies the data as text formatted value. - - - - - Or - - - - Byte1('b') - - - - Identifies the data as binary formatted value. - - - - - - Int32 - - - - Length of the column value. - - - - - - Byten - - - - The value of the column, either in binary or in text format. - (As specified in the preceding format byte). - n is the above length. - - - - - - - - - - - - - - - -Summary of Changes since Protocol 2.0 - - -This section provides a quick checklist of changes, for the benefit of -developers trying to update existing client libraries to protocol 3.0. - - - -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 options field, but given the -limited width of options and the lack of any way to quote -whitespace in the values, it wasn't a very safe technique.) - - - -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. - - - -ErrorResponse and NoticeResponse ('E' and 'N') -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. - - - -The ReadyForQuery ('Z') message includes a transaction status -indicator. - - - -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. - - - -There is a new extended query 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. - - - -COPY data is now encapsulated into CopyData and CopyDone messages. There -is a well-defined way to recover from errors during COPY. The special -\. last line is not needed anymore, and is not sent -during COPY OUT. -(It is still recognized as a terminator during COPY IN, but its use is -deprecated and will eventually be removed.) Binary COPY is supported. -The CopyInResponse and CopyOutResponse messages include fields indicating -the number of columns and the format of each column. - - - -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. - - - -The backend sends ParameterStatus ('S') 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. - - - -The RowDescription ('T') 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. - - - -The CursorResponse ('P') message is no longer generated by -the backend. - - - -The NotificationResponse ('A') message has an additional string -field, which can carry a payload string passed -from the NOTIFY event sender. - - - -The EmptyQueryResponse ('I') message used to include an empty -string parameter; this has been removed. - - - - + + + + + + + + CopyData (F & B) + + + + Byte1('d') + + + Identifies the message as COPY data. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Byten + + + Data that forms part of a COPY 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. + + + + + + + + + CopyDone (F & B) + + + + Byte1('c') + + + Identifies the message as a COPY-complete indicator. + + + + + + Int32(4) + + + Length of message contents in bytes, including self. + + + + + + + + + CopyFail (F) + + + + Byte1('f') + + + Identifies the message as a COPY-failure indicator. + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + String + + + An error message to report as the cause of failure. + + + + + + + + + CopyInResponse (B) + + + + Byte1('G') + + + 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). + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Int8 + + + 0 indicates the overall COPY 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 + for more information. + + + + + + Int16 + + + The number of columns in the data to be copied + (denoted N below). + + + + + + Int16[N] + + + 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. + + + + + + + + + CopyOutResponse (B) + + + + Byte1('H') + + + Identifies the message as a Start Copy Out response. + This message will be followed by copy-out data. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Int8 + + + 0 indicates the overall COPY 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 for more information. + + + + + + Int16 + + + The number of columns in the data to be copied + (denoted N below). + + + + + + Int16[N] + + + 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. + + + + + + + + + CopyBothResponse (B) + + + + Byte1('W') + + + Identifies the message as a Start Copy Both response. + This message is used only for Streaming Replication. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Int8 + + + 0 indicates the overall COPY 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 for more information. + + + + + + Int16 + + + The number of columns in the data to be copied + (denoted N below). + + + + + + Int16[N] + + + 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. + + + + + + + + + DataRow (B) + + + + Byte1('D') + + + Identifies the message as a data row. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Int16 + + + The number of column values that follow (possibly zero). + + + + + + + Next, the following pair of fields appear for each column: + + + + + Int32 + + + 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. + + + + + + Byten + + + The value of the column, in the format indicated by the + associated format code. + n is the above length. + + + + + + + + + Describe (F) + + + + Byte1('D') + + + Identifies the message as a Describe command. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Byte1 + + + 'S' to describe a prepared statement; or + 'P' to describe a portal. + + + + + + String + + + The name of the prepared statement or portal to describe + (an empty string selects the unnamed prepared statement + or portal). + + + + + + + + + EmptyQueryResponse (B) + + + + Byte1('I') + + + Identifies the message as a response to an empty query string. + (This substitutes for CommandComplete.) + + + + + + Int32(4) + + + Length of message contents in bytes, including self. + + + + + + + + + ErrorResponse (B) + + + + Byte1('E') + + + Identifies the message as an error. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + + 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: + + + + + Byte1 + + + 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 + . + Since more field types might be added in future, + frontends should silently ignore fields of unrecognized + type. + + + + + + String + + + The field value. + + + + + + + + + Execute (F) + + + + Byte1('E') + + + Identifies the message as an Execute command. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + String + + + The name of the portal to execute + (an empty string selects the unnamed portal). + + + + + + Int32 + + + Maximum number of rows to return, if portal contains + a query that returns rows (ignored otherwise). Zero + denotes no limit. + + + + + + + + + Flush (F) + + + + Byte1('H') + + + Identifies the message as a Flush command. + + + + + + Int32(4) + + + Length of message contents in bytes, including self. + + + + + + + + + FunctionCall (F) + + + + Byte1('F') + + + Identifies the message as a function call. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Int32 + + + Specifies the object ID of the function to call. + + + + + + Int16 + + + The number of argument format codes that follow + (denoted C 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. + + + + + + Int16[C] + + + The argument format codes. Each must presently be + zero (text) or one (binary). + + + + + + Int16 + + + Specifies the number of arguments being supplied to the + function. + + + + + + + Next, the following pair of fields appear for each argument: + + + + + Int32 + + + 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. + + + + + + Byten + + + The value of the argument, in the format indicated by the + associated format code. + n is the above length. + + + + + + + After the last argument, the following field appears: + + + + + Int16 + + + The format code for the function result. Must presently be + zero (text) or one (binary). + + + + + + + + + FunctionCallResponse (B) + + + + Byte1('V') + + + Identifies the message as a function call result. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Int32 + + + 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. + + + + + + Byten + + + The value of the function result, in the format indicated by + the associated format code. + n is the above length. + + + + + + + + + GSSENCRequest (F) + + + + Int32(8) + + + Length of message contents in bytes, including self. + + + + + + Int32(80877104) + + + The GSSAPI Encryption request code. The value is chosen to contain + 1234 in the most significant 16 bits, and 5680 in the + least significant 16 bits. (To avoid confusion, this code + must not be the same as any protocol version number.) + + + + + + + + + GSSResponse (F) + + + + Byte1('p') + + + 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. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Byten + + + GSSAPI/SSPI specific message data. + + + + + + + + + NegotiateProtocolVersion (B) + + + + Byte1('v') + + + Identifies the message as a protocol version negotiation + message. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Int32 + + + Newest minor protocol version supported by the server + for the major protocol version requested by the client. + + + + + + Int32 + + + Number of protocol options not recognized by the server. + + + + + + + Then, for protocol option not recognized by the server, there + is the following: + + + + + String + + + The option name. + + + + + + + + + NoData (B) + + + + Byte1('n') + + + Identifies the message as a no-data indicator. + + + + + + Int32(4) + + + Length of message contents in bytes, including self. + + + + + + + + + NoticeResponse (B) + + + + Byte1('N') + + + Identifies the message as a notice. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + + 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: + + + + + Byte1 + + + 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 + . + Since more field types might be added in future, + frontends should silently ignore fields of unrecognized + type. + + + + + + String + + + The field value. + + + + + + + + + NotificationResponse (B) + + + + Byte1('A') + + + Identifies the message as a notification response. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Int32 + + + The process ID of the notifying backend process. + + + + + + String + + + The name of the channel that the notify has been raised on. + + + + + + String + + + The payload string passed from the notifying process. + + + + + + + + + ParameterDescription (B) + + + + Byte1('t') + + + Identifies the message as a parameter description. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Int16 + + + The number of parameters used by the statement + (can be zero). + + + + + + + Then, for each parameter, there is the following: + + + + + Int32 + + + Specifies the object ID of the parameter data type. + + + + + + + + + ParameterStatus (B) + + + + Byte1('S') + + + Identifies the message as a run-time parameter status report. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + String + + + The name of the run-time parameter being reported. + + + + + + String + + + The current value of the parameter. + + + + + + + + + Parse (F) + + + + Byte1('P') + + + Identifies the message as a Parse command. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + String + + + The name of the destination prepared statement + (an empty string selects the unnamed prepared statement). + + + + + + String + + + The query string to be parsed. + + + + + + Int16 + + + 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. + + + + + + + Then, for each parameter, there is the following: + + + + + Int32 + + + Specifies the object ID of the parameter data type. + Placing a zero here is equivalent to leaving the type + unspecified. + + + + + + + + + ParseComplete (B) + + + + Byte1('1') + + + Identifies the message as a Parse-complete indicator. + + + + + + Int32(4) + + + Length of message contents in bytes, including self. + + + + + + + + + PasswordMessage (F) + + + + Byte1('p') + + + 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. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + String + + + The password (encrypted, if requested). + + + + + + + + + PortalSuspended (B) + + + + Byte1('s') + + + Identifies the message as a portal-suspended indicator. + Note this only appears if an Execute message's row-count limit + was reached. + + + + + + Int32(4) + + + Length of message contents in bytes, including self. + + + + + + + + + Query (F) + + + + Byte1('Q') + + + Identifies the message as a simple query. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + String + + + The query string itself. + + + + + + + + + ReadyForQuery (B) + + + + Byte1('Z') + + + Identifies the message type. ReadyForQuery is sent + whenever the backend is ready for a new query cycle. + + + + + + Int32(5) + + + Length of message contents in bytes, including self. + + + + + + Byte1 + + + Current backend transaction status indicator. + Possible values are 'I' if idle (not in + a transaction block); 'T' if in a transaction + block; or 'E' if in a failed transaction + block (queries will be rejected until block is ended). + + + + + + + + + RowDescription (B) + + + + Byte1('T') + + + Identifies the message as a row description. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Int16 + + + Specifies the number of fields in a row (can be zero). + + + + + + + Then, for each field, there is the following: + + + + + String + + + The field name. + + + + + + Int32 + + + If the field can be identified as a column of a specific + table, the object ID of the table; otherwise zero. + + + + + + Int16 + + + If the field can be identified as a column of a specific + table, the attribute number of the column; otherwise zero. + + + + + + Int32 + + + The object ID of the field's data type. + + + + + + Int16 + + + The data type size (see pg_type.typlen). + Note that negative values denote variable-width types. + + + + + + Int32 + + + The type modifier (see pg_attribute.atttypmod). + The meaning of the modifier is type-specific. + + + + + + Int16 + + + 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. + + + + + + + + + SASLInitialResponse (F) + + + + Byte1('p') + + + 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. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + String + + + Name of the SASL authentication mechanism that the client + selected. + + + + + + Int32 + + + Length of SASL mechanism specific "Initial Client Response" that + follows, or -1 if there is no Initial Response. + + + + + + Byten + + + SASL mechanism specific "Initial Response". + + + + + + + + + SASLResponse (F) + + + + Byte1('p') + + + 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. + + + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Byten + + + SASL mechanism specific message data. + + + + + + + + + SSLRequest (F) + + + + Int32(8) + + + Length of message contents in bytes, including self. + + + + + + Int32(80877103) + + + The SSL request code. The value is chosen to contain + 1234 in the most significant 16 bits, and 5679 in the + least significant 16 bits. (To avoid confusion, this code + must not be the same as any protocol version number.) + + + + + + + + + StartupMessage (F) + + + + Int32 + + + Length of message contents in bytes, including self. + + + + + + Int32(196608) + + + 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). + + + + + + + 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. user is required, others are optional. + Each parameter is specified as: + + + + + String + + + The parameter name. Currently recognized names are: + + + + user + + + The database user name to connect as. Required; + there is no default. + + + + + + database + + + The database to connect to. Defaults to the user name. + + + + + + options + + + 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 (\); write \\ to + represent a literal backslash. + + + + + + replication + + + Used to connect in streaming replication mode, where + a small set of replication commands can be issued + instead of SQL statements. Value can be + true, false, or + database, and the default is + false. See + for details. + + + + + + In addition to the above, other parameters may be listed. + Parameter names beginning with _pq_. 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. + + + + + + String + + + The parameter value. + + + + + + + + + Sync (F) + + + + Byte1('S') + + + Identifies the message as a Sync command. + + + + + + Int32(4) + + + Length of message contents in bytes, including self. + + + + + + + + + Terminate (F) + + + + Byte1('X') + + + Identifies the message as a termination. + + + + + + Int32(4) + + + Length of message contents in bytes, including self. + + + + + + + + + + + Error and Notice Message Fields + + + 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. + + + + + S + + + Severity: the field contents are + ERROR, FATAL, or + PANIC (in an error message), or + WARNING, NOTICE, DEBUG, + INFO, or LOG (in a notice message), + or a localized translation of one of these. Always present. + + + + + + V + + + Severity: the field contents are + ERROR, FATAL, or + PANIC (in an error message), or + WARNING, NOTICE, DEBUG, + INFO, or LOG (in a notice message). + This is identical to the S field except + that the contents are never localized. This is present only in + messages generated by PostgreSQL versions 9.6 + and later. + + + + + + C + + + Code: the SQLSTATE code for the error (see ). Not localizable. Always present. + + + + + + M + + + Message: the primary human-readable error message. + This should be accurate but terse (typically one line). + Always present. + + + + + + D + + + Detail: an optional secondary error message carrying more + detail about the problem. Might run to multiple lines. + + + + + + H + + + 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. + + + + + + P + + + 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. + + + + + + p + + + Internal position: this is defined the same as the P + field, but it is used when the cursor position refers to an internally + generated command rather than the one submitted by the client. + The q field will always appear when this field appears. + + + + + + q + + + Internal query: the text of a failed internally-generated command. + This could be, for example, an SQL query issued by a PL/pgSQL function. + + + + + + W + + + 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. + + + + + + s + + + Schema name: if the error was associated with a specific database + object, the name of the schema containing that object, if any. + + + + + + t + + + 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.) + + + + + + c + + + 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.) + + + + + + d + + + 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.) + + + + + + n + + + 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.) + + + + + + F + + + File: the file name of the source-code location where the error + was reported. + + + + + + L + + + Line: the line number of the source-code location where the error + was reported. + + + + + + R + + + Routine: the name of the source-code routine reporting the error. + + + + + + + + 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 . 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. + + + + + 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. + + + + + Logical Replication Message Formats + + + 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 + , and generally obey the same message + flow as physical replication. + + + + + Begin + + + + Byte1('B') + + + Identifies the message as a begin message. + + + + + + Int64 (XLogRecPtr) + + + The final LSN of the transaction. + + + + + + Int64 (TimestampTz) + + + Commit timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). + + + + + + Int32 (TransactionId) + + + Xid of the transaction. + + + + + + + + + Message + + + + Byte1('M') + + + Identifies the message as a logical decoding message. + + + + + + Int32 (TransactionId) + + + Xid of the transaction (only present for streamed transactions). + This field is available since protocol version 2. + + + + + + Int8 + + + Flags; Either 0 for no flags or 1 if the logical decoding + message is transactional. + + + + + + Int64 (XLogRecPtr) + + + The LSN of the logical decoding message. + + + + + + String + + + The prefix of the logical decoding message. + + + + + + Int32 + + + Length of the content. + + + + + + Byten + + + The content of the logical decoding message. + + + + + + + + + Commit + + + + Byte1('C') + + + Identifies the message as a commit message. + + + + + + Int8(0) + + + Flags; currently unused. + + + + + + Int64 (XLogRecPtr) + + + The LSN of the commit. + + + + + + Int64 (XLogRecPtr) + + + The end LSN of the transaction. + + + + + + Int64 (TimestampTz) + + + Commit timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). + + + + + + + + + Origin + + + + Byte1('O') + + + Identifies the message as an origin message. + + + + + + Int64 (XLogRecPtr) + + + The LSN of the commit on the origin server. + + + + + + String + + + Name of the origin. + + + + + + + Note that there can be multiple Origin messages inside a single transaction. + + + + + + Relation + + + + Byte1('R') + + + Identifies the message as a relation message. + + + + + + Int32 (TransactionId) + + + Xid of the transaction (only present for streamed transactions). + This field is available since protocol version 2. + + + + + + Int32 (Oid) + + + OID of the relation. + + + + + + String + + + Namespace (empty string for pg_catalog). + + + + + + String + + + Relation name. + + + + + + Int8 + + + Replica identity setting for the relation (same as + relreplident in pg_class). + + + + + + Int16 + + + Number of columns. + + + + + + + Next, the following message part appears for each column included in + the publication (except generated columns): + + + + + Int8 + + + Flags for the column. Currently can be either 0 for no flags + or 1 which marks the column as part of the key. + + + + + + String + + + Name of the column. + + + + + + Int32 (Oid) + + + OID of the column's data type. + + + + + + Int32 + + + Type modifier of the column (atttypmod). + + + + + + + + + Type + + + + Byte1('Y') + + + Identifies the message as a type message. + + + + + + Int32 (TransactionId) + + + Xid of the transaction (only present for streamed transactions). + This field is available since protocol version 2. + + + + + + Int32 (Oid) + + + OID of the data type. + + + + + + String + + + Namespace (empty string for pg_catalog). + + + + + + String + + + Name of the data type. + + + + + + + + + Insert + + + + Byte1('I') + + + Identifies the message as an insert message. + + + + + + Int32 (TransactionId) + + + Xid of the transaction (only present for streamed transactions). + This field is available since protocol version 2. + + + + + + Int32 (Oid) + + + OID of the relation corresponding to the ID in the relation + message. + + + + + + Byte1('N') + + + Identifies the following TupleData message as a new tuple. + + + + + + TupleData + + + TupleData message part representing the contents of new tuple. + + + + + + + + + Update + + + + Byte1('U') + + + Identifies the message as an update message. + + + + + + Int32 (TransactionId) + + + Xid of the transaction (only present for streamed transactions). + This field is available since protocol version 2. + + + + + + Int32 (Oid) + + + OID of the relation corresponding to the ID in the relation + message. + + + + + + Byte1('K') + + + 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. + + + + + + Byte1('O') + + + 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. + + + + + + TupleData + + + TupleData message part representing the contents of the old tuple + or primary key. Only present if the previous 'O' or 'K' part + is present. + + + + + + Byte1('N') + + + Identifies the following TupleData message as a new tuple. + + + + + + TupleData + + + TupleData message part representing the contents of a new tuple. + + + + + + + The Update message may contain either a 'K' message part or an 'O' message part + or neither of them, but never both of them. + + + + + + Delete + + + + Byte1('D') + + + Identifies the message as a delete message. + + + + + + Int32 (TransactionId) + + + Xid of the transaction (only present for streamed transactions). + This field is available since protocol version 2. + + + + + + Int32 (Oid) + + + OID of the relation corresponding to the ID in the relation + message. + + + + + + Byte1('K') + + + 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. + + + + + + Byte1('O') + + + 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. + + + + + + TupleData + + + TupleData message part representing the contents of the old tuple + or primary key, depending on the previous field. + + + + + + + The Delete message may contain either a 'K' message part or an 'O' message part, + but never both of them. + + + + + + Truncate + + + + Byte1('T') + + + Identifies the message as a truncate message. + + + + + + Int32 (TransactionId) + + + Xid of the transaction (only present for streamed transactions). + This field is available since protocol version 2. + + + + + + Int32 + + + Number of relations + + + + + + Int8 + + + Option bits for TRUNCATE: + 1 for CASCADE, 2 for RESTART IDENTITY + + + + + + Int32 (Oid) + + + OID of the relation corresponding to the ID in the relation + message. This field is repeated for each relation. + + + + + + + + + + The following messages (Stream Start, Stream Stop, Stream Commit, and + Stream Abort) are available since protocol version 2. + + + + + Stream Start + + + + Byte1('S') + + + Identifies the message as a stream start message. + + + + + + Int32 (TransactionId) + + + Xid of the transaction. + + + + + + Int8 + + + A value of 1 indicates this is the first stream segment for + this XID, 0 for any other stream segment. + + + + + + + + + Stream Stop + + + + Byte1('E') + + + Identifies the message as a stream stop message. + + + + + + + + + Stream Commit + + + + Byte1('c') + + + Identifies the message as a stream commit message. + + + + + + Int32 (TransactionId) + + + Xid of the transaction. + + + + + + Int8(0) + + + Flags; currently unused. + + + + + + Int64 (XLogRecPtr) + + + The LSN of the commit. + + + + + + Int64 (XLogRecPtr) + + + The end LSN of the transaction. + + + + + + Int64 (TimestampTz) + + + Commit timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). + + + + + + + + + Stream Abort + + + + Byte1('A') + + + Identifies the message as a stream abort message. + + + + + + Int32 (TransactionId) + + + Xid of the transaction. + + + + + + Int32 (TransactionId) + + + Xid of the subtransaction (will be same as xid of the transaction for top-level + transactions). + + + + + + + + + + The following messages (Begin Prepare, Prepare, Commit Prepared, Rollback Prepared, Stream Prepare) + are available since protocol version 3. + + + + + Begin Prepare + + + + Byte1('b') + + + Identifies the message as the beginning of a two-phase transaction message. + + + + + + Int64 (XLogRecPtr) + + + The LSN of the prepare. + + + + + + Int64 (XLogRecPtr) + + + The end LSN of the prepared transaction. + + + + + + Int64 (TimestampTz) + + + Prepare timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). + + + + + + Int32 (TransactionId) + + + Xid of the transaction. + + + + + + String + + + The user defined GID of the two-phase transaction. + + + + + + + + + Prepare + + + + Byte1('P') + + + Identifies the message as a two-phase prepared transaction message. + + + + + + Int8(0) + + + Flags; currently unused. + + + + + + Int64 (XLogRecPtr) + + + The LSN of the prepare. + + + + + + Int64 (XLogRecPtr) + + + The end LSN of the prepared transaction. + + + + + + Int64 (TimestampTz) + + + Prepare timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). + + + + + + Int32 (TransactionId) + + + Xid of the transaction. + + + + + + String + + + The user defined GID of the two-phase transaction. + + + + + + + + + Commit Prepared + + + + Byte1('K') + + + Identifies the message as the commit of a two-phase transaction message. + + + + + + Int8(0) + + + Flags; currently unused. + + + + + + Int64 (XLogRecPtr) + + + The LSN of the commit prepared. + + + + + + Int64 (XLogRecPtr) + + + The end LSN of the commit prepared transaction. + + + + + + Int64 (TimestampTz) + + + Commit timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). + + + + + + Int32 (TransactionId) + + + Xid of the transaction. + + + + + + String + + + The user defined GID of the two-phase transaction. + + + + + + + + + Rollback Prepared + + + + Byte1('r') + + + Identifies the message as the rollback of a two-phase transaction message. + + + + + + Int8(0) + + + Flags; currently unused. + + + + + + Int64 (XLogRecPtr) + + + The end LSN of the prepared transaction. + + + + + + Int64 (XLogRecPtr) + + + The end LSN of the rollback prepared transaction. + + + + + + Int64 (TimestampTz) + + + Prepare timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). + + + + + + Int64 (TimestampTz) + + + Rollback timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). + + + + + + Int32 (TransactionId) + + + Xid of the transaction. + + + + + + String + + + The user defined GID of the two-phase transaction. + + + + + + + + + Stream Prepare + + + + Byte1('p') + + + Identifies the message as a two-phase stream prepare message. + + + + + + Int8(0) + + + Flags; currently unused. + + + + + + Int64 (XLogRecPtr) + + + The LSN of the prepare. + + + + + + Int64 (XLogRecPtr) + + + The end LSN of the prepare transaction. + + + + + + Int64 (TimestampTz) + + + Prepare timestamp of the transaction. The value is in number + of microseconds since PostgreSQL epoch (2000-01-01). + + + + + + Int32 (TransactionId) + + + Xid of the transaction. + + + + + + String + + + The user defined GID of the two-phase transaction. + + + + + + + + + + The following message parts are shared by the above messages. + + + + + TupleData + + + + Int16 + + + Number of columns. + + + + + + + Next, one of the following submessages appears for each column (except generated columns): + + + + Byte1('n') + + + Identifies the data as NULL value. + + + + + Or + + + Byte1('u') + + + Identifies unchanged TOASTed value (the actual value is not + sent). + + + + + Or + + + Byte1('t') + + + Identifies the data as text formatted value. + + + + + Or + + + Byte1('b') + + + Identifies the data as binary formatted value. + + + + + + Int32 + + + Length of the column value. + + + + + + Byten + + + The value of the column, either in binary or in text format. + (As specified in the preceding format byte). + n is the above length. + + + + + + + + + + + + Summary of Changes since Protocol 2.0 + + + This section provides a quick checklist of changes, for the benefit of + developers trying to update existing client libraries to protocol 3.0. + + + + 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 options field, but given the + limited width of options and the lack of any way to quote + whitespace in the values, it wasn't a very safe technique.) + + + + 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. + + + + ErrorResponse and NoticeResponse ('E' and 'N') + 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. + + + + The ReadyForQuery ('Z') message includes a transaction status + indicator. + + + + 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. + + + + There is a new extended query 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. + + + + COPY data is now encapsulated into CopyData and CopyDone messages. There + is a well-defined way to recover from errors during COPY. The special + \. last line is not needed anymore, and is not sent + during COPY OUT. + (It is still recognized as a terminator during COPY IN, but its use is + deprecated and will eventually be removed.) Binary COPY is supported. + The CopyInResponse and CopyOutResponse messages include fields indicating + the number of columns and the format of each column. + + + + 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. + + + + The backend sends ParameterStatus ('S') 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. + + + + The RowDescription ('T') 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. + + + + The CursorResponse ('P') message is no longer generated by + the backend. + + + + The NotificationResponse ('A') message has an additional string + field, which can carry a payload string passed + from the NOTIFY event sender. + + + + The EmptyQueryResponse ('I') message used to include an empty + string parameter; this has been removed. + +