PostgreSQL: 文档：15：53.7. 消息格式

文档 → PostgreSQL 15

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

开发版本： devel

53.7. 消息格式
Prev	Up	Chapter 53. 前端/后端协议	Home	Next

53.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(12) #

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

Int32 #

这个后端的进程ID。

Int32 #

该后端的 secret key。该字段长度由消息总长度决定，并一直延伸到消息末尾。

key 的最小与最大长度分别为 4 和 256 字节。PostgreSQL 服务器当前发送不超过 32 字节的 key；更大的上限用于兼容未来版本及连接池/中间件使用更长 key 的需求。中间件也不宜用满全部字节，以便多层中间件叠加时仍可附加自身数据。

在协议 3.2 之前，secret key 固定为 4 字节。

Bind (F) #

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

接下来，对于每个参数，都会出现以下一对字段：

Int32 #: 参数值的长度，以字节为单位（此计数不包括自身）。可以为零。作为特殊情况，-1表示空参数值。在空参数值的情况下，不会跟随任何值字节。
Byten #: 参数的值，以相关格式代码指示的格式表示。 n是上述长度。

在最后一个参数之后，出现以下字段：

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

BindComplete (B) #

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

CancelRequest (F) #

Int32 #: 消息内容的长度（以字节为单位），包括其自身。
Int32(80877102) #: 取消请求代码。该值被选择为在最高的16位中包含1234，在最低的16位中包含5678。（为避免混淆，此代码不得与任何协议版本号相同。）
Int32 #: 目标后端的进程ID。
Int32 #: 目标后端的 secret key。该字段长度由消息总长度决定并延伸至消息末尾，最大长度为 256 字节。

在协议 3.2 之前，secret key 固定为 4 字节。

Close (F) #

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

CloseComplete (B) #

Byte1('3') #: 标识消息为关闭完成指示符。
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') #: 标识消息为开始复制响应。前端现在必须发送复制数据（如果没有准备好，发送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] #: 每列要使用的格式代码。每个必须目前为零（文本）或一（二进制）。如果整体复制格式为文本，则所有必须为零。

CopyBothResponse (B) #

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

DataRow (B) #

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

接下来，对于每一列，都会出现以下一对字段：

Int32 #: 列值的长度，以字节为单位（此计数不包括其本身）。可以为零。作为特殊情况，-1表示空列值。在空值情况下，不跟随任何值字节。
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 #: 一个用于标识字段类型的代码；如果为零，则这是消息终止符，后面没有字符串。目前定义的字段类型列在Section 53.8中。由于将来可能会添加更多的字段类型，前端应该静默地忽略未识别类型的字段。
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表示空参数值。在空参数值的情况下，不会跟随任何值字节。
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 #: 一个用于标识字段类型的代码；如果为零，则这是消息终止符，后面没有字符串。目前定义的字段类型列在Section 53.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') #: 将消息标识为解析命令。
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 #: 正在使用的字段格式代码。目前将为零（文本）或一（二进制）。在从描述语句变体返回的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(196608) #: 协议版本号。最重要的16位是主版本号（此处描述的协议为3）。最不重要的16位是次版本号（此处描述的协议为2）。

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

String #

参数名称。当前识别的名称包括：

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

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

String #

参数数值。

Sync (F) #

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

Terminate (F) #

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

Prev	Up	Next
53.6. 消息数据类型	Home	53.8. 错误和通知消息域

提交更正

如果您发现文档中有不正确的内容、与您使用特定功能的经验不符或需要进一步说明，请使用此表单来报告文档问题。