本节描述每条消息的详细格式。每条消息都带有标记, 指明它可以由前端(F)、后端(B)或两者 (F & B)发送。 注意,尽管每条消息的开头都包含一个字节计数, 但大多数消息的定义方式使得无需参照字节计数 就能找到消息的末尾。这出于历史原因: 最初的、现已废弃的协议版本 2 没有显式的长度字段。 不过这也有助于有效性检查。
把该消息标识为一条认证请求。
消息内容的长度,以字节计,包括其自身。
指定认证已成功。
把该消息标识为一条认证请求。
消息内容的长度,以字节计,包括其自身。
指定需要 Kerberos V5 认证。
把该消息标识为一条认证请求。
消息内容的长度,以字节计,包括其自身。
指定需要一个明文口令。
把该消息标识为一条认证请求。
消息内容的长度,以字节计,包括其自身。
指定需要一个 MD5 加密的口令。
加密口令时要使用的盐值。
把该消息标识为一条认证请求。
消息内容的长度,以字节计,包括其自身。
指定需要 GSSAPI 认证。
把该消息标识为一条认证请求。
消息内容的长度,以字节计,包括其自身。
指定该消息包含 GSSAPI 或 SSPI 数据。
nGSSAPI 或 SSPI 认证数据。
把该消息标识为一条认证请求。
消息内容的长度,以字节计,包括其自身。
指定需要 SSPI 认证。
把该消息标识为一条认证请求。
消息内容的长度,以字节计,包括其自身。
指定需要 SASL 认证。
消息体是一个 SASL 认证机制的列表,按服务器的优先顺序排列。 在最后一个认证机制名之后需要一个零字节作为终止符。 对于每个机制,有如下内容:
一个 SASL 认证机制的名称。
把该消息标识为一条认证请求。
消息内容的长度,以字节计,包括其自身。
指定该消息包含一个 SASL 挑战。
nSASL 数据,特定于正在使用的 SASL 机制。
把该消息标识为一条认证请求。
消息内容的长度,以字节计,包括其自身。
指定 SASL 认证已完成。
nSASL 结果的“额外数据”,特定于正在使用的 SASL 机制。
把该消息标识为取消密钥数据。 如果前端希望以后能发出 CancelRequest 消息, 它必须保存这些值。
消息内容的长度,以字节计,包括其自身。
该后端的进程 ID。
n该后端的秘密密钥。该字段一直延伸到由长度字段指明的 消息末尾。
密钥长度的最小值和最大值分别是 4 和 256 字节。 PostgreSQL 服务器只发送最长 32 字节的密钥,但更大的最大尺寸允许未来的服务器版本 以及连接池和其他中间件使用更长的密钥。 一个可能的用例是在服务器的密钥上附加额外的信息。 因此也鼓励中间件不要把所有字节都用完, 以防多个中间件应用相互叠加,每一层都可能 用额外的数据包装该密钥。
在协议版本 3.2 之前,秘密密钥的长度总是 4 字节。
把该消息标识为一条 Bind 命令。
消息内容的长度,以字节计,包括其自身。
目标门户的名字 (空字符串选择未命名的门户)。
源预备语句的名字 (空字符串选择未命名的预备语句)。
后面跟着的参数格式代码的个数
(在下文中记作 C)。
它可以是零,表示没有参数或所有参数都使用默认格式(文本);
也可以是一,这时指定的格式代码会应用于所有参数;
或者它可以等于实际的参数个数。
C]参数格式代码。目前每个都必须是零(文本)或一(二进制)。
后面跟着的参数值的个数(可能为零)。 它必须与查询所需的参数个数一致。
接下来,每个参数都会出现下面这一对字段:
参数值的长度,以字节计(该计数不包含它自身)。 可以为零。作为一种特殊情况,-1 表示一个 NULL 参数值。 在 NULL 的情况下,后面没有值字节。
n
参数的值,采用关联格式代码所指示的格式。
n 就是上面的长度。
在最后一个参数之后,会出现以下字段:
后面跟着的结果列格式代码的个数
(在下文中记作 R)。
它可以是零,表示没有结果列或所有结果列都应使用默认格式
(文本);也可以是一,这时指定的格式代码会应用于
所有结果列(如果有);或者它可以等于该查询
实际的结果列个数。
R]结果列格式代码。目前每个都必须是零(文本)或一(二进制)。
把该消息标识为一条 Bind 完成指示。
消息内容的长度,以字节计,包括其自身。
消息内容的长度,以字节计,包括其自身。
取消请求代码。该值的选取使得最高 16 位包含
1234,最低 16 位包含
5678。(为避免混淆,
该代码不得与任何协议版本号相同。)
目标后端的进程 ID。
n目标后端的秘密密钥。该字段一直延伸到由长度字段指明的 消息末尾。密钥的最大长度是 256 字节。
在协议版本 3.2 之前,秘密密钥的长度总是 4 字节。
把该消息标识为一条 Close 命令。
消息内容的长度,以字节计,包括其自身。
'S' 表示关闭一条预备语句;
'P' 表示关闭一个门户。
要关闭的预备语句或门户的名字 (空字符串选择未命名的预备语句或门户)。
把该消息标识为一条 Close 完成指示。
消息内容的长度,以字节计,包括其自身。
把该消息标识为一条命令完成响应。
消息内容的长度,以字节计,包括其自身。
命令标签。这通常是一个单词, 标识完成的是哪条 SQL 命令。
对于 INSERT 命令,标签是
INSERT ,
其中 oid
rowsrows 是被插入的行数。
当 rows 为 1 且目标表带有 OID 时,
oid 过去表示被插入行的对象 ID,
但现在已经不再支持 OID 系统列;
因此 oid 总是 0。
对于 DELETE 命令,标签是
DELETE ,
其中 rowsrows 是被删除的行数。
对于 UPDATE 命令,标签是
UPDATE ,
其中 rowsrows 是被更新的行数。
对于 MERGE 命令,标签是
MERGE ,
其中 rowsrows 是被插入、更新
或删除的行数。
对于 SELECT 或
CREATE TABLE AS 命令,标签是
SELECT ,
其中 rowsrows 是被检索的行数。
对于 MOVE 命令,标签是
MOVE ,
其中 rowsrows 是游标位置
被移动的行数。
对于 FETCH 命令,标签是
FETCH ,
其中 rowsrows 是从游标中
检索到的行数。
对于 COPY 命令,标签是
COPY ,
其中 rowsrows 是被复制的行数。
(注意:行计数只在
PostgreSQL 8.2 及之后的版本中出现。)
把该消息标识为 COPY 数据。
消息内容的长度,以字节计,包括其自身。
n
构成 COPY 数据流一部分的数据。
从后端发送的消息总是对应于单个数据行,
但前端发送的消息可以任意划分数据流。
把该消息标识为一条 COPY 完成指示。
消息内容的长度,以字节计,包括其自身。
把该消息标识为一条 COPY 失败指示。
消息内容的长度,以字节计,包括其自身。
一条作为失败原因报告的错误消息。
把该消息标识为开始复制进入(Copy In)的响应。 前端现在必须发送复制进入数据 (如果没有准备好,则发送一条 CopyFail 消息)。
消息内容的长度,以字节计,包括其自身。
0 表示整体的 COPY 格式是文本格式
(行由换行分隔、列由分隔字符分隔等)。
1 表示整体的复制格式是二进制格式
(类似于 DataRow 格式)。
更多信息见 COPY。
要复制的数据中的列数
(在下文中记作 N)。
N]每列要使用的格式代码。 目前每个都必须是零(文本)或一(二进制)。 如果整体的复制格式是文本格式,则所有列都必须为零。
把该消息标识为开始复制传出(Copy Out)的响应。 这条消息之后将跟着复制传出的数据。
消息内容的长度,以字节计,包括其自身。
0 表示整体的 COPY 格式
是文本格式(行由换行分隔、列由分隔字符分隔等)。
1 表示整体的复制格式是二进制格式
(类似于 DataRow 格式)。
更多信息见 COPY。
要复制的数据中的列数
(在下文中记作 N)。
N]每列要使用的格式代码。 目前每个都必须是零(文本)或一(二进制)。 如果整体的复制格式是文本格式,则所有列都必须为零。
把该消息标识为开始双向复制(Copy Both)的响应。 这条消息只用于流复制。
消息内容的长度,以字节计,包括其自身。
0 表示整体的 COPY 格式
是文本格式(行由换行分隔、列由分隔字符分隔等)。
1 表示整体的复制格式是二进制格式
(类似于 DataRow 格式)。
更多信息见 COPY。
要复制的数据中的列数
(在下文中记作 N)。
N]每列要使用的格式代码。 目前每个都必须是零(文本)或一(二进制)。 如果整体的复制格式是文本格式,则所有列都必须为零。
把该消息标识为一条数据行。
消息内容的长度,以字节计,包括其自身。
后面跟着的列值的个数(可能为零)。
接下来,每一列都会出现下面这一对字段:
列值的长度,以字节计(该计数不包含它自身)。 可以为零。作为一种特殊情况,-1 表示一个 NULL 列值。 在 NULL 的情况下,后面没有值字节。
n
列的值,采用关联格式代码所指示的格式。
n 就是上面的长度。
把该消息标识为一条 Describe 命令。
消息内容的长度,以字节计,包括其自身。
'S' 表示描述一条预备语句;
'P' 表示描述一个门户。
要描述的预备语句或门户的名字 (空字符串选择未命名的预备语句或门户)。
把该消息标识为对一个空查询字符串的响应。 (它替代 CommandComplete。)
消息内容的长度,以字节计,包括其自身。
把该消息标识为一条错误。
消息内容的长度,以字节计,包括其自身。
消息体由一个或多个被标识的字段组成, 后跟一个作为终止符的零字节。字段可以以任何顺序出现。 对于每个字段,有如下内容:
一个标识字段类型的代码;如果为零, 则这是消息终止符,后面没有字符串。 目前已定义的字段类型列在 Section 54.8 中。 由于将来可能会增加更多字段类型, 前端应当静默忽略无法识别类型的字段。
The field value.
把该消息标识为一条 Execute 命令。
消息内容的长度,以字节计,包括其自身。
要执行的门户的名字 (空字符串选择未命名的门户)。
如果门户包含一个返回行的查询,则是要返回的最大行数 (否则忽略)。零表示“无限制”。
把该消息标识为一条 Flush 命令。
消息内容的长度,以字节计,包括其自身。
把该消息标识为一次函数调用。
消息内容的长度,以字节计,包括其自身。
指定要调用的函数的对象 ID。
后面跟着的参数格式代码的个数
(在下文中记作 C)。
它可以是零,表示没有参数或所有参数都使用默认格式(文本);
也可以是一,这时指定的格式代码会应用于所有参数;
或者它可以等于实际的参数个数。
C]参数格式代码。目前每个都必须是零(文本)或一(二进制)。
指定提供给函数的参数个数。
接下来,每个参数都会出现下面这一对字段:
参数值的长度,以字节计(该计数不包含它自身)。 可以为零。作为一种特殊情况,-1 表示一个 NULL 参数值。 在 NULL 的情况下,后面没有值字节。
n
参数的值,采用关联格式代码所指示的格式。
n 就是上面的长度。
在最后一个参数之后,会出现以下字段:
函数结果的格式代码。目前必须是零(文本)或一(二进制)。
把该消息标识为一次函数调用的结果。
消息内容的长度,以字节计,包括其自身。
函数结果值的长度,以字节计(该计数不包含它自身)。 可以为零。作为一种特殊情况,-1 表示一个 NULL 函数结果。 在 NULL 的情况下,后面没有值字节。
n
函数结果的值,采用关联格式代码所指示的格式。
n 就是上面的长度。
消息内容的长度,以字节计,包括其自身。
GSSAPI 加密请求代码。该值的选取使得
最高 16 位包含 1234,最低 16 位包含
5680。(为避免混淆,
该代码不得与任何协议版本号相同。)
把该消息标识为一条 GSSAPI 或 SSPI 响应。注意, 它也用于 SASL 和口令响应消息。 确切的消息类型可以从上下文推断。
消息内容的长度,以字节计,包括其自身。
nGSSAPI/SSPI 特有的消息数据。
把该消息标识为一条协议版本协商消息。
消息内容的长度,以字节计,包括其自身。
对于客户端请求的主协议版本,服务器支持的最新次协议版本。
服务器无法识别的协议选项的个数。
然后,对于服务器无法识别的每个协议选项,有如下内容:
The option name.
把该消息标识为一条无数据指示。
消息内容的长度,以字节计,包括其自身。
把该消息标识为一条通知。
消息内容的长度,以字节计,包括其自身。
消息体由一个或多个被标识的字段组成, 后跟一个作为终止符的零字节。字段可以以任何顺序出现。 对于每个字段,有如下内容:
一个标识字段类型的代码;如果为零, 则这是消息终止符,后面没有字符串。 目前已定义的字段类型列在 Section 54.8 中。 由于将来可能会增加更多字段类型, 前端应当静默忽略无法识别类型的字段。
The field value.
把该消息标识为一条通知响应。
消息内容的长度,以字节计,包括其自身。
发出通知的后端进程的进程 ID。
通知被引发的频道的名称。
由通知进程传入的“载荷”字符串。
把该消息标识为一条参数描述。
消息内容的长度,以字节计,包括其自身。
该语句使用的参数个数 (可以为零)。
然后,对每个参数有如下内容:
指定参数数据类型的对象 ID。
把该消息标识为一份运行时参数状态报告。
消息内容的长度,以字节计,包括其自身。
被报告的运行时参数的名称。
该参数的当前值。
把该消息标识为一条 Parse 命令。
消息内容的长度,以字节计,包括其自身。
目标准备语句的名字 (空字符串选择未命名的预备语句)。
要解析的查询字符串。
指定的参数数据类型的个数 (可以为零)。注意,这并不表示查询字符串中 可能出现的参数的个数,而只是前端想要 预先指定类型的参数的个数。
然后,对每个参数有如下内容:
指定参数数据类型的对象 ID。在这里放一个零 等价于不指定该类型。
把该消息标识为一条 Parse 完成指示。
消息内容的长度,以字节计,包括其自身。
把该消息标识为一条口令响应。注意, 它也用于 GSSAPI、SSPI 和 SASL 响应消息。 确切的消息类型可以从上下文推断。
消息内容的长度,以字节计,包括其自身。
口令(如果要求了则已加密)。
把该消息标识为一个门户挂起(portal-suspended)指示。 注意,只有在 Execute 消息的行数限制被达到时 才会出现这条消息。
消息内容的长度,以字节计,包括其自身。
把该消息标识为一条简单查询。
消息内容的长度,以字节计,包括其自身。
查询字符串本身。
标识消息类型。每当后端准备好接受一个新的查询周期时, 就会发送 ReadyForQuery。
消息内容的长度,以字节计,包括其自身。
当前后端事务状态指示器。可能的取值是:
'I' 表示空闲(不在事务块中);
'T' 表示在事务块中;
或 'E' 表示在一个失败的事务块中
(在块结束之前查询将被拒绝)。
把该消息标识为一条行描述。
消息内容的长度,以字节计,包括其自身。
指定一行中的字段个数(可以为零)。
然后,对每个字段有如下内容:
The field name.
如果该字段可以被标识为某个特定表的一列, 则是该表的对象 ID;否则为零。
如果该字段可以被标识为某个特定表的一列, 则是该列的属性编号;否则为零。
该字段数据类型的对象 ID。
数据类型大小(见 pg_type.typlen)。
注意,负值表示变宽类型。
类型修饰符(见 pg_attribute.atttypmod)。
修饰符的含义取决于具体的类型。
该字段使用的格式代码。目前将是零(文本)或一(二进制)。 在由 Describe 的语句变体返回的 RowDescription 中, 格式代码尚不可知,因此总是为零。
把该消息标识为一条初始 SASL 响应。注意, 它也用于 GSSAPI、SSPI 和口令响应消息。 确切的消息类型可以从上下文推断。
消息内容的长度,以字节计,包括其自身。
客户端选择的 SASL 认证机制的名称。
后面跟着的 SASL 机制相关的“初始客户端响应”的长度; 如果没有初始响应则为 -1。
nSASL 机制特有的“初始响应”。
把该消息标识为一条 SASL 响应。注意, 它也用于 GSSAPI、SSPI 和口令响应消息。 确切的消息类型可以从上下文推断。
消息内容的长度,以字节计,包括其自身。
nSASL 机制特有的消息数据。
消息内容的长度,以字节计,包括其自身。
SSL 请求代码。该值的选取使得
最高 16 位包含 1234,最低 16 位包含
5679。(为避免混淆,
该代码不得与任何协议版本号相同。)
消息内容的长度,以字节计,包括其自身。
协议版本号。最高 16 位是主版本号 (对这里描述的协议是 3)。 最低 16 位是次版本号 (对这里描述的协议是 2)。
协议版本号之后是一对或多对参数名和参数值字符串。
在最后一对名称/值之后需要一个零字节作为终止符。
参数可以以任何顺序出现。user 是必需的,
其他都是可选的。每个参数按如下方式指定:
参数名。目前可识别的名称有:
user要以其身份连接的数据库用户名。必需;没有默认值。
database要连接的数据库。默认为用户名。
options
后端的命令行参数。
(现已弃用,建议改为设置单个运行时参数。)
该字符串中的空格被视为参数分隔符,
除非用反斜线(\)转义;
写 \ 表示一个字面的反斜线。
replication
用于以流复制模式连接,
在这种模式下可以发出少量复制命令来代替 SQL 语句。
值可以是 true、false
或 database,默认值为
false。详情见
Section 54.4。
除上述内容之外,还可以列出其他参数。
以 _pq_. 开头的参数名
被保留用作协议扩展,而其他参数则被视为
要在后端启动时设置的运行时参数。
这些设置将在后端启动期间应用
(如果有的话,会在解析完命令行参数之后),
并作为会话默认值生效。
The parameter value.
把该消息标识为一条 Sync 命令。
消息内容的长度,以字节计,包括其自身。
把该消息标识为一次终止。
消息内容的长度,以字节计,包括其自身。