9.3 9.4 9.5 9.6 10 11 12 13 14 15 16 17 Current(18)
PostgreSQL中文社区 问题报告 纠错本页面

54.7. 消息格式 #

本节描述每个消息的详细格式。每个消息都有标记以指示它可以由前端(F)、后端(B)或两者(F & B)发送。 请注意,尽管每个消息在开头包含字节计数,但大多数消息的定义使得可以在不参考字节计数的情况下找到消息结束。 这是出于历史原因,因为原始的、现已过时的协议版本 2 没有显式的长度字段。这也有助于有效性检查。

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

目标门户的名称(空字符串选择未命名的门户)。

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。

Byten

目标后端的密钥。该字段延伸到消息的末尾,由长度字段指示。最大密钥长度为 256 字节。

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

Close (F) #
Byte1('C')

将消息标识为关闭命令。

Int32

消息内容的长度(以字节为单位),包括自身。

Byte1

'S' 用于关闭一个准备好的语句;或者 'P' 用于关闭一个门户。

String

要关闭的预处理语句或门户的名称(空字符串选择未命名的预处理语句 或门户)。

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 是插入、更新或删除的行数。

对于 SELECTCREATE 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表示NULL列值。在NULL情况下,不跟随任何值字节。

Byten

列的值,格式由相关的格式代码指示。 n是上述长度。

Describe (F) #
Byte1('D')

标识消息为 Describe 命令。

Int32

消息内容的长度(以字节为单位),包括自身。

Byte1

'S'用于描述一个准备好的语句;或者 'P'用于描述一个门户。

String

要描述的准备好的语句或门户的名称(空字符串选择未命名的准备好的语句 或门户)。

EmptyQueryResponse (B) #
Byte1('I')

将消息标识为对空查询字符串的响应。(这相当于CommandComplete。)

Int32(4)

消息内容的长度(以字节为单位),包括其自身。

ErrorResponse (B) #
Byte1('E')

将消息标识为错误。

Int32

消息内容的长度(以字节为单位),包括其自身。

消息正文由一个或多个已识别的字段组成,后跟一个零字节作为终止符。字段可以以任何顺序出现。对于每个字段,都有以下内容:

Byte1

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

String

字段值。

Execute (F) #
Byte1('E')

标识消息为执行命令。

Int32

消息内容的长度(以字节为单位),包括自身。

String

要执行的门户的名称(空字符串选择未命名的门户)。

Int32

返回的最大行数,如果门户包含返回行的查询(否则忽略)。零表示没有限制

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

从通知进程传递的payload字符串。

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')

标识消息为门户暂停指示器。 请注意,仅当执行消息的行数限制达到时才会出现此消息。

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(196610)

协议版本号。最重要的 16 位是主要版本号(此处协议的版本为 3)。 最不重要的 16 位是次要版本号(此处协议的版本为 2)。

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

String

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

user

要连接的数据库用户名称。必填项;没有默认值。

database

要连接的数据库。默认为用户名。

options

后端的命令行参数。(已弃用,建议设置单独的运行时参数。)此字符串中的空格被视为分隔参数,除非用反斜杠(\)转义;写\\表示字面反斜杠。

replication

用于以流式复制模式连接,可以发出一小组复制命令而不是SQL语句。值可以是truefalsedatabase,默认为false。详细信息请参见第 54.4 节

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

String

参数值。

Sync (F) #
Byte1('S')

将消息标识为同步命令。

Int32(4)

消息内容的长度(以字节为单位),包括其自身。

Terminate (F) #
Byte1('X')

标识消息为终止。

Int32(4)

消息内容的长度(以字节为单位),包括自身。