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

对于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

      • 消息内容的长度(以字节为单位),包括自身。
    • 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 语句。值可以是truefalsedatabase,默认值为false。有关详情,请参见Section 52.4

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

  • String

    • 参数值。
  • Sync (F)

      • Byte1('S')

      • 将消息标识为同步命令。

    • Int32(4)

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

      • Byte1('X')

      • 将消息标识为终止。

    • Int32(4)

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