45.4. 消息格式 — PostgreSQL 8.4

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

开发中的版本： 19 / 20devel

已结束支持的版本： 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 8.4 已结束支持。请参阅当前版本手册.

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

45.4. 消息格式 #

本节描述每条消息的详细格式。每条消息都标记了可由前端（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: 加密密码时使用的盐。

AuthenticationSCMCredential (B)

Byte1('R'): 将该消息标识为认证请求。
Int32(8): 消息内容的长度，以字节为单位，包括此长度字段本身。
Int32(6): 表示需要 SCM 凭证消息。

AuthenticationGSS (B)

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

AuthenticationSSPI (B)

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

AuthenticationGSSContinue (B)

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

BackendKeyData (B)

Byte1('K'): 将此消息标识为取消请求密钥数据。如果前端希望以后能够发送 CancelRequest 消息，就必须保存这些值。
Int32(12): 消息内容的长度，以字节为单位，包括此长度字段本身。
Int32: 此后端的进程 ID。
Int32: 此后端的密钥。

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(16): 消息内容以字节计的长度，包括自身。
Int32(80877102): 取消请求代码。此值的最高 16 位为 1234，最低 16 位为 5678。（为避免混淆，此代码不能与任何协议版本号相同。）
Int32: 目标后端的进程 ID。
Int32: 目标后端的密钥。

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 且目标表具有 OID，则 oid 是插入行的对象 ID；否则 oid 为 0。

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

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

CopyOutResponse (B)

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

DataRow (B)

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

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

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

Describe (F)

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

EmptyQueryResponse (B)

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

ErrorResponse (B)

Byte1('E'): 将消息标识为错误。
Int32: 消息内容的长度，以字节为单位，包括此长度字段本身。

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

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

Execute (F)

Byte1('E'): 标识消息为一个执行命令。
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，此时后面没有值字节。
Byten: 参数的值，以相关格式代码指示的格式表示。n是上述长度。

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

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

FunctionCallResponse (B)

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

NoData (B)

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

NoticeResponse (B)

Byte1('N'): 将消息标识为通知。
Int32: 消息内容的长度，以字节为单位，包括此长度字段本身。

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

Byte1: 一个用于标识字段类型的代码；如果为零，则这是消息终止符，后面没有字符串。目前定义的字段类型列在第 45.5 节中。由于将来可能会添加更多的字段类型，前端应该静默地忽略未识别类型的字段。
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'): 将消息标识为解析命令。
Int32: 消息内容的长度，以字节为单位，包括此长度字段本身。
String: 目标预备语句的名称（空字符串选择未命名的预备语句）。
String: 要解析的查询字符串。
Int16: 指定的参数数据类型的数量（可以为零）。请注意，这不是查询字符串中可能出现的参数数量的指示，而是前端希望为其预先指定类型的参数数量。

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

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

ParseComplete (B)

Byte1('1'): 将消息标识为解析完成指示器。
Int32(4): 消息内容的长度，以字节为单位，包括此长度字段本身。

PasswordMessage (F)

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

PortalSuspended (B)

Byte1('s'): 标识消息为 portal 挂起指示器。请注意，仅当执行消息的行数限制达到时才会出现此消息。
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，格式代码尚未确定，始终为零。

SSLRequest (F)

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

StartupMessage (F)

Int32: 消息内容以字节计的长度，包括自身。
Int32(196608): 协议版本号。最高 16 位是协议主版本号（本文档描述的协议为 3）。最低 16 位是协议次版本号（本文档描述的协议为 0）。

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

String

参数名。目前可识别的名称有：

user: 要连接的数据库用户名。必需；没有默认值。
database: 要连接的数据库。默认为用户名。
options: 后端的命令行参数。（已弃用，建议设置单独的运行时参数。）

除上述参数外，还可以列出任何可在后端启动时设置的运行时参数。这些设置将在后端启动期间应用（如果有的话，在解析命令行选项之后）。这些值将作为会话默认值。

String

参数的值。

Sync (F)

Byte1('S'): 将消息标识为同步命令。
Int32(4): 消息内容的长度，以字节为单位，包括此长度字段本身。

Terminate (F)

Byte1('X'): 标识消息为终止。
Int32(4): 消息内容的长度，以字节为单位，包括此长度字段本身。

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

报告文档问题

阅读上游文档. 反馈更正前请先核对当前版本手册.