支援的版本:目前 (17) / 16 / 15 / 14 / 13
開發版本:devel
不支援的版本:12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2 / 7.1

53.7. 訊息格式 #

本節描述每個訊息的詳細格式。每個訊息都標記為可由前端 (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

加密密碼時使用的鹽值。

AuthenticationGSS (B) #
Byte1('R')

將訊息識別為身份驗證請求。

Int32(8)

訊息內容的長度(以位元組為單位),包括自身。

Int32(7)

指定需要 GSSAPI 身份驗證。

AuthenticationGSSContinue (B) #
Byte1('R')

將訊息識別為身份驗證請求。

Int32

訊息內容的長度(以位元組為單位),包括自身。

Int32(8)

指定此訊息包含 GSSAPI 或 SSPI 資料。

Byten

GSSAPI 或 SSPI 身份驗證資料。

AuthenticationSSPI (B) #
Byte1('R')

將訊息識別為身份驗證請求。

Int32(8)

訊息內容的長度(以位元組為單位),包括自身。

Int32(9)

指定需要 SSPI 身份驗證。

AuthenticationSASL (B) #
Byte1('R')

將訊息識別為身份驗證請求。

Int32

訊息內容的長度(以位元組為單位),包括自身。

Int32(10)

指定需要 SASL 身份驗證。

訊息正文是 SASL 身份驗證機制的列表,按伺服器的偏好順序排列。最後一個身份驗證機制名稱後需要一個零位元組作為終止符。對於每個機制,都有以下內容:

字串

SASL 身份驗證機制的名稱。

AuthenticationSASLContinue (B) #
Byte1('R')

將訊息識別為身份驗證請求。

Int32

訊息內容的長度(以位元組為單位),包括自身。

Int32(11)

指定此訊息包含 SASL 質詢。

Byten

SASL 資料,特定於所使用的 SASL 機制。

AuthenticationSASLFinal (B) #
Byte1('R')

將訊息識別為身份驗證請求。

Int32

訊息內容的長度(以位元組為單位),包括自身。

Int32(12)

指定 SASL 身份驗證已完成。

Byten

SASL 結果「附加資料」,特定於所使用的 SASL 機制。

BackendKeyData (B) #
Byte1('K')

將訊息識別為取消金鑰資料。如果前端希望稍後能夠發出 CancelRequest 訊息,則必須儲存這些值。

Int32(12)

訊息內容的長度(以位元組為單位),包括自身。

Int32

此後端的進程 ID。

Int32

此後端的密鑰。

Bind (F) #
Byte1('B')

將訊息識別為 Bind 命令。

Int32

訊息內容的長度(以位元組為單位),包括自身。

字串

目標入口網站的名稱(空字串選擇未命名入口網站)。

字串

來源預備語句的名稱(空字串選擇未命名預備語句)。

Int16

以下參數格式代碼的數量(以下表示為 C)。它可以為零,表示沒有參數或參數都使用預設格式(文字);或者為一,在這種情況下,指定的格式代碼應用於所有參數;或者它可以等於參數的實際數量。

Int16[C]

參數格式代碼。每個代碼目前必須為零(文字)或一(二進位)。

Int16

後續參數值的數量(可能為零)。此值必須與查詢所需的參數數量相符。

接下來,每個參數都會出現以下欄位組

Int32

參數值的長度,以位元組為單位(此計數不包含本身)。可以是零。作為一個特例,-1 表示 NULL 參數值。在 NULL 情況下,沒有後續的值位元組。

Byten

參數的值,格式由相關的格式代碼指示。n 是上述長度。

在最後一個參數之後,會出現以下欄位

Int16

後續結果欄格式代碼的數量(以下表示為 R)。此值可以為零,表示沒有結果欄或結果欄應全部使用預設格式(文字);或者為一,在這種情況下,指定的格式代碼將應用於所有結果欄(如果有的話);或者它可以等於查詢的實際結果欄數。

Int16[R]

結果欄格式代碼。目前每個代碼必須為零(文字)或一(二進位)。

BindComplete (B) #
Byte1('2')

將訊息識別為 Bind-complete 指示器。

Int32(4)

訊息內容的長度(以位元組為單位),包括自身。

CancelRequest (F) #
Int32(16)

訊息內容的長度(以位元組為單位),包括自身。

Int32(80877102)

取消請求代碼。該值的選擇是為了在最高有效 16 位中包含 1234,在最低有效 16 位中包含 5678。(為避免混淆,此代碼不得與任何協議版本號相同。)

Int32

目標後端的程序 ID。

Int32

目標後端的秘密金鑰。

Close (F) #
Byte1('C')

將訊息識別為 Close 命令。

Int32

訊息內容的長度(以位元組為單位),包括自身。

Byte1

'S' 用於關閉預備語句;或 'P' 用於關閉入口(portal)。

字串

要關閉的預備語句或入口的名稱(空字串選擇未命名的預備語句或入口)。

CloseComplete (B) #
Byte1('3')

將訊息識別為 Close-complete 指示器。

Int32(4)

訊息內容的長度(以位元組為單位),包括自身。

CommandComplete (B) #
Byte1('C')

將訊息識別為命令完成回應。

Int32

訊息內容的長度(以位元組為單位),包括自身。

字串

命令標籤。這通常是一個單字,用於識別已完成的 SQL 命令。

對於 INSERT 命令,標籤為 INSERT oid rows,其中 rows 是插入的行數。oid 曾經是插入行的物件 ID,如果 rows 為 1 且目標表具有 OID,但 OID 系統欄不再支援;因此 oid 始終為 0。

對於 DELETE 命令,標籤為 DELETE rows,其中 rows 是刪除的行數。

對於 UPDATE 命令,標籤為 UPDATE rows,其中 rows 是更新的行數。

對於 MERGE 命令,標籤為 MERGE 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

訊息內容的長度(以位元組為單位),包括自身。

Byten

構成 COPY 資料流的一部分的資料。從後端傳送的訊息將始終對應於單個資料列,但前端傳送的訊息可能會任意分割資料流。

CopyDone (F & B) #
Byte1('c')

將訊息識別為 COPY-complete 指示器。

Int32(4)

訊息內容的長度(以位元組為單位),包括自身。

CopyFail (F) #
Byte1('f')

將訊息識別為 COPY-failure 指示器。

Int32

訊息內容的長度(以位元組為單位),包括自身。

字串

要報告為失敗原因的錯誤訊息。

CopyInResponse (B) #
Byte1('G')

將訊息識別為 Start Copy In 回應。前端現在必須傳送 copy-in 資料(如果未準備好這樣做,請傳送 CopyFail 訊息)。

Int32

訊息內容的長度(以位元組為單位),包括自身。

Int8

0 表示整體 COPY 格式為文字(行由換行符分隔,欄由分隔符分隔等)。1 表示整體 copy 格式為二進位(類似於 DataRow 格式)。有關更多資訊,請參閱 COPY

Int16

要複製的資料中的欄數(以下表示為 N)。

Int16[N]

要用於每個欄位的格式代碼。目前每個代碼必須為零(文字)或一(二進位)。如果整體 copy 格式為文字,則所有代碼必須為零。

CopyOutResponse (B) #
Byte1('H')

將訊息識別為 Start Copy Out 回應。此訊息之後將是 copy-out 資料。

Int32

訊息內容的長度(以位元組為單位),包括自身。

Int8

0 表示整體 COPY 格式為文字(行由換行符分隔,欄由分隔符分隔等)。1 表示整體 copy 格式為二進位(類似於 DataRow 格式)。有關更多資訊,請參閱 COPY

Int16

要複製的資料中的欄數(以下表示為 N)。

Int16[N]

要用於每個欄位的格式代碼。目前每個代碼必須為零(文字)或一(二進位)。如果整體 copy 格式為文字,則所有代碼必須為零。

CopyBothResponse (B) #
Byte1('W')

將訊息識別為 Start Copy Both 回應。此訊息僅用於 Streaming Replication。

Int32

訊息內容的長度(以位元組為單位),包括自身。

Int8

0 表示整體 COPY 格式為文字(行由換行符分隔,欄由分隔符分隔等)。1 表示整體 copy 格式為二進位(類似於 DataRow 格式)。有關更多資訊,請參閱 COPY

Int16

要複製的資料中的欄數(以下表示為 N)。

Int16[N]

要用於每個欄位的格式代碼。目前每個代碼必須為零(文字)或一(二進位)。如果整體 copy 格式為文字,則所有代碼必須為零。

DataRow (B) #
Byte1('D')

將訊息識別為資料列。

Int32

訊息內容的長度(以位元組為單位),包括自身。

Int16

後續欄位值的數量(可能為零)。

接下來,每個欄位都會出現以下欄位組

Int32

欄位值的長度,以位元組為單位(此計數不包含其本身)。可以為零。作為一種特殊情況,-1 表示 NULL 欄位值。在 NULL 情況下,後面沒有值位元組。

Byten

欄位的值,格式由相關的格式代碼指示。n 是上述長度。

Describe (F) #
Byte1('D')

將訊息識別為 Describe 命令。

Int32

訊息內容的長度(以位元組為單位),包括自身。

Byte1

'S' 用於描述預備語句;或 'P' 用於描述入口 (portal)。

字串

要描述的預備語句或入口的名稱(空字串選擇未命名的預備語句或入口)。

EmptyQueryResponse (B) #
Byte1('I')

將訊息識別為對空查詢字串的回應。(這取代了 CommandComplete。)

Int32(4)

訊息內容的長度(以位元組為單位),包括自身。

ErrorResponse (B) #
Byte1('E')

將訊息識別為錯誤。

Int32

訊息內容的長度(以位元組為單位),包括自身。

訊息主體由一個或多個已識別的欄位組成,後跟一個零位元組作為終止符。欄位可以以任何順序出現。對於每個欄位,都有以下內容:

Byte1

識別欄位類型的代碼;如果為零,則表示訊息終止符,且後面沒有字串。目前定義的欄位類型列在Section 53.8中。由於將來可能會添加更多欄位類型,因此前端應靜默地忽略無法識別的類型欄位。

字串

欄位值。

Execute (F) #
Byte1('E')

將訊息識別為 Execute 命令。

Int32

訊息內容的長度(以位元組為單位),包括自身。

字串

要執行的入口名稱(空字串選擇未命名的入口)。

Int32

要返回的最大行數,如果入口包含返回行的查詢(否則將被忽略)。零表示無限制

Flush (F) #
Byte1('H')

將訊息識別為 Flush 命令。

Int32(4)

訊息內容的長度(以位元組為單位),包括自身。

FunctionCall (F) #
Byte1('F')

將訊息識別為函數呼叫。

Int32

訊息內容的長度(以位元組為單位),包括自身。

Int32

指定要呼叫的函數的物件 ID。

Int16

後續引數格式代碼的數量(以下表示為 C)。可以為零,表示沒有引數,或所有引數都使用預設格式(文字);或為一,在這種情況下,指定的格式代碼將應用於所有引數;或者它可以等於引數的實際數量。

Int16[C]

引數格式代碼。目前每個都必須為零(文字)或一(二進制)。

Int16

指定提供給函數的引數數量。

接下來,每個引數都會出現以下一對欄位:

Int32

引數值的長度,以位元組為單位(此計數不包含其本身)。可以為零。作為一種特殊情況,-1 表示 NULL 引數值。在 NULL 情況下,後面沒有值位元組。

Byten

引數的值,格式由相關的格式代碼指示。n 是上述長度。

在最後一個引數之後,會出現以下欄位:

Int16

函數結果的格式代碼。目前必須為零(文字)或一(二進制)。

FunctionCallResponse (B) #
Byte1('V')

將訊息識別為函數呼叫結果。

Int32

訊息內容的長度(以位元組為單位),包括自身。

Int32

函數結果值的長度,以位元組為單位(此計數不包含其本身)。可以為零。作為一種特殊情況,-1 表示 NULL 函數結果。在 NULL 情況下,後面沒有值位元組。

Byten

函數結果的值,格式由相關的格式代碼指示。n 是上述長度。

GSSENCRequest (F) #
Int32(8)

訊息內容的長度(以位元組為單位),包括自身。

Int32(80877104)

GSSAPI加密請求代碼。該值的選擇使其最高有效 16 位包含 1234,最低有效 16 位包含 5680。(為避免混淆,此代碼不得與任何協定版本號相同。)

GSSResponse (F) #
Byte1('p')

將訊息識別為 GSSAPI 或 SSPI 回應。請注意,這也用於 SASL 和密碼回應訊息。確切的訊息類型可以從上下文中推斷出來。

Int32

訊息內容的長度(以位元組為單位),包括自身。

Byten

GSSAPI/SSPI 特定訊息資料。

NegotiateProtocolVersion (B) #
Byte1('v')

將訊息識別為協定版本協商訊息。

Int32

訊息內容的長度(以位元組為單位),包括自身。

Int32

伺服器支援的,針對用戶端請求的主協定版本的最新的次要協定版本。

Int32

伺服器無法識別的協定選項數量。

然後,對於伺服器無法識別的協定選項,有以下內容:

字串

選項名稱。

NoData (B) #
Byte1('n')

將訊息識別為無資料指示器。

Int32(4)

訊息內容的長度(以位元組為單位),包括自身。

NoticeResponse (B) #
Byte1('N')

將訊息識別為通知。

Int32

訊息內容的長度(以位元組為單位),包括自身。

訊息主體由一個或多個已識別的欄位組成,後跟一個零位元組作為終止符。欄位可以以任何順序出現。對於每個欄位,都有以下內容:

Byte1

識別欄位類型的代碼;如果為零,則表示訊息終止符,且後面沒有字串。目前定義的欄位類型列在Section 53.8中。由於將來可能會添加更多欄位類型,因此前端應靜默地忽略無法識別的類型欄位。

字串

欄位值。

NotificationResponse (B) #
Byte1('A')

將訊息識別為通知回應。

Int32

訊息內容的長度(以位元組為單位),包括自身。

Int32

發出通知的後端程序的程序 ID。

字串

已在其上引發通知的通道名稱。

字串

從通知程序傳遞的酬載字串。

ParameterDescription (B) #
Byte1('t')

將訊息識別為參數描述。

Int32

訊息內容的長度(以位元組為單位),包括自身。

Int16

語句使用的參數數量(可以為零)。

然後,對於每個參數,都有以下內容:

Int32

指定參數資料類型的物件 ID。

ParameterStatus (B) #
Byte1('S')

將訊息識別為執行階段參數狀態報告。

Int32

訊息內容的長度(以位元組為單位),包括自身。

字串

報告的執行階段參數的名稱。

字串

參數的目前值。

Parse (F) #
Byte1('P')

將訊息識別為 Parse 命令。

Int32

訊息內容的長度(以位元組為單位),包括自身。

字串

目標預備語句的名稱(空字串選擇未命名的預備語句)。

字串

要解析的查詢字串。

Int16

指定的參數資料類型數量(可以為零)。請注意,這並不表示查詢字串中可能出現的參數數量,僅表示前端要預先指定類型的數量。

然後,對於每個參數,都有以下內容:

Int32

指定參數資料類型的物件 ID。在此處放置零等同於不指定類型。

ParseComplete (B) #
Byte1('1')

將訊息識別為 Parse-complete 指示器。

Int32(4)

訊息內容的長度(以位元組為單位),包括自身。

PasswordMessage (F) #
Byte1('p')

識別訊息為密碼回應。請注意,這也用於 GSSAPI、SSPI 和 SASL 回應訊息。確切的訊息類型可以從上下文中推斷出來。

Int32

訊息內容的長度(以位元組為單位),包括自身。

字串

密碼(如果要求加密)。

PortalSuspended (B) #
Byte1('s')

識別訊息為 portal 暫停指示器。 請注意,只有在 Execute 訊息達到 row-count 限制時才會出現。

Int32(4)

訊息內容的長度(以位元組為單位),包括自身。

Query (F) #
Byte1('Q')

識別訊息為簡單查詢。

Int32

訊息內容的長度(以位元組為單位),包括自身。

字串

查詢字串本身。

ReadyForQuery (B) #
Byte1('Z')

識別訊息類型。 當後端準備好進行新的查詢週期時,就會發送 ReadyForQuery。

Int32(5)

訊息內容的長度(以位元組為單位),包括自身。

Byte1

目前的後端交易狀態指示器。 可能的值為 'I'(如果閒置,不在交易區塊中);'T'(如果在交易區塊中);或 'E'(如果在失敗的交易區塊中)(在區塊結束前,查詢將被拒絕)。

RowDescription (B) #
Byte1('T')

識別訊息為 row description。

Int32

訊息內容的長度(以位元組為單位),包括自身。

Int16

指定一行中的欄位數(可以為零)。

然後,對於每個欄位,都有以下內容

字串

欄位名稱。

Int32

如果該欄位可以識別為特定表格的欄位,則為該表格的物件 ID;否則為零。

Int16

如果該欄位可以識別為特定表格的欄位,則為該欄位的屬性編號;否則為零。

Int32

欄位資料類型的物件 ID。

Int16

資料類型大小(請參閱 pg_type.typlen)。 請注意,負值表示可變寬度類型。

Int32

類型修飾符(請參閱 pg_attribute.atttypmod)。 修飾符的含義是類型特定的。

Int16

用於該欄位的格式代碼。 目前將為零(文字)或一(二進制)。 在從 Describe 的語句變體返回的 RowDescription 中,格式代碼尚不為人知,並且將始終為零。

SASLInitialResponse (F) #
Byte1('p')

識別訊息為初始 SASL 回應。請注意,這也用於 GSSAPI、SSPI 和密碼回應訊息。確切的訊息類型是從上下文中推斷出來的。

Int32

訊息內容的長度(以位元組為單位),包括自身。

字串

用戶端選擇的 SASL 身份驗證機制的名稱。

Int32

後面的 SASL 機制特定「Initial Client Response」的長度,如果沒有 Initial Response,則為 -1。

Byten

SASL 機制特定的「Initial Response」。

SASLResponse (F) #
Byte1('p')

識別訊息為 SASL 回應。請注意,這也用於 GSSAPI、SSPI 和密碼回應訊息。確切的訊息類型可以從上下文中推斷出來。

Int32

訊息內容的長度(以位元組為單位),包括自身。

Byten

SASL 機制特定的訊息資料。

SSLRequest (F) #
Int32(8)

訊息內容的長度(以位元組為單位),包括自身。

Int32(80877103)

SSL請求代碼。選擇該值是為了使最高有效 16 位包含 1234,而最低有效 16 位包含 5679。(為了避免混淆,此代碼不得與任何協議版本號相同。)

StartupMessage (F) #
Int32

訊息內容的長度(以位元組為單位),包括自身。

Int32(196608)

協議版本號。 最高有效 16 位是主要版本號(此處描述的協議為 3)。 最低有效 16 位是次要版本號(此處描述的協議為 0)。

協議版本號之後是一個或多個參數名稱和值字串對。 需要一個零字節作為最後一個名稱/值對之後的終止符。 參數可以以任何順序出現。 user 是必需的,其他是可選的。 每個參數都指定為

字串

參數名稱。 目前識別的名稱有

user

要作為其連接的資料庫使用者名稱。 必填;沒有預設值。

database

要連接的資料庫。 預設為使用者名稱。

options

後端的命令行引數。 (不建議使用此方法,而建議設置單獨的執行時間參數。)此字串中的空格被認為是分隔引數,除非使用反斜線 (\) 逸出;寫入 \\ 以表示文字反斜線。

replication

用於在流式複寫模式下連接,在該模式下可以發出一小組複寫命令,而不是 SQL 語句。 值可以是 truefalsedatabase,預設值為 false。 有關詳細資訊,請參閱 第 53.4 節

除了上述參數外,還可以列出其他參數。 以 _pq_. 開頭的參數名稱保留用於協議擴展,而其他參數則被視為在後端啟動時要設置的執行時間參數。 這些設置將在後端啟動期間應用(如果在有的話,解析命令行引數之後),並且將充當會話預設值。

字串

參數值。

Sync (F) #
Byte1('S')

識別訊息為 Sync 命令。

Int32(4)

訊息內容的長度(以位元組為單位),包括自身。

Terminate (F) #
Byte1('X')

識別訊息為終止。

Int32(4)

訊息內容的長度(以位元組為單位),包括自身。

提交更正

如果您在文件中發現任何不正確、與特定功能的體驗不符或需要進一步說明的內容,請使用此表單來報告文件問題。