48.5. 消息格式 · PostgreSQL 中文文檔 9.3

# 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](#calibre_link-777)獲取更多信息。 Int16 數據中要拷貝的字段數(由下面的`_N_`解釋)。 Int16[`_N_`] 每個字段將要使用的格式代碼，目前每個都必須是0(文本)或者1(二進制)。如果全部拷貝格式都是文本的，那么所有的都必須是0。 CopyOutResponse (B) Byte1('H') 標識這條消息是一條 StartCopyOut(開始拷貝輸出)響應消息。這條消息后面將跟著一條拷貝出數據消息。 Int32 以字節記的消息內容的長度，包括它自己。 Int8 0 表示全部`COPY`格式都是文本(數據行由換行符分隔，字段由分隔字符分隔等等)。 1 表示所有拷貝格式都是二進制的(類似于 DataRow 格式)。參閱[COPY](#calibre_link-777)獲取更多信息。 Int16 要拷貝的數據的字段的數目(在下面的`_N_`說明)。 Int16[`_N_`] 每個字段要使用的格式代碼。目前每個都必須是0(文本)或者1(二進制)。如果全部的拷貝格式都是文本，那么所有的都必須是0。 CopyBothResponse (B) Byte1('W') 標識這條消息是一條 StartCopyBoth(開始雙向拷貝)響應消息。這個消息只會被流復制使用。 Int32 以字節記的消息內容的長度，包括它自己。 Int8 0 表示全部拷貝`COPY`格式都是文本(數據行由換行符分隔，字段由分隔字符分隔等等)。 1 表示所有拷貝格式都是二進制的(類似于 DataRow 格式)。參閱[COPY](#calibre_link-777)獲取更多信息。 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](#calibre_link-1027)列出。因為將來可能增加更多的字段類型，所以前端應該不聲不響地忽略不認識類型的字段。 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](#calibre_link-1027)里列出。因為將來可能會增加更多字段類型，所以前端應該將不識別的字段安靜地忽略掉。 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) 以字節計的消息內容長度，包括長度本身。