- linkend="view-pg-replication-slots"/>), whichever is greater. This
- behavior makes it easier for clients to avoid updating their local LSN
- status when there is no data to process. However, starting at a
- different LSN than requested might not catch certain kinds of client
- errors; so the client may wish to check that
- 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.
-
+
+ Int64 (TimestampTz)
+
+ Prepare timestamp of the transaction. The value is in number
+ of microseconds since PostgreSQL epoch (2000-01-01).
+
+
+
- The messages inside the CopyBothResponse messages are of the same format
- documented for START_REPLICATION ... PHYSICAL, including
- two CommandComplete messages.
-
+
+ Int32 (TransactionId)
+
+ Xid of the transaction.
+
+
+
- The output plugin associated with the selected slot is used
- to process the output for streaming.
-
+
+ String
+
+ The user defined GID of the two-phase transaction.
+
+
+
+
+
+
+
+ Commit Prepared
+
- SLOT slot_name
+ Byte1('K')
- 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.
-
+ Identifies the message as the commit of a two-phase transaction message.
+
+
- XXX/XXX
+ Int8(0)
- The WAL location to begin streaming at.
+ Flags; currently unused.
+
- option_name
+ Int64 (XLogRecPtr)
- The name of an option passed to the slot's logical decoding plugin.
+ The LSN of the commit prepared.
+
- option_value
+ Int64 (XLogRecPtr)
- Optional value, in the form of a string constant, associated with the
- specified option.
+ The end LSN of the commit prepared transaction.
-
-
-
-
-
- DROP_REPLICATION_SLOT slot_name WAIT
-
-
- 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
+ Int64 (TimestampTz)
- The name of the slot to drop.
-
+ Commit timestamp of the transaction. The value is in number
+ of microseconds since PostgreSQL epoch (2000-01-01).
+
- WAIT
+ Int32 (TransactionId)
- This option causes the command to wait if the slot is active until
- it becomes inactive, instead of the default behavior of raising an
- error.
+ Xid of the transaction.
+
+
+
+
+
+ String
+
+ The user defined GID of the two-phase transaction.
-
+
-
- BASE_BACKUP [ ( option [, ...] ) ]
-
+
+ Rollback Prepared
- 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.
+
+
+ Byte1('r')
+
+ Identifies the message as the rollback of a two-phase transaction message.
+
+
+
+ Int8(0)
+
- 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.
-
+ Flags; currently unused.
+
+
+
+
+ Int64 (XLogRecPtr)
+
- 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:
-
-
-
+ The end LSN of the prepared transaction.
+
+
+
- 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).
-
-
-
- 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.
-
-
-
+ Int64 (XLogRecPtr)
+
+ The end LSN of the rollback prepared transaction.
+
+
- manifest (B)
-
- Byte1('m')
- Identifes the message as indicating the start of the backup
- manifest.
-
-
-
+ Int64 (TimestampTz)
+
+ Prepare timestamp of the transaction. The value is in number
+ of microseconds since PostgreSQL epoch (2000-01-01).
+
+
- archive or manifest data (B)
-
- Byte1('d')
- Identifes the message as containing archive or manifest data.
-
-
-
- Byten
- Data bytes.
-
-
-
+ Int64 (TimestampTz)
+
+ Rollback timestamp of the transaction. The value is in number
+ of microseconds since PostgreSQL epoch (2000-01-01).
+
+
- progress report (B)
-
- Byte1('p')
- Identifes the message as a progress report.
-
-
-
- Int64
- The number of bytes from the current tablespace for which
- processing has been completed.
-
-
-
+ Int32 (TransactionId)
+
+ Xid of the transaction.
+
+
-
-
-
- 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.
-
+
+ String
+
+ The user defined GID of the two-phase transaction.
+
+
+
+
+
+
- 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:
- >
+ >
+ Stream Prepare
+
+
+
+ Byte1('p')>
- postmaster.pid
+ Identifies the message as a two-phase stream prepare message.
+
+
+
+ Int8(0)
- postmaster.opts
+ Flags; currently unused.
+
+
+
+ Int64 (XLogRecPtr)
- pg_internal.init (found in multiple directories)
+ The LSN of the prepare.
+
+
+
+ Int64 (XLogRecPtr)
- 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.
+ The end LSN of the prepare transaction.
+
+
+
+ Int64 (TimestampTz)
- Unlogged relations, except for the init fork which is required to
- recreate the (empty) unlogged relation on recovery.
+ Prepare timestamp of the transaction. The value is in number
+ of microseconds since PostgreSQL epoch (2000-01-01).
+
+
+
+ Int32 (TransactionId)
- 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.
+ Xid of the transaction.
+
+
+
+ String
- 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).
+ The user defined GID of the two-phase transaction.
+
+
+
+
+
+
+ The following message parts are shared by the above messages.
+
+
+
+
+ TupleData
+
+
+
+ Int16
- 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.)
+ Number of columns.
-
- Owner, group, and file mode are set if the underlying file system on
- the server supports it.
-
-
-
-
-
-
+
+
-
+ Next, one of the following submessages appears for each column (except generated columns):
-
-
Logical Streaming Replication Protocol
+
+
+ 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.
+
+
+
- This section describes the logical replication protocol, which is the message
- flow started by the START_REPLICATION
- SLOT slot_name
- LOGICAL replication command.
-
+
+ Int32
+
+ Length of the column value.
+
+
+
- The logical streaming replication protocol builds on the primitives of
- the physical streaming replication protocol.
-
+
+ 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.
+
+
+
+
+
+
+
+
+
- 2 id="protocol-logical-replication-params">
-
<span class="marked">Logical Streaming Replication Parameters</span>
+ 1 id="protocol-changes">
+
<span class="marked">Summary of Changes since Protocol 2.0</span>
- The logical replication START_REPLICATION command
- accepts following parameters:
-
-
-
-
- proto_version
-
-
- Protocol version. Currently versions 1, 2,
- and 3 are supported.
-
- Version 2 is supported only for server version 14
- and above, and it allows streaming of large in-progress transactions.
-
- Version 3 is supported only for server version 15
- and above, and it allows streaming of two-phase transactions.
-
-
-
-
-
-
- publication_names
-
-
- Comma separated list of publication names for which to subscribe
- (receive changes). The individual publication names are treated
- as standard objects names and can be quoted the same as needed.
-
-
-
-
-
+ This section provides a quick checklist of changes, for the benefit of
+ developers trying to update existing client libraries to protocol 3.0.
-
-
-
-
Logical Replication Protocol Messages
- The individual protocol messages are discussed in the following
- subsections. Individual messages are described in
- .
+ 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 top-level protocol messages begin with a message type byte.
- While represented in code as a character, this is a signed byte with no
- associated encoding.
+ All messages now have a length count immediately following the message type
+ byte (except for startup packets, which have no type byte). Also note that
+ PasswordMessage now has a type byte.
- Since the streaming replication protocol supplies a message length there
- is no need for top-level protocol messages to embed a length in their
- header.
+ ErrorResponse and NoticeResponse ('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.
-
-
-
-
Logical Replication Protocol Message Flow
-
- With the exception of the START_REPLICATION command and
- the replay progress messages, all information flows only from the backend
- to the frontend.
+ The ReadyForQuery ('Z') message includes a transaction status
+ indicator.
- The logical replication protocol sends individual transactions one by one.
- This means that all messages between a pair of Begin and Commit messages
- belong to the same transaction. Similarly, all messages between a pair of
- Begin Prepare and Prepare messages belong to the same transaction.
- It also sends changes of large in-progress transactions between a pair of
- Stream Start and Stream Stop messages. The last stream of such a transaction
- contains a Stream Commit or Stream Abort message.
+ The distinction between BinaryRow and DataRow message types is gone; the
+ single DataRow message type serves for returning data in all formats.
+ Note that the layout of DataRow has changed to make it easier to parse.
+ Also, the representation of binary values has changed: it is no longer
+ directly tied to the server's internal representation.
- Every sent transaction contains zero or more DML messages (Insert,
- Update, Delete). In case of a cascaded setup it can also contain Origin
- messages. The origin message indicates that the transaction originated on
- different replication node. Since a replication node in the scope of logical
- replication protocol can be pretty much anything, the only identifier
- is the origin name. It's downstream's responsibility to handle this as
- needed (if needed). The Origin message is always sent before any DML
- messages in the transaction.
+ There is a new 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.
- Every DML message contains a relation OID, identifying the publisher's
- relation that was acted on. Before the first DML message for a given
- relation OID, a Relation message will be sent, describing the schema of
- that relation. Subsequently, a new Relation message will be sent if
- the relation's definition has changed since the last Relation message
- was sent for it. (The protocol assumes that the client is capable of
- remembering this metadata for as many relations as needed.)
+ 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.
- Relation messages identify column types by their OIDs. In the case
- of a built-in type, it is assumed that the client can look up that
- type OID locally, so no additional data is needed. For a non-built-in
- type OID, a Type message will be sent before the Relation message,
- to provide the type name associated with that OID. Thus, a client that
- needs to specifically identify the types of relation columns should
- cache the contents of Type messages, and first consult that cache to
- see if the type OID is defined there. If not, look up the type OID
- locally.
+ The layout of FunctionCall and FunctionCallResponse messages has changed.
+ FunctionCall can now support passing NULL arguments to functions. It also
+ can handle passing parameters and retrieving results in either text or
+ binary format. There is no longer any reason to consider FunctionCall a
+ potential security hole, since it does not offer direct access to internal
+ server data representations.
-
-
-
-
-
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.
-
-
- For an INSERT command, the tag is
- INSERT oid
- rows, where
- rows is the number of rows
- inserted. oid used to be the object ID
- of the inserted row if rows was 1
- and the target table had OIDs, but OIDs system columns are
- not supported anymore; therefore oid
- is always 0.
-
-
- For a DELETE command, the tag is
- DELETE rows where
- rows is the number of rows deleted.
-
-
- For an UPDATE command, the tag is
- UPDATE rows where
- rows is the number of rows updated.
-
-
- For a SELECT or CREATE TABLE AS
- command, the tag is SELECT rows
- where rows is the number of rows retrieved.
-
-
- For a MOVE command, the tag is
- MOVE rows where
- rows is the number of rows the
- cursor's position has been changed by.
-
-
- For a FETCH command, the tag is
- FETCH rows where
- rows is the number of rows that
- have been retrieved from the cursor.
-
-
- For a COPY command, the tag is
- COPY rows where
- rows is the number of rows copied.
- (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
- linkend="errcodes-appendix"/>). 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.
-
-
-
-
-
-
-
-
-
-
-
+ 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.
+
-
-
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.
-
+ 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.
+
+
projects / postgresql.git / commitdiff