48.5. 消息格式

本节描述各种消息的详细格式。 每种消息都标记为它是由一个前端(F)，一个后端(B)或者两者(F &B)发送的。 请注意，尽管每条消息在开头都包含一个字节计数，消息格式也定义为可以不用参考字节计数就可以找到消息的结尾。 这样就增加了有效性检查。CopyData 消息是一个例外，因为它形成一个数据流的一部分；任意独立的 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认证数据。

BackendKeyData (B)

Byte1('K')

标识该消息是一个取消键字数据。 如果前端希望能够在稍后发出 CancelRequest 消息，那么它必须保存这个值。

Int32(12)

以字节记的消息内容的长度，包括长度本身。

Int32

后端的进程号(PID)

Int32

此后端的密钥

Bind (F)

Byte1('B')

标识该消息是一个绑定命令

Int32

以字节记的消息内容的长度，包括长度本身。

String

目标入口的名字(空字符串则选取未命名的入口)

String

源预备语句的名字(空字符串则选取未命名的预备语句)

Int16

后面跟着的参数格式代码的数目(在下面的_C_中说明)。 这个数值可以是0，表示没有参数，或者是参数都使用缺省格式(文本)；或者是1，这种情况下声明的格式代码应用于所有参数；或者它可以等于实际数目的参数。

Int16[_C_]

参数格式代码。目前每个都必须是0(文本)或者1(二进制)。

Int16

后面跟着的参数值的数目(可能为零)。这些必须和查询需要的参数个数匹配。

然后，每个参数都会出现下面的字段对：

Int32

参数值的长度，以字节记(这个长度并不包含长度本身)。 可以为0。一个特殊的情况是，-1 表示一个 NULL 参数值。 在 NULL 的情况下，后面不会跟着数值字节。

Byte_n_

参数值，格式是用相关的格式代码表示的。_n_是上面的长度。

在最后一个参数之后，出现下面的字段：

Int16

后面跟着的结果字段格式代码数目(下面的_R_描述)。 这个数目可以是0表示没有结果字段，或者结果字段都使用缺省格式(文本)；或者是1，这种情况下声明格式代码应用于所有结果字段(如果有的话)；或者它可以等于查询的结果字段的实际数目。

Int16[_R_]

结果字段格式代码。目前每个必须是0(文本)或者1(二进制)。

BindComplete (B)

Byte1('2')

标识消息为一个绑定结束标识符

Int32(4)

以字节记的消息长度，包括长度本身。

CancelRequest (F)

Int32(16)

以字节记的消息长度，包括长度本身。

Int32(80877102)

取消请求代码。选这个值是为了在高 16 位包含1234 ，低 16 位包含5678。 （为避免混乱，这个代码必须与协议版本号不同。）

Int32

目标后端的进程号(PID)

Int32

目标后端的密钥

Close (F)

Byte1('C')

标识这条消息是一个 Close 命令。

Int32

以字节计的消息内容长度，包括长度本身。

Byte1

'S'关闭一个准备的语句；或者'P'关闭一个入口。

String

一个要关闭的预备语句或者入口的名字(一个空字符串选择未命名的预备语句或者入口)。

CloseComplete (B)

Byte1('3')

标识消息是一个 Close 完毕指示器。

Int32(4)

以字节记的消息内容的长度，包括长度本身。

CommandComplete (B)

Byte1('C')

标识此消息是一个命令结束响应。

Int32

以字节记的消息内容的长度，包括长度本身。

String

命令标记。它通常是一个单字，标识那个命令完成。

对于INSERT命令，标记是INSERT _oid_ _rows_，这里的_rows_是插入的行数。 _oid_在_rows_为1并且目标表有OID的时候是插入行的对象ID； 否则_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')

标识这条消息是一条 StartCopyIn(开始拷贝输入)响应消息。 前端现在必须发送一条拷贝入数据(如果还没准备好做这些事情，那么发送一条 CopyFail 消息)。

Int32

以字节记的消息内容的长度，包括长度本身。

Int8

0 表示全部的COPY格式都是文本的(数据行由换行符分隔，字段由分隔字符分隔等等)。 1 表示都是二进制的(类似 DataRow 格式)。参阅COPY获取更多信息。

Int16

数据中要拷贝的字段数(由下面的_N_解释)。

Int16[_N_]

每个字段将要使用的格式代码，目前每个都必须是0(文本)或者1(二进制)。 如果全部拷贝格式都是文本的，那么所有的都必须是0。

CopyOutResponse (B)

Byte1('H')

标识这条消息是一条 StartCopyOut(开始拷贝输出)响应消息。这条消息后面将跟着一条拷贝出数据消息。

Int32

以字节记的消息内容的长度，包括它自己。

Int8

0 表示全部COPY格式都是文本(数据行由换行符分隔，字段由分隔字符分隔等等)。 1 表示所有拷贝格式都是二进制的(类似于 DataRow 格式)。参阅COPY获取更多信息。

Int16

要拷贝的数据的字段的数目(在下面的_N_说明)。

Int16[_N_]

每个字段要使用的格式代码。目前每个都必须是0(文本)或者1(二进制)。 如果全部的拷贝格式都是文本，那么所有的都必须是0。

CopyBothResponse (B)

Byte1('W')

标识这条消息是一条 StartCopyBoth(开始双向拷贝)响应消息。 这个消息只会被流复制使用。

Int32

以字节记的消息内容的长度，包括它自己。

Int8

0 表示全部拷贝COPY格式都是文本(数据行由换行符分隔，字段由分隔字符分隔等等)。 1 表示所有拷贝格式都是二进制的(类似于 DataRow 格式)。参阅COPY获取更多信息。

Int16

数据中要拷贝的字段数(由下面的_N_解释)。

Int16[_N_]

每个字段要使用的格式代码。目前每个都必须是0(文本)或者1(二进制)。 如果全部的拷贝格式都是文本，那么所有的都必须是0。

DataRow (B)

Byte1('D')

标识这个消息是一个数据行。

Int32

以字节记的消息内容的长度，包括长度自身。

Int16

后面跟着的字段值的个数(可能是零)。

然后，每个字段都会出现下面的数据域对：

Int32

字段值的长度，以字节记(这个长度不包括它自己)。 可以为0。一个特殊的情况是，-1 表示一个 NULL 的字段值。在 NULL 的情况下就没有跟着数据字段。

Byte_n_

一个字段的数值，以相关的格式代码表示的格式展现。_n_是上面的长度。

Describe (F)

Byte1('D')

标识消息是一个 Describe命令。

Int32

以字节记的消息内容的长度，包括字节本身。

Byte1

'S'描述一个预备语句；或者'P'描述一个入口。

String

要描述的预备语句或者入口的名字(或者一个空字符串，就会选取未命名的预备语句或者入口)。

EmptyQueryResponse (B)

Byte1('I')

标识这条消息是对一个空查询字符串的响应。 (这个消息替换了 CommandComplete。)

Int32(4)

以字节记的消息内容长度，包括它自己。

ErrorResponse (B)

Byte1('E')

标识消息是一条错误

Int32

以字节记的消息内容的长度，包括长度本身。

消息体由一个或多个标识出来的字段组成，后面跟着一个字节零作为终止符。字段可以以任何顺序出现。 对于每个字段都有下面的东西：

Byte1

一个标识字段类型的代码；如果为零，这就是消息终止符并且不会跟着有字符串。 目前定义的字段类型在Section 48.6列出。 因为将来可能增加更多的字段类型，所以前端应该不声不响地忽略不认识类型的字段。

String

字段值

Execute (F)

Byte1('E')

标识消息识一个 Execute 命令。

Int32

以字节记的消息内容的长度，包括长度自身。

String

要执行的入口的名字(空字符串选定未命名的入口)。

Int32

要返回的最大行数，如果入口包含返回行的查询(否则忽略)。零表示"没有限制"。

Flush (F)

Byte1('H')

标识消息识一条 Flush 命令。

Int32(4)

以字节记的消息内容的长度，包括长度本身。

FunctionCall (F)

Byte1('F')

标识消息是一个函数调用。

Int32

以字节记的消息内容的长度，包括长度本身。

Int32

声明待调用的函数的对象标识(OID)。

Int16

后面跟着的参数格式代码的数目(用下面的_C_表示)。 它可以是0，表示没有参数，或者是所有参数都使用缺省格式(文本)；或者是1，这种情况下声明的格式代码应用于所有参数；或者它可以等于参数的实际个数。

Int16[_C_]

参数格式代码。目前每个必须是0(文本)或者1(二进制)。

Int16

声明提供给函数的参数个数

然后，每个参数都出现下面字段对：

Int32

以字节记的参数值的长度(不包括长度自己)。可以为零。 一个特殊的例子是，-1 表示一个 NULL 参数值。如果是 NULL ，则没有参数字节跟在后面。

Byte_n_

参数的值，格式是用相关的格式代码表示的。_n_是上面的长度。

在最后一个参数之后，出现下面的字段：

Int16

函数结果的格式代码。目前必须是0(文本)或者1(二进制)。

FunctionCallResponse (B)

Byte1('V')

标识这条消息是一个函数调用结果

Int32

以字节计的消息内容长度，包括长度本身。

Int32

以字节记的函数结果值的长度(不包括长度本身)。 可以为零。一个特殊的情况是 -1 表示 NULL 函数结果。如果是 NULL 则后面没有数值字节跟随。

Byte_n_

函数结果的值，格式是相关联的格式代码标识的。_n_ 是上面的长度。

NoData (B)

Byte1('n')

标识这条消息是一个无数据指示器

Int32(4)

以字节计的消息内容长度，包括长度本身。

NoticeResponse (B)

Byte1('N')

标识这条消息是一个通知

Int32

以字节计的消息内容长度，包括长度本身。

消息体由一个或多个标识字段组成，后面跟着字节零作为中止符。字段可以以任何顺序出现。对于每个字段，都有下面的东西：

Byte1

一个标识字段类型的代码；如果为零，那么它就是消息终止符，并且后面不会跟着字符串。 目前定义的字段类型在Section 48.6里列出。 因为将来可能会增加更多字段类型，所以前端应该将不识别的字段安静地忽略掉。

String

字段值

NotificationResponse (B)

Byte1('A')

标识这条消息是一个通知响应

Int32

以字节计的消息内容长度，包括长度本身。

Int32

通知后端进程的进程 ID

String

触发通知的通道(channel)的名字

String

从通知进程传递过来的"装载（payload）"字符串。

ParameterDescription (B)

Byte1('t')

标识消息是一个参数描述

Int32

以字节计的消息内容长度，包括长度本身。

Int16

语句所使用的参数的个数(可以为零)

然后，对每个参数，有下面的东西：

Int32

声明参数数据类型的对象 ID

ParameterStatus (B)

Byte1('S')

标识这条消息是一个运行时参数状态报告

Int32

以字节计的消息内容长度，包括长度本身。

String

被报告的运行时参数的名字

String

参数的当前值

Parse (F)

Byte1('P')

标识消息是一条 Parse 命令。

Int32

以字节计的消息内容长度，包括长度本身。

String

目的预备语句的名字(空字符串表示选取了未命名的预备语句)

String

要解析的查询字符串

Int16

声明的参数数据类型的数目(可以为零)。 请注意这个参数并不意味着可能在查询字符串里出现的参数个数的意思，只是前端希望预先声明的类型的数目。

然后，对每个参数，有下面的东西：

Int32

声明参数数据类型的对象 ID 。在这里放一个零等效于不声明该类型。

ParseComplete (B)

Byte1('1')

标识这条消息是一个 Parse 完成指示器。

Int32(4)

以字节计的消息内容长度，包括长度本身。

PasswordMessage (F)

Byte1('p')

标识这条消息是一个口令响应。 注意这也被使用在GSSAPI和SSPI响应消息中。 （这实际上是一个设计错误，既然这里包含的数据不是一个NULL终止的字符串，而可能是任意的二进制数据。）

Int32

以字节计的消息内容长度，包括长度本身。

String

口令(必要的情况下，是加密后的)。

PortalSuspended (B)

Byte1('s')

标识这条消息是一个入口挂起指示器。 请注意这个消息只出现在达到一条 Execute 消息的行计数限制的时候。

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

用于该字段的格式码。目前会是0(文本)或者1(二进制)。 从语句的Describe 返回的 RowDescription 里，格式码还是未知的，因此总是零。

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

给后端的命令行参数。(这个特性已经废弃，更好的方法是设置单独的运行时参数。)

除了上面的外，在后端启动的时候可以设置的任何运行时参数都可以列出来。 这样的设置将在后端启动的时候附加(在分析了命令行参数之后，如果有的话)。这些值将成为会话缺省。

String

参数值

Sync (F)

Byte1('S')

表示该消息为一条 Sync 命令。

Int32(4)

以字节计的消息内容长度，包括长度本身。

Terminate (F)

Byte1('X')

标识消息是一个终止消息。

Int32(4)

以字节计的消息内容长度，包括长度本身。