52.7. 邮件格式

本节描述每条消息的详细格式。每个标记都表示可以通过前端(F)，后端(B)或同时通过两者(F＆B)发送。请注意，尽管每个消息的开头都包含一个字节数，但是定义了消息格式，以便可以在不参考字节数的情况下找到消息结尾。这有助于有效性检查。 (CopyData 消息是一个 exception，因为它构成数据流的一部分；任何单独的 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 认证。

消息正文按服务器的优先 Sequences 列出了 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
  - 此后端的 Secret 密钥。
Bind (F)
- - Byte1('B')
  - 将消息标识为绑定命令。
- Int32
  - 消息内容的长度(以字节为单位)，包括自身。
- String
  - 目标门户的名称(空字符串将选择未命名的门户)。
- String
  - 源预准备语句的名称(空字符串将选择未命名的预准备语句)。
- Int16
  - 紧随其后的参数格式代码的数量(以下用* C *表示)。可以为零表示没有参数，或者这些参数全部使用默认格式(文本)。或一种，在这种情况下，将指定的格式代码应用于所有参数；或者它可以等于参数的实际数量。
- Int16[ C ]
  - 参数格式代码。每个当前必须为零(文本)或一个(二进制)。
- Int16
  - 紧随其后的参数值的数量(可能为零)。这必须与查询所需的参数数量匹配。

接下来，为每个参数显示以下字段对：

Int32
- 参数值的长度，以字节为单位(此计数不包括其自身)。可以为零。作为特殊情况，-1 表示参数值为 NULL。在 NULL 情况下，没有值字节。
- Byte n
  - 参数值，以相关格式代码指示的格式。 * n *为上述长度。

在最后一个参数之后，将显示以下字段：

Int16
- 紧随其后的结果列格式代码的数量(以下用* R *表示)。可以为零，以表示没有结果列，或者结果列都应使用默认格式(文本)；或一个，在这种情况下，将指定的格式代码应用于所有结果列(如果有)；或者可以等于查询的实际结果列数。
- Int16[ R ]
  - 结果列格式代码。每个当前必须为零(文本)或一个(二进制)。
BindComplete (B)
- - Byte1('2')
  - 将消息标识为绑定完成指示符。
- Int32(4)
  - 消息内容的长度(以字节为单位)，包括自身。
CancelRequest (F)
- - Int32(16)
  - 消息内容的长度(以字节为单位)，包括自身。
- Int32(80877102)
  - 取消请求代码。该值选择为在最高有效 16 位中包含1234，在最低有效 16 位中包含5678。 (为避免混淆，此代码不得与任何协议版本号相同.)
- Int32
  - 目标后端的进程 ID。
- Int32
  - 目标后端的 Secret 密钥。
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 *是插入的行数。 * oid 是插入行的对象 ID，如果 rows 为 1 并且目标表具有 OID；否则 oid *为 0.

对于DELETE命令，标记为DELETE rows，其中* rows *是已删除的行数。

对于UPDATE命令，标记为UPDATE rows，其中* rows *是更新的行数。

对于SELECT或CREATE 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
  - 消息内容的长度(以字节为单位)，包括自身。
- Byte n
  - 构成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 情况下，没有值字节。
- Byte n
  - 列的值，采用相关格式代码指示的格式。 * n *为上述长度。
Describe (F)
- - Byte1('D')
  - 将消息标识为“描述”命令。
- Int32
  - 消息内容的长度(以字节为单位)，包括自身。
- Byte1
  - 'S'描述准备好的 Statements；或“ P”来描述门户。
- String
  - 要描述的准备好的语句或门户的名称(空字符串将选择未命名的准备好的语句或门户)。
EmptyQueryResponse (B)
- - Byte1('I')
  - 将消息标识为对空查询字符串的响应。 (这代替 CommandComplete.)
- Int32(4)
  - 消息内容的长度(以字节为单位)，包括自身。
ErrorResponse (B)
- - Byte1('E')
  - 将消息标识为错误。
- Int32
  - 消息内容的长度(以字节为单位)，包括自身。

邮件正文由一个或多个标识的字段组成，后跟一个零字节作为终止符。字段可以按任何 Sequences 出现。对于每个字段，都有以下内容：

Byte1
- 标识字段类型的代码；如果为零，则为消息终止符，并且不跟随任何字符串。当前定义的字段类型在Section 52.8中列出。由于将来可能会添加更多字段类型，因此前端应静默忽略无法识别类型的字段。
- String
  - 字段值。
Execute (F)
- - Byte1('E')
  - 将消息标识为执行命令。
- Int32
  - 消息内容的长度(以字节为单位)，包括自身。
- String
  - 要执行的门户网站的名称(空字符串将选择未命名的门户网站)。
- Int32
  - 如果门户网站包含返回行的查询，则返回的最大行数(否则忽略)。零表示“无限制”。
Flush (F)
- - Byte1('H')
  - 将消息标识为“刷新”命令。
- 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
  - 服务器支持 Client 端请求的主要协议版本的最新次要协议版本。
- Int32
  - 服务器无法识别的协议选项数。

然后，对于服务器无法识别的协议选项，有以下内容：

String
- 选项名称。
NoData (B)
- - Byte1('n')
  - 将消息标识为无数据指示符。
- Int32(4)
  - 消息内容的长度(以字节为单位)，包括自身。
NoticeResponse (B)
- - Byte1('N')
  - 将消息标识为通知。
- Int32
  - 消息内容的长度(以字节为单位)，包括自身。

邮件正文由一个或多个标识的字段组成，后跟一个零字节作为终止符。字段可以按任何 Sequences 出现。对于每个字段，都有以下内容：

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')
  - 将消息标识为门户网站挂起的指示器。请注意，仅在达到执行消息的行数限制时才会显示。
- Int32(4)
  - 消息内容的长度(以字节为单位)，包括自身。
Query (F)
- - Byte1('Q')
  - 将消息标识为简单查询。
- Int32
  - 消息内容的长度(以字节为单位)，包括自身。
- String
  - 查询字符串本身。
ReadyForQuery (B)
- - Byte1('Z')
  - 标识消息类型。每当后端准备好进行新的查询周期时，就会发送 ReadyForQuery。
- Int32(5)
  - 消息内容的长度(以字节为单位)，包括自身。
- Byte1
  - 当前后端 Transaction 状态指示器。如果空闲(不在事务块中)，则可能的值为“ I”； 'T'，如果在 Transaction 区块中；或'E'(如果在失败的事务块中)(查询将被拒绝，直到该块结束)。
RowDescription (B)
- - Byte1('T')
  - 将消息标识为行描述。
- Int32
  - 消息内容的长度(以字节为单位)，包括自身。
- Int16
  - 指定一行中的字段数(可以为零)。

然后，对于每个字段，都有以下内容：

String
- 字段名称。
- Int32
  - 如果可以将该字段标识为特定表的列，则为该表的对象 ID；否则为 false。否则为零。
- Int16
  - 如果该字段可以标识为特定表的一列，则该列的属性号；否则，为 0.否则为零。
- Int32
  - 字段数据类型的对象 ID。
- Int16
  - 数据类型的大小(请参见pg_type.typlen)。请注意，负值表示宽度可变的类型。
- Int32
  - 类型修饰符(请参阅pg_attribute.atttypmod)。修饰符的含义是特定于类型的。
- Int16
  - 用于该字段的格式代码。当前将为零(文本)或一(二进制)。在从 Describe 语句变体返回的 RowDescription 中，格式代码尚不知道，并且始终为零。
SASLInitialResponse (F)
- - Byte1('p')
  - 将消息标识为初始 SASL 响应。请注意，这也用于 GSSAPI，SSPI 和密码响应消息。确切的消息类型是从上下文推导出来的。
- Int32
  - 消息内容的长度(以字节为单位)，包括自身。
- String
  - Client 端选择的 SASL 认证机制的名称。
- Int32
  - 随后的特定于 SASL 机制的“初始 Client 端响应”的长度；如果没有初始响应，则为-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)。

协议版本号后跟一对或多对参数名称和值字符串。在姓/值对之后，需要一个零字节作为终止符。参数可以以任何 Sequences 出现。 user是必需的，其他是可选的。每个参数指定为：

String
- 参数名称。当前公认的名称是：
user
```
 - The database user name to connect as\. Required; there is no default\.
```
- database
  - 要连接的数据库。默认为用户名。
- options
  - 后端的命令行参数。 (不建议使用设置单个运行时参数.)此字符串中的空格被视为用于分隔参数，除非使用反斜杠(\)进行转义。写\\代表 Literals 反斜杠。
- replication
  - 用于以流复制模式进行连接，在该模式下，可以发出一小组复制命令而不是 SQL 语句。值可以是true，false或database，默认值为false。有关详情，请参见Section 52.4。

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

String
- 参数值。
Sync (F)
- - Byte1('S')
  - 将消息标识为同步命令。
- Int32(4)
  - 消息内容的长度(以字节为单位)，包括自身。
Terminate (F)
- - Byte1('X')
  - 将消息标识为终止。
- Int32(4)
  - 消息内容的长度(以字节为单位)，包括自身。

PostgreSQL 中文文档

52.7. 邮件格式