From 2454cb07eed1ec7e68b9953b03d473d3c334ba05 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Fri, 13 May 2022 16:14:16 +0200 Subject: [PATCH] Indent protocol.sgml protocol.sgml had some unusual indentation that kept getting added on to with new additions in that file. This reindents it to be more in line with the style elsewhere. Discussion: https://www.postgresql.org/message-id/flat/15113594-649b-ce82-24c8-7522f1373da4%40enterprisedb.com --- doc/src/sgml/protocol.sgml | 11844 ++++++++++++++++------------------- 1 file changed, 5476 insertions(+), 6368 deletions(-) diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 75a7a76a558..a155370a3c4 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1597,1455 +1597,1416 @@ SELCT 1/0; - -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. + +