选择 打开 改范围 完整检索页
受支持版本: 当前版本 (18) / 17 / 16 / 15 / 14
开发版本: 19 / devel
不受支持的版本: 13 / 12 / 11 / 10
当前 PostgreSQL 版本不在支持生命周期内。
您可以参阅当前版本的对应页面,或其他在上面列出的活跃大版本。

52.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

加密密码时使用的盐。

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 认证数据。

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

此后端的密钥。

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是更新的行数。

对于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,此时后面没有值字节。

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 52.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 表示参数值为 NULL,此时后面没有值字节。

Byten

参数的值,以相关格式代码指示的格式表示。 n是上述长度。

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

Int16

函数结果的格式代码。目前必须为零(文本)或一(二进制)。

FunctionCallResponse (B)
Byte1('V')

标识消息为函数调用结果。

Int32

消息内容的长度,以字节为单位,包括此长度字段本身。

Int32

函数结果值的长度,以字节为单位(不包括本长度字段自身)。可以为零。特殊值 -1 表示函数结果为 NULL,此时后面没有值字节。

Byten

函数结果的值,格式由相关的格式代码指示。 n是上述长度。

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

将消息标识为解析命令。

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,格式代码尚未确定,始终为零。

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 位为次版本号(此处描述的协议为 0)。

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

String

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

user

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

database

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

options

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

replication

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

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

String

参数值。

Sync (F)
Byte1('S')

将消息标识为同步命令。

Int32(4)

消息内容的长度,以字节为单位,包括此长度字段本身。

Terminate (F)
Byte1('X')

标识消息为终止。

Int32(4)

消息内容的长度,以字节为单位,包括此长度字段本身。