PostgreSQL7.0手册-开发者手册 -64. 前端/后端协议
2019-09-08 23:34:06
供稿：网友
第六十四章. 前端/后端协议
内容
概述
协议
消息数据类型
消息格式
注意：由 Phil Thompson 写作．协议 2.0 的更新由 Tom Lane 写作．
Postgres 使用一种以消息为基础的协议用于在前端和后端之间通讯．该协议是在 TCP/IP 和 Unix 套接字上实现的．Postgres v6.3 往协议里面引入了版本号．这么做的同时仍然允许早期的前端与新的后端进行联接，但是本文档没有介绍那些早期版本的协议．
这份文档描述了版本 2.0 的协议，在 Postgres v6.4 和以后的版本中实现．
在这个协议的基础上建立的更高级特性（例如，libpq 是如何在建立联接以后传递某种环境变量的）在其他地方描述．
概述
The three major components are the frontend (running on the client) and the postmaster and backend (running on the server). The postmaster and backend have different roles but may be implemented by the same executable.
三个主要的部分是前端（在客户端运行）postmaster 和后端（在服务器端运行）．postmaster 和后端有着不同的角色但是可以用同样的可执行文件实现．
一个前端向 postmaster 发送一个启动包．包里面包括用户名和该用户希望联接的数据库．postmaster 则使用这些信息和 pg_hba.conf(5) 文件里的信息决定她还需要前端发送什么样的进一步认证信息（如果需要的话）并且把这些回应给相应的前端．
该前端则发送任何所要求的认证信息．一旦 postmaster 认为有效，那么它回应给前端并且把联接转交给一个后端．该后端则发送信息给前端表明启动成功（正常状态）或失败（例如，非法数据库名）．
随后的通讯是在前端和后端之间交换的查询和结果包．postmaster 不再参与正常的查询/结果通讯．（不过，当前端希望取消目前在其后端上执行的查询时，postmaster 也要参与．详细信息见下文．）
当前端希望断开联接时，它给后端发送一个合适的包并且在不等待后端回应的情况下关闭联接．
包是当做数据流发送的．包的第一个字节决定了包的其余部分的类型．例外是从前端发送给 postmaster 的包，是由包长和包本身组成．这种区别是历史原因造成的．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
协议
本节描述信息流．根据联接的状态不同有四种类型的流：启动（startup），查询（query），函数调用（function call）和结束（termination）．还有用于通知响应和命令取消的特殊信息，这些特殊信息可能在启动阶段过后的任何时间发生．
启动
启动分成认证阶段和后端启动阶段．
开始时，前端发送一个 StartupPacket （启动包）．postmaster 利用这个信息和 pg_hba.conf(5) 文件的内容决定这个前端必须使用那种认证方式．然后 postmaster 用下面信息之一响应：
ErrorResponse
然后 postmaster 马上关闭联接．
AuthenticationOk
然后 postmaster 转交给后端．postmaster 不再参与以后的通讯．
AuthenticationKerberosV4
然后前端必须与 postmaster 进行一次 Kerberos V4 认证对话（在这里没有描述）．如果对话成功，postmaster 响应一个 AuthenticationOk （认证成功）信息，否则它响应一个 ErrorResponse （错误响应）．
AuthenticationKerberosV5
然后前端必须与 postmaster 进行一次 Kerberos V5 认证对话（在这里没有描述）．如果对话成功，postmaster 响应一个 AuthenticationOk （认证成功）信息，否则它响应一个 ErrorResponse （错误响应）．
AuthenticationUnencryptedPassword
然后前端必须发送一个 UnencryptedPasswordPacket （未加密口令）包．如果这是正确的口令，postmaster 用一个 AuthenticationOk 包响应，否则它响应一个 ErrorResponse 包．
AuthenticationEncryptedPassword
然后前端必须发送一个 EncryptedPasswordPacket （加密口令）包．如果这是正确口令，postmaster 用一个AuthenticationOk 响应，否则它用一个 ErrorResponse 响应．
如果前端不支持 postmaster 要求的认证方式，那么它应该马上关闭联接．
在发送完 AuthenticationOk 包之后，postmaster 试图运行一个后端进程．因为这个过程可能失败，或者后端可能在启动过程中失败，前端必须等待后端确认成功启动．这时前端不应该发送任何信息．在这个阶段从后端来的信息可能是：
BackendKeyData
这个消息是在后端成功启动后才发出的．这个消息提供了密钥（secret-key）数据，前端如果想要在稍后发出取消的请求，则必须保存这个数据．前端不应该响应这个信息，但是应该继续侦听等待 ReadyForQuery 消息．
ReadyForQuery
后端启动成功，前端现在可以发出查询或者函数调用消息．
ErrorResponse
后端启动失败．在发送完这个消息之后联接被关闭．
NoticeResponse
发出了一个警告信息．前端应该显示这个信息，并且继续等待 ReadyForQuery 或 ErrorResponse．
后端在每个查询循环后都会发出一个相同的 ReadyForQuery 消息．前端可以认为 ReadyForQuery 是一个查询循环的开始（而 BackendKeyData 表明启动阶段的成功完成），或者认为 ReadyForQuery 是启动阶段和每个随后查询循环的结束，这些取决于前端的编码需要．
查询
一个查询循环是由前端发送一条 Query 消息给后端初始化的．后端根据查询命令字串的内容发送一条或者更多条响应消息给前端，并且最后是一条 ReadyForQuery 响应信息．ReadyForQuery 通知前端它可以安全地发送新查询或者函数调用给后端了．
从后端来的可能的消息是：
CompletedResponse
一个正常结束的 SQL 命令．
CopyInResponse
后端已经准备好从前端拷贝数据到一个关系里面去．然后前端应该发送一条 CopyDataRows 消息．然后后端用一个带有标记 "COPY" 的 CompletedResponse 消息响应．
CopyOutResponse
后端已经准备好从一个关系拷贝数据到前端里面去．然后它会发送一条 CopyDataRows 消息．最后后端发送一个带有标记 "COPY" 的 CompletedResponse 消息．
CursorResponse
查询可以是一条 insert(l)，delete(l)，update(l)，fetch(l) 或一个 select(l) 命令．如果事务被终止，那么后端发送一条带有标记 "*ABORT STATE*" 的 CompletedResponse 消息．否则发送下面的响应．
对一条 insert(l) 命令，后端发送一条带有 "INSERT oidrows" 标记的 CompletedResponse 消息，这里的 rows 是插入的行数，而 oid 在插入的函数 rows 为 1 时是插入行的对象标识（OID），否则 oid 为 0．
对一条 delete(l) 命令，后端发送一条带有 "DELETE rows" 标记的 CompletedResponse 消息，这里 rows 是删除的行数．
对一条 update(l) 命令，后端发送一条带有 "UPDATE rows" 标记的 CompletedResponse 消息，这里 rows 是更新的行数．
对于一条 fetch(l) 或 select(l) 命令，后端发送一条 RowDescription 消息．然后跟着一条 AsciiRow 或 BinaryRow 消息 （取决于是否声明了一个二进制游标）给返回给前端的每一行．最后，后端发送一条带有标记 "SELECT" 的 CompletedResponse 消息．
EmptyQueryResponse
识别了一个空的查询字串．（ 对这个情况的特殊识别是历史原因．）
ErrorResponse
发生了一个错误．
ReadyForQuery
查询字串的处理完成．发送一个分隔消息来标识这个是因为查询字串可能包含多个 SQL 命令．（CompletedResponse 只是标记一条 SQL 命令处理完毕，而不是整个字串．）ReadyForQuery 总会被发送，不管是处理成功结束还是产生错误．
NoticeResponse
发送了一个与查询有关的警告信息．注意信息是附加在其他响应上的，也就是说, 后端将继续处理该命令．
前端在等待其他类型的消息时必须准备接收 ErrorResponse 和 NoticeResponse 消息．
实际上，当前端没有等待任何消息时 NoticeResponse 消息也有可能到达，那就是，后端正常空闲．（尤其是后端可以被其 postmaster 命令终止运行．在那种情况下，后端将在关闭联接之前发送一条 NoticeResponse 消息．）我们建议前端在发出任何命令之前检查这样的异步通知消息．
同样，如果前端发出了任何 listen(l) 命令，那么它必须在任何时候准备接收 NotificationResponse 消息；见下文．
函数调用
一个函数调用循环是由前端向后端发送一条 FunctionCall 消息初始化的．然后后端根据函数调用的结果发送一条或者更多响应消息，并且在最后是一条 ReadyForQuery 响应消息．ReadyForQuery 通知前端它可以安全地发送一条新的查询或者函数调用了．
从后端来的可能的响应信息是：
ErrorResponse
发生了一个错误．
FunctionResultResponse
函数调用被执行并且返回一个结果．
FunctionVoidResponse
函数调用被执行并且没有返回一个结果．
ReadyForQuery
函数调用处理完成．ReadyForQuery 将总是被发送，不管是成功完成处理还是发生一个错误．
NoticeResponse
发出了一条有关该函数调用的警告信息．通知是附加在其他响应上的，也就是说，后端将继续处理命令．
前端在等待其他类型的消息时必须准备接收 ErrorResponse 和 NoticeResponse 消息．同样，如果前端发出了任何 listen(l) 命令，那么它必须在任何时候准备接收 NotificationResponse 消息；见下文．
通知响应
如果前端发出了一条 listen(l) 命令，那么每当为同样名称的通知执行一条 notify(l) 命令，后端都会发送一条 NotificationResponse 消息 （不要与 NoticeResponse 弄混了！）．
除了在另外一个后端的消息里以外，在协议里的任何地方（启动后）都允许通知响应．因此，前端在等待任何消息的时候都必须准备识别 NotificationResponse 消息．实际上，前端甚至在不能进行查询的时候都要能够处理 NotificationResponse 消息．
NotificationResponse
一条 notify(l) 命令为前面执行的 listen(l) 命令的名称被执行．通知可以在任何时候发送．
有一点值得我们指出来，就是在 listen 和 notify 里面的名称不必与 SQL 数据库里的关系（表）的名称有任何关系．通知名只是一个独立选出来的条件名．
取消正在处理的请求
在一条查询正在处理的时候，前端可以通过发送合适的消息给 postmaster 取消该查询的处理．这样的取消不直接发送给后端是因为实现的有效性：我们不希望后端在处理查询的过程中不停地检查前端来的输入．取消请求应该相对而言比较少见，所以我们把取消做得稍微笨拙一些，以便不影响正常状况的性能．
要发送一条取消请求，前端打开一个与 postmaster 的新的联接并且发送一条 CancelRequest 消息，而不是通常在新联接中经常发送的 StartupPacket 消息．postmaster 将处理这个请求然后关闭联接．出于安全原因，对取消请求消息不做直接的响应．
除非 CancelRequest 消息包含与联接启动过程中传递给前端的相同的键数据（PID 和 安全键字），否则它将被忽略．如果该请求与当前运行着的后端匹配了 PID 和安全键字，postmaster 将给后端发送信号以退出当前查询．
取消信号可能有也可能没有做用 －－ 例如，如果它在后端完成查询的处理后到达，那么它就没有做用．如果取消起作用了，它将导致当前命令带着一个错误信息被提前退出．
这么做的结果是对安全和有效性通盘考虑的结果，前端没有直接的方法获知一个取消请求是否成功．它必须继续等待后端对查询响应．执行取消仅仅是增加了当前查询快些结束的可能性，以及增加了当前查询会带着一条错误信息失败而不是成功执行的可能性．
因为取消请求是发送给 postmaster 而不是通过通常的前端/后端通讯链接，所以取消请求可能是任意过程执行的，而不仅仅是要取消查询的前端．这样可能对创建多进程应用有某种灵活性的好处．但是同时这样也带来了安全风险，因为这样任何一个非认证用户都可能试图取消查询．这个安全风险通过要求在取消请求中提供一个动态生成的安全键字排除．
终止
通常的和优雅的终止过程是前端发送一条 Terminate （终止）消息并且立刻关闭联接．一旦收到消息，后端马上关闭联接并且退出．
一个欠优雅的的退出可能因为任何一端的软件失效（例如．内核倾倒）产生．如果前端或后端看到一个意外的联接关闭，它应该清理并退出．前端可以选择通过 postmaster 重新建立一个新的联接 －－ 如果它不想终止自己的处理的话．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
消息数据类型
本节描述消息里用到的基本数据类型．
Intn(i)
一个网络字节序（译注：高位->高地址，底位->底地址）的 n 位整数．如果声明了 i ，它就是字面（literal ）值．如.．Int16，Int32（42）．
LimStringn(s)
一个被当成一个 '/0' 结尾的字串的 n 字节的字符数组．如果空间不够，'/0' 被忽略．如果声明了 s ，那么它是字面值．例如．LimString32，LimString64（"user"）．
String(s)
一个传统没有长度限制的的 C 的 '/0' 结尾的字符串。如果声明了 s ，那么它是字面值．例如 String，String("user")。
注意：后端返回的字串的可能长度没有预定义的限制。所以前端必须使用良好的编码策略，使用某种可扩展的缓冲区以便能接受任何能放进内存里的东西。如果那样做不可行，则读取全长的字串然后抛弃不能放进你的定长缓冲区的结尾字符。
Byten(c)
精确的 n 字节．如果声明了 c 它是字面值．例如．Byte，Byte1（'/n'）．
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
消息格式
本节描述各种消息的详细格式．每种消息都可以由一个前端 （F），一个 posmaster/后端（B）或者两者（F & B）发送．
AsciiRow (B)
Byte1('D')
标识消息是一个 ASCII 数据行．（一个前面的 RowDescription 消息定义该行里面的字段数和它们的数据类型．）
Byten
一个每个位对应（数据）行里一个字段的位图．第一字段对应第一字节的位7 （MSB，最高位），第二字段对应第一字节位6，第八字段对应第一字节位 0 （LSB，最低位），第九字段对应第二字节的位7，等等．如果对应域的值不为 NULL，对应位设置为1，如果字段的个数不为8的倍数，位图最后一个字节余下的位就没有用．
然后，每个非空的字段值（non-NULL），有下面规则：
Int32
声明字段值的尺寸，包括尺寸本身．
Byten
声明以 ASCII 字符表示的字段值本身．n 是上面的尺寸减 4．在字段数据里面没有结尾的 '/0'；如果前端希望有个结束符，它必须自己追加一个．
AuthenticationOk (B)
Byte1('R')
标识该消息是一条认证请求．
Int32(0)
声明该认证是成功的．
AuthenticationKerberosV4 (B)
Byte1('R')
标识该消息是一条认证请求．
Int32(1)
声明需要 Kerberos V4 认证．
AuthenticationKerberosV5 (B)
Byte1('R')
标识该消息是一条认证请求．
Int32(2)
声明需要 Kerberos V5 认证．
AuthenticationUnencryptedPassword (B)
Byte1('R')
标识该消息是一条认证请求．
Int32(3)
声明需要一个未加密的口令．
AuthenticationEncryptedPassword (B)
Byte1('R')
标识该消息是一条认证请求．
Int32(4)
声明需要一个加密的口令．
Byte2
加密口令使用的'种子'（salt）．
BackendKeyData (B)
Byte1('K')
标识该消息是一个取消键字数据．如果前端希望能够在稍后发出 CancelRequest 消息，那么它必须保存这个值．
Int32
后端的进程号（PID）．
Int32
此后端的密钥（secret key ）．
BinaryRow (B)
Byte1('B')
标识消息为为二进制（数据）行．（一个前面的 RowDescription 消息定义数据行里的字段数和它们的数据类型．）
Byten
一个每个位对应（数据）行里一个字段的位图．第一字段对应第一字节的位7 （MSB，最高位），第二字段对应第一字节位6，第八字段对应第一字节位 0 （LSB，最低位），第九字段对应第二字节的位7，等等．如果对应域的值不为 NULL，对应位设置为1，如果字段的个数不为8的倍数，位图最后一个字节余下的位就没有用．
然后，每个非空的字段值（non-NULL），有下面规则：
Int32
声明字段值的尺寸，包括尺寸本身．
Byten
以二进制格式声明字段本身的值．n 就是上面的尺寸．
CancelRequest (F)
Int32(16)
以字节计的包尺寸．
Int32(80877102)
取消请求代码．选这个值是为了在高16位包含 "1234"，低16位包含 "5678"．（要避免混乱，这个代码必须与协议版本号不同．）
Int32
目标后端的进程号（PID）．
Int32
目标后端的密钥（secret key ）．
CompletedResponse (B)
Byte1('C')
标识此消息是一个完成响应．
String
命令标记．它通常是（但并不总是）一个单字，标识完成了哪条 SQL 命令．
CopyDataRows (B & F)
这是一个行的流，这里每行都是一个 Byte1('/n') 结尾的．后面顺序跟着 Byte1('//')，Byte1('.')，Byte1('/n')．
CopyInResponse (B)
Byte1('G')
标识这条消息是一条 Start Copy In （开始拷贝进入）响应消息．前端现在必须发送一条 CopyDataRows．
CopyOutResponse (B)
Byte1('H')
标识这条消息是一条 Start Copy Out （开始拷贝进出）响应消息．这条消息后面将跟着一条 CopyDataRows 消息．
CursorResponse (B)
Byte1('P')
标识这条消息是一条游标响应消息．
String
游标的名称．如果游标是隐含的，这个地方会是"空白" （"blank"）．
EmptyQueryResponse (B)
Byte1('I')
标识这条消息是对一个空查询字串的响应．
String("")
没有用．
EncryptedPasswordPacket (F)
Int32
以字节记的包的尺寸．
String
加密了（使用 crypt()）的口令．
ErrorResponse (B)
Byte1('E')
标识消息是一条错误．
String
错误消息本身．
FunctionCall (F)
Byte1('F')
标识消息是一个函数调用．
String("")
未使用．
Int32
声明待调用的函数的对象标识（OID）．
Int32
声明提供给函数的参数个数．
然后，每个参数用下面格式声明：
Int32
声明参数值的尺寸，除去尺寸本身的长度．
Byten
声明以二进制格式表示的字段值本身． n 是上面的尺寸．
FunctionResultResponse (B)
Byte1('V')
标识这条消息是函数调用结果．
Byte1('G')
声明返回了一个非空结果．
Int32
声明结果值的尺寸，除去尺寸本身长度．
Byten
声明二进制格式表示的结果值本身．n 是上面的尺寸．
Byte1('0')
未用．（严格的说，FunctionResultResponse 和 FunctionVoidResponse 都是一样的东西，但是消息里有一些可选的部分．）
FunctionVoidResponse (B)
Byte1('V')
标识这条消息是一个函数调用结果．
Byte1('0')
声明返回了一个空结果．
NoticeResponse (B)
Byte1('N')
标识消息是一个通知．
String
通知消息本身．
NotificationResponse (B)
Byte1('A')
标识消息是一个通知响应．
Int32
发出通知的后端进程的进程号（PID）．
String
生成通知的条件名．
Query (F)
Byte1('Q')
标识此消息是一条查询．
String
查询字串本身．
ReadyForQuery (B)
Byte1('Z')
标识消息类型．当后端准备好进入一个新的查询循环时，它发送一条 ReadyForQuery．
RowDescription (B)
Byte1('T')
标识消息是一个行描述消息．
Int16
声明一行里的字段数（可以是零）．
然后每个字段，用下面格式表示：
String
声明字段名称．
Int32
声明字段的对象标识（OID）．
Int16
声明类型尺寸．
Int32
声明类型修改器．
StartupPacket (F)
Int32(296)
以字节计的包的尺寸．
Int32
协议版本号．最高16位是主版本号．低16位是次版本号．
LimString64
数据库名，缺省时是用户名．
LimString32
用户名．
LimString64
由 postmaster 传递给后端的任何附加的命令行参数．
LimString64
未使用．
LimString64
后端用于调试信息输出的可选 tty （控制台）．
Terminate (F)
Byte1('X')
标识这条消息是终止消息．
UnencryptedPasswordPacket (F)
Int32
以字节计的包尺寸．
String
未加密的口令．
--------------------------------------------------------------------------------
