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