52.7. 消息格式 #
本节描述每条消息的详细格式。每条消息都标明它可以由前端(F)、后端(B)或双方(F & B)发送。注意,虽然每条消息开头都有字节计数,但消息格式的定义使得无需参考该计数也能确定消息的结束位置。这有助于检查消息的有效性。(CopyData 消息是例外,因为它构成数据流的一部分,任何单条 CopyData 消息的内容都无法独立解释。)
- 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 数据。
- Byte
n GSSAPI 或 SSPI 认证数据。
- AuthenticationSASL (B)
- Byte1('R')
将该消息标识为认证请求。
- Int32
消息内容的长度(以字节为单位),包括其自身。
- Int32(10)
表示需要 SASL 认证。
消息体是按服务器偏好顺序排列的 SASL 认证机制列表。在最后一个认证机制名称之后,必须有一个零字节作为终止符。每个机制包含以下内容:
- String
SASL 认证机制的名称。
- AuthenticationSASLContinue (B)
- Byte1('R')
将该消息标识为认证请求。
- Int32
消息内容的长度(以字节为单位),包括其自身。
- Int32(11)
表示此消息包含 SASL 挑战。
- Byte
n SASL 数据,具体内容取决于所使用的 SASL 机制。
- AuthenticationSASLFinal (B)
- Byte1('R')
将该消息标识为认证请求。
- Int32
消息内容的长度(以字节为单位),包括其自身。
- Int32(12)
表示 SASL 认证已完成。
- Byte
n SASL 结果的“附加数据”,具体内容取决于所使用的 SASL 机制。
- 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 时,后面不再有值的字节。
- Byte
n 参数值,格式由对应的格式代码指明。
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,其中oidrowsrows是插入的行数。如果rows为 1 且目标表具有 OID,则oid是插入行的对象 ID;否则oid为 0。对于
DELETE命令,标签是DELETE,其中rowsrows表示删除的行数。对于
UPDATE命令,标签是UPDATE,其中rowsrows是更新的行数。对于
SELECT或CREATE TABLE AS命令,标签是SELECT,其中rowsrows是检索到的行数。对于
MOVE命令,标签是MOVE,其中rowsrows表示游标位置改变的行数。对于
FETCH命令,标签是FETCH,其中rowsrows是从游标中检索出的行数。对于
COPY命令,标签为COPY,其中rowsrows是复制的行数。(注意:行数仅出现在 PostgreSQL 8.2 及更高版本中。)
- CopyData (F & B)
- Byte1('d')
标识消息为
COPY数据。- Int32
消息内容的长度(以字节为单位),包括其自身。
- Byte
n 数据是
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 时,后面不再有值的字节。
- Byte
n 列的值,格式由相关的格式代码指示。
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
一个用于标识字段类型的代码;如果为零,则这是消息终止符,后面没有字符串。目前定义的字段类型列在第 52.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 时,后面不再有值的字节。
- Byte
n 参数的值,以相关格式代码指示的格式表示。
n是上述长度。
最后一个参数之后还有以下字段:
- Int16
函数结果的格式代码。目前必须为零(文本)或一(二进制)。
- FunctionCallResponse (B)
- Byte1('V')
标识消息为函数调用结果。
- Int32
消息内容的长度(以字节为单位),包括其自身。
- Int32
函数结果值的长度,以字节为单位(不包括此长度字段本身)。可以为零。特殊值 -1 表示 NULL 函数结果。为 NULL 时,后面不再有值的字节。
- Byte
n 函数结果的值,格式由相关的格式代码指示。
n是上述长度。
- GSSResponse (F)
- Byte1('p')
标识消息为 GSSAPI 或 SSPI 响应。请注意,这也用于 SASL 和密码响应消息。可以从上下文中推断出确切的消息类型。
- Int32
消息内容的长度(以字节为单位),包括其自身。
- Byte
n GSSAPI/SSPI 特定的消息数据。
- NegotiateProtocolVersion (B)
- Byte1('v')
标识消息为协议版本协商消息。
- Int32
消息内容的长度(以字节为单位),包括其自身。
- Int32
对于客户端请求的协议主版本,服务器所支持的最新协议次版本。
- Int32
服务器无法识别的协议选项数量。
接下来,对于服务器无法识别的每个协议选项,都有以下内容:
- String
选项名称。
- NoData (B)
- Byte1('n')
将消息标识为无数据指示器。
- Int32(4)
消息内容的长度(以字节为单位),包括其自身。
- NoticeResponse (B)
- Byte1('N')
将消息标识为通知。
- Int32
消息内容的长度(以字节为单位),包括其自身。
消息体由一个或多个带标识的字段组成,最后以一个零字节终止。字段可以按任意顺序出现。每个字段包含以下内容:
- Byte1
一个用于标识字段类型的代码;如果为零,则这是消息终止符,后面没有字符串。目前定义的字段类型列在第 52.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。
- Byte
n SASL 机制特定的“初始响应”。
- SASLResponse (F)
- Byte1('p')
标识消息为 SASL 响应。请注意,这也用于 GSSAPI、SSPI 和密码响应消息。可以从上下文中推断出确切的消息类型。
- Int32
消息内容的长度(以字节为单位),包括其自身。
- Byte
n SASL 机制特定的消息数据。
- 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 后端的命令行参数。(已弃用,建议设置单独的运行时参数。)此字符串中的空格被视为分隔参数,除非用反斜杠(
\)转义;写\\表示字面反斜杠。-
replication 用于以流复制模式连接,可以发出一小组复制命令而不是 SQL 语句。值可以是
true、false或database,默认为false。详细信息请参见第 52.4 节。
除上述参数外,还可以列出其他参数。以
_pq_.开头的参数名称保留用于协议扩展,其余参数则作为运行时参数,在后端启动时设置。这些设置会在后端启动期间应用(在解析命令行参数之后,如果有的话),并作为会话默认值。-
- String
参数值。
- Sync (F)
- Byte1('S')
将该消息标识为 Sync 命令。
- Int32(4)
消息内容的长度(以字节为单位),包括其自身。
- Terminate (F)
- Byte1('X')
标识消息为终止。
- Int32(4)
消息内容的长度(以字节为单位),包括其自身。