PostgreSQL 19 文档 · 54.7. 消息格式

文档 → PostgreSQL 19

受支持版本：当前版本 (18) / 17 / 16 / 15 / 14

测试与开发版本： 19 / devel

不受支持的版本： 13 / 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2 / 7.1

测试版PostgreSQL 19 Beta 4 尚未正式发布，内容与行为在正式发布前可能变化。正式内容请看当前版本。

54.7. 消息格式
上一页	上一级	第 54 章前端/后端协议	起始页	下一页

54.7. 消息格式 #

本节描述每条消息的详细格式。每条消息都标记了可由前端（F）、后端（B）或双方（F&B）发送。请注意，虽然每条消息开头都带有字节计数，但大多数消息格式都定义为无需参考该计数也能确定消息边界。这一设计最初是出于历史原因（早期已废弃的协议 v2 没有显式长度字段），同时也有助于有效性校验。

AuthenticationOk (B) #

Byte1('R') #: 将该消息标识为认证请求。
Int32(8) #: 消息内容的长度（以字节为单位），包括其自身。
Int32(0) #: 表示认证成功。

AuthenticationKerberosV5 (B) #

Byte1('R') #: 将该消息标识为认证请求。
Int32(8) #: 消息内容的长度（以字节为单位），包括其自身。
Int32(2) #: 表示需要 Kerberos V5 认证。

AuthenticationCleartextPassword (B) #

Byte1('R') #: 将该消息标识为认证请求。
Int32(8) #: 消息内容的长度（以字节为单位），包括其自身。
Int32(3) #: 表示需要明文密码。

AuthenticationMD5Password (B) #

Byte1('R') #: 将该消息标识为认证请求。
Int32(12) #: 消息内容的长度（以字节为单位），包括其自身。
Int32(5) #: 表示需要经过 MD5 加密的密码。
Byte4 #: 加密密码时使用的盐。

AuthenticationGSS (B) #

Byte1('R') #: 将该消息标识为认证请求。
Int32(8) #: 消息内容的长度（以字节为单位），包括其自身。
Int32(7) #: 表示需要 GSSAPI 认证。

AuthenticationGSSContinue (B) #

Byte1('R') #: 将该消息标识为认证请求。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Int32(8) #: 表示此消息包含 GSSAPI 或 SSPI 数据。
Byten #: GSSAPI 或 SSPI 认证数据。

AuthenticationSSPI (B) #

Byte1('R') #: 将该消息标识为认证请求。
Int32(8) #: 消息内容的长度（以字节为单位），包括其自身。
Int32(9) #: 表示需要 SSPI 认证。

AuthenticationSASL (B) #

Byte1('R') #: 将该消息标识为认证请求。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Int32(10) #: 表示需要 SASL 认证。

消息体是按服务器偏好顺序排列的 SASL 认证机制列表。在最后一个认证机制名称之后，必须有一个零字节作为终止符。每个机制包含以下内容：

String #: SASL 认证机制的名称。

AuthenticationSASLContinue (B) #

Byte1('R') #: 将该消息标识为认证请求。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Int32(11) #: 表示此消息包含 SASL 挑战。
Byten #: SASL 数据，具体内容取决于所使用的 SASL 机制。

AuthenticationSASLFinal (B) #

Byte1('R') #: 将该消息标识为认证请求。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Int32(12) #: 表示 SASL 认证已完成。
Byten #: SASL 结果的“附加数据”，具体内容取决于所使用的 SASL 机制。

BackendKeyData (B) #

Byte1('K') #

将此消息标识为取消请求密钥数据。如果前端希望以后能够发送 CancelRequest 消息，就必须保存这些值。

Int32 #

消息内容的长度（以字节为单位），包括其自身。

Int32 #

此后端的进程 ID。

Byten #

此后端的密钥。此字段延伸至消息末尾，其范围由长度字段确定。

密钥长度最小为 4 字节，最大为 256 字节。PostgreSQL 服务器只发送最长 32 字节的密钥，但更大的长度上限允许未来的服务器版本、连接池和其他中间件使用更长的密钥。一种可能的用途是在服务器密钥中附加额外信息。因此，也建议中间件不要用尽所有字节，以便多层中间件叠加时，每一层都可以在密钥外再附加数据。

在协议版本 3.2 之前，密钥始终为 4 字节长。

Bind (F) #

Byte1('B') #: 将该消息标识为 Bind 命令。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
String #: 目标 portal 的名称（空字符串选择未命名的 portal）。
String #: 源预备语句的名称（空字符串选择未命名的预备语句）。
Int16 #: 后续参数格式代码的数量（下文以 C 表示）。可以为零，表示没有参数，或者所有参数都使用默认格式（文本）；也可以为一，此时指定的格式代码应用于所有参数；还可以等于实际参数数量。
Int16[C] #: 参数格式代码。目前每个格式代码必须为零（文本）或一（二进制）。
Int16 #: 后续参数值的数量（可以为零）。必须与查询所需的参数数量一致。

接下来，每个参数都有以下一对字段：

Int32 #: 参数值的长度，以字节为单位（不包括此长度字段本身）。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时，后面不再有值的字节。
Byten #: 参数值，格式由对应的格式代码指明。n 为上述长度。

最后一个参数之后是以下字段：

Int16 #: 后续结果列格式代码的数量（下文以 R 表示）。可以为零，表示没有结果列，或者所有结果列都应使用默认格式（文本）；也可以为一，此时指定的格式代码应用于所有结果列（如果有）；还可以等于查询实际的结果列数量。
Int16[R] #: 结果列格式代码。目前每个格式代码必须为零（文本）或一（二进制）。

BindComplete (B) #

Byte1('2') #: 将该消息标识为 Bind 完成指示。
Int32(4) #: 消息内容的长度（以字节为单位），包括其自身。

CancelRequest (F) #

Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Int32(80877102) #: 取消请求代码。此值的最高 16 位为 1234，最低 16 位为 5678。（为避免混淆，此代码不能与任何协议版本号相同。）
Int32 #: 目标后端的进程 ID。
Byten #: 目标后端的密钥。此字段延伸至消息末尾，其范围由长度字段确定。密钥最长为 256 字节。

在协议版本 3.2 之前，密钥始终为 4 字节长。

Close (F) #

Byte1('C') #: 将该消息标识为 Close 命令。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Byte1 #: “S”表示关闭预备语句；“P”表示关闭 portal。
String #: 要关闭的预备语句或 portal 的名称（空字符串选择未命名的预备语句或 portal）。

CloseComplete (B) #

Byte1('3') #: 将该消息标识为 Close 完成指示。
Int32(4) #: 消息内容的长度（以字节为单位），包括其自身。

CommandComplete (B) #

Byte1('C') #

将该消息标识为命令完成响应。

Int32 #

消息内容的长度（以字节为单位），包括其自身。

String #

命令标签。通常是一个单词，用来标识已完成的 SQL 命令。

对于 INSERT 命令，标签是 INSERT oid rows，其中 rows 是插入的行数。如果 rows 为 1 且目标表具有 OIDs，则 oid 曾经是插入行的对象 ID，但不再支持 OIDs 系统列；因此 oid 总是 0。

对于 DELETE 命令，标签是 DELETE rows，其中 rows 表示删除的行数。

对于 UPDATE 命令，标签是 UPDATE rows，其中 rows 是更新的行数。

对于 MERGE 命令，标签是 MERGE rows，其中 rows 是插入、更新或删除的行数。

对于 SELECT 或 CREATE TABLE AS 命令，标签是 SELECT rows，其中 rows 是检索到的行数。

对于 MOVE 命令，标签是 MOVE rows，其中 rows 表示游标位置改变的行数。

对于 FETCH 命令，标签是 FETCH rows，其中 rows 是从游标中检索出的行数。

对于 COPY 命令，标签为 COPY rows，其中 rows 是复制的行数。（注意：行数仅出现在 PostgreSQL 8.2 及更高版本中。）

CopyData (F & B) #

Byte1('d') #: 标识消息为 COPY 数据。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Byten #: 数据是 COPY 数据流的一部分。来自后端的消息始终对应单个数据行，但来自前端的消息可能会任意划分数据流。

CopyDone (F & B) #

Byte1('c') #: 将消息标识为 COPY 完成指示符。
Int32(4) #: 消息内容的长度（以字节为单位），包括其自身。

CopyFail (F) #

Byte1('f') #: 将消息标识为 COPY 失败指示器。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
String #: 作为失败原因报告的错误消息。

CopyInResponse (B) #

Byte1('G') #: 将该消息标识为开始 COPY 输入的响应。前端此时必须发送 COPY 输入数据（如果尚未准备好，应发送 CopyFail 消息）。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Int8 #: 0 表示整体 COPY 格式是文本的（行由换行符分隔，列由分隔符分隔等）。1 表示整体复制格式是二进制的（类似于 DataRow 格式）。更多信息请参见 COPY。
Int16 #: 要复制的数据中的列数（以下用 N 表示）。
Int16[N] #: 各列使用的格式代码。目前每个代码必须为零（文本）或一（二进制）。如果整体复制格式为文本，则所有代码都必须为零。

CopyOutResponse (B) #

Byte1('H') #: 将该消息标识为开始 COPY 输出的响应。此消息之后会发送 COPY 输出数据。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Int8 #: 0 表示整体 COPY 格式是文本的（行由换行符分隔，列由分隔符分隔等）。1 表示整体复制格式是二进制的（类似于 DataRow 格式）。更多信息请参见 COPY。
Int16 #: 要复制的数据中的列数（以下用 N 表示）。
Int16[N] #: 各列使用的格式代码。目前每个代码必须为零（文本）或一（二进制）。如果整体复制格式为文本，则所有代码都必须为零。

CopyBothResponse (B) #

Byte1('W') #: 将该消息标识为开始双向 COPY 的响应。此消息仅用于流复制。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Int8 #: 0 表示整体 COPY 格式是文本的（行由换行符分隔，列由分隔符分隔等）。1 表示整体复制格式是二进制的（类似于 DataRow 格式）。更多信息请参见 COPY。
Int16 #: 要复制的数据中的列数（以下用 N 表示）。
Int16[N] #: 各列使用的格式代码。目前每个代码必须为零（文本）或一（二进制）。如果整体复制格式为文本，则所有代码都必须为零。

DataRow (B) #

Byte1('D') #: 标识消息为数据行。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Int16 #: 后面跟着的列值的数量（可能为零）。

接下来，每列都有以下两个字段：

Int32 #: 列值的长度，以字节为单位（不包括此长度字段本身）。可以为零。特殊值 -1 表示 NULL 列值。为 NULL 时，后面不再有值的字节。
Byten #: 列的值，格式由相关的格式代码指示。n 是上述长度。

Describe (F) #

Byte1('D') #: 将该消息标识为 Describe 命令。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Byte1 #: 'S' 表示描述一个预备语句；或者 'P' 表示描述一个 portal。
String #: 要描述的预备语句或 portal 的名称（空字符串选择未命名的预备语句或 portal）。

EmptyQueryResponse (B) #

Byte1('I') #: 标识消息为对空查询字符串的响应。（此消息替代 CommandComplete。）
Int32(4) #: 消息内容的长度（以字节为单位），包括其自身。

ErrorResponse (B) #

Byte1('E') #: 将消息标识为错误。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。

消息体由一个或多个带标识的字段组成，最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容：

Byte1 #: 一个用于标识字段类型的代码；如果为零，则这是消息终止符，后面没有字符串。目前定义的字段类型列在第 54.8 节中。由于将来可能会添加更多的字段类型，前端应该静默地忽略未识别类型的字段。
String #: 字段值。

Execute (F) #

Byte1('E') #: 将该消息标识为 Execute 命令。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
String #: 要执行的 portal 的名称（空字符串选择未命名的 portal）。
Int32 #: 如果 portal 包含返回行的查询，则这是最多返回的行数（否则忽略此值）。零表示“无限制”。

Flush (F) #

Byte1('H') #: 将该消息标识为 Flush 命令。
Int32(4) #: 消息内容的长度（以字节为单位），包括其自身。

FunctionCall (F) #

Byte1('F') #: 标识消息为函数调用。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Int32 #: 指定要调用的函数的对象 ID。
Int16 #: 后续参数格式代码的数量（以下用 C 表示）。可以为零，表示没有参数，或所有参数都采用默认格式（文本）；也可以为一，表示将指定的格式代码用于所有参数；还可以等于实际参数数量。
Int16[C] #: 参数格式代码。每个目前必须是零（文本）或一（二进制）。
Int16 #: 指定传递给函数的参数数量。

接下来，每个参数都有以下两个字段：

Int32 #: 参数值的长度，以字节为单位（不包括此长度字段本身）。可以为零。特殊值 -1 表示 NULL 参数值。为 NULL 时，后面不再有值的字节。
Byten #: 参数的值，以相关格式代码指示的格式表示。n 是上述长度。

最后一个参数之后还有以下字段：

Int16 #: 函数结果的格式代码。目前必须为零（文本）或一（二进制）。

FunctionCallResponse (B) #

Byte1('V') #: 标识消息为函数调用结果。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Int32 #: 函数结果值的长度，以字节为单位（不包括此长度字段本身）。可以为零。特殊值 -1 表示 NULL 函数结果。为 NULL 时，后面不再有值的字节。
Byten #: 函数结果的值，格式由相关的格式代码指示。n 是上述长度。

GSSENCRequest (F) #

Int32(8) #: 消息内容的长度（以字节为单位），包括其自身。
Int32(80877104) #: GSSAPI 加密请求代码。此值的最高 16 位为 1234，最低 16 位为 5680。（为避免混淆，此代码不得与任何协议版本号相同。）

GSSResponse (F) #

Byte1('p') #: 标识消息为 GSSAPI 或 SSPI 响应。请注意，这也用于 SASL 和密码响应消息。可以从上下文中推断出确切的消息类型。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Byten #: GSSAPI/SSPI 特定的消息数据。

NegotiateProtocolVersion (B) #

Byte1('v') #: 标识消息为协议版本协商消息。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Int32 #: 对于客户端请求的协议主版本，服务器所支持的最新协议次版本。
Int32 #: 服务器无法识别的协议选项数量。

接下来，对于服务器无法识别的每个协议选项，都有以下内容：

String #: 选项名称。

NoData (B) #

Byte1('n') #: 将消息标识为无数据指示器。
Int32(4) #: 消息内容的长度（以字节为单位），包括其自身。

NoticeResponse (B) #

Byte1('N') #: 将消息标识为通知。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。

消息体由一个或多个带标识的字段组成，最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容：

Byte1 #: 一个用于标识字段类型的代码；如果为零，则这是消息终止符，后面没有字符串。目前定义的字段类型列在第 54.8 节中。由于将来可能会添加更多的字段类型，前端应该静默地忽略未识别类型的字段。
String #: 字段值。

NotificationResponse (B) #

Byte1('A') #: 标识消息为通知响应。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Int32 #: 发出通知的后端进程的进程 ID。
String #: 发出该通知的通道名称。
String #: 通知进程传来的“有效载荷”字符串。

ParameterDescription (B) #

Byte1('t') #: 标识消息为参数描述。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Int16 #: 语句使用的参数数量（可以为零）。

接下来，每个参数都有以下内容：

Int32 #: 指定参数数据类型的对象 ID。

ParameterStatus (B) #

Byte1('S') #: 标识消息为运行时参数状态报告。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
String #: 所报告的运行时参数的名称。
String #: 参数的当前值。

Parse (F) #

Byte1('P') #: 将该消息标识为 Parse 命令。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
String #: 目标预备语句的名称（空字符串选择未命名的预备语句）。
String #: 要解析的查询字符串。
Int16 #: 指定的参数数据类型的数量（可以为零）。请注意，这不是查询字符串中可能出现的参数数量的指示，而是前端希望为其预先指定类型的参数数量。

接下来，每个参数都有以下内容：

Int32 #: 指定参数数据类型的对象 ID。此处填零等同于不指定类型。

ParseComplete (B) #

Byte1('1') #: 将该消息标识为 Parse 完成指示。
Int32(4) #: 消息内容的长度（以字节为单位），包括其自身。

PasswordMessage (F) #

Byte1('p') #: 标识消息为密码响应。请注意，这也用于 GSSAPI、SSPI 和 SASL 响应消息。可以从上下文中推断出确切的消息类型。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
String #: 密码（如果需要，已加密）。

PortalSuspended (B) #

Byte1('s') #: 将该消息标识为 portal 挂起指示。注意，仅当达到 Execute 消息指定的行数限制时，才会出现此消息。
Int32(4) #: 消息内容的长度（以字节为单位），包括其自身。

Query (F) #

Byte1('Q') #: 标识消息为简单查询。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
String #: 查询字符串本身。

ReadyForQuery (B) #

Byte1('Z') #: 标识消息类型。ReadyForQuery 在后端准备好进行新的查询周期时发送。
Int32(5) #: 消息内容的长度（以字节为单位），包括其自身。
Byte1 #: 当前后端事务状态指示器。可能的值为'I'，如果空闲（不在事务块中）；'T'，如果在事务块中；或'E'，如果在失败的事务块中（查询将被拒绝，直到块结束）。

RowDescription (B) #

Byte1('T') #: 标识消息为行描述。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Int16 #: 指定一行中的字段数量（可以为零）。

接下来，每个字段都有以下内容：

String #: 字段名称。
Int32 #: 如果能够确定该字段是某个特定表的列，则为该表的对象 ID；否则为零。
Int16 #: 如果能够确定该字段是某个特定表的列，则为该列的属性编号；否则为零。
Int32 #: 字段数据类型的对象 ID。
Int16 #: 数据类型大小（参见 pg_type.typlen）。注意，负值表示可变宽度类型。
Int32 #: 类型修饰符（参见 pg_attribute.atttypmod）。修饰符的含义是特定于类型的。
Int16 #: 字段所使用的格式代码。目前为零（文本）或一（二进制）。对于 Describe 针对预备语句的变体所返回的 RowDescription，格式代码尚未确定，始终为零。

SASLInitialResponse (F) #

Byte1('p') #: 标识消息为初始 SASL 响应。请注意，这也用于 GSSAPI、SSPI 和密码响应消息。精确的消息类型是从上下文中推断出来的。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
String #: 客户端选择的 SASL 认证机制的名称。
Int32 #: 后续 SASL 机制特有的“客户端初始响应”的长度；如果没有初始响应，则为 -1。
Byten #: SASL 机制特定的“初始响应”。

SASLResponse (F) #

Byte1('p') #: 标识消息为 SASL 响应。请注意，这也用于 GSSAPI、SSPI 和密码响应消息。可以从上下文中推断出确切的消息类型。
Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Byten #: SASL 机制特定的消息数据。

SSLRequest (F) #

Int32(8) #: 消息内容的长度（以字节为单位），包括其自身。
Int32(80877103) #: SSL 请求代码。该值被选择为在最高的 16 位中包含 1234，在最低的 16 位中包含 5679。（为避免混淆，此代码不得与任何协议版本号相同。）

StartupMessage (F) #

Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Int32 #: 协议版本号。高 16 位是主版本号。低 16 位是次版本号。例如，协议版本 3.2 在十进制中表示为 196610，在十六进制中则更清楚地表示为 0x00030002。

协议版本号之后是一个或多个参数名与参数值字符串对。最后一个名称/值对之后必须有一个零字节作为终止符。参数可以按任意顺序出现。其中，user 是必需的，其余均为可选。每个参数按以下方式指定：

String #

参数名称。目前能够识别的名称如下：

user #: 要连接的数据库用户名称。必填项；没有默认值。
database #: 要连接的数据库。默认为用户名。
options #: 后端的命令行参数。（已弃用，建议设置单独的运行时参数。）此字符串中的空格被视为分隔参数，除非用反斜杠（\）转义；写\\ 表示字面反斜杠。
replication #: 用于以流复制模式连接，可以发出一小组复制命令而不是 SQL 语句。值可以是 true、false 或 database，默认为 false。详细信息请参见第 54.4 节。

除上述之外，还可以列出其他参数。以_pq_.开头的参数名称保留用于协议扩展，而其他参数被视为后端启动时设置的运行时参数。这些设置将在后端启动时应用（在解析命令行参数后，如果有的话），并将作为会话默认值。

String #

参数值。

Sync (F) #

Byte1('S') #: 将该消息标识为 Sync 命令。
Int32(4) #: 消息内容的长度（以字节为单位），包括其自身。

Terminate (F) #

Byte1('X') #: 标识消息为终止。
Int32(4) #: 消息内容的长度（以字节为单位），包括其自身。

上一页	上一级	下一页
54.6. 消息数据类型	起始页	54.8. 错误和通知消息字段

提交更正

译文有误、术语不当或页面显示问题，请到译文仓库 pgsty/pgdoc 报告译文问题。英文原文本身的问题，请在当前版本的对应页面向上游反馈；上游会在正式发布前持续修订。