Форматы сообщений

В этом разделе подробно описывается формат каждого сообщения. Все сообщения помечены символами, обозначающими, какая сторона может их отправить: клиент (F, frontend), сервер (B, backend) или обе (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.

Authenticationss (B)

Byte1('R')

Определяет, что сообщение является запросом аутентификации.

Int32(8)

Длина содержимого сообщения в байтах, включая само поле длины.

Int32(7)

Указывает, что требуется аутентификация на базе GSSAPI.

AuthenticationSSPI (B)

Byte1('R')

Определяет, что сообщение является запросом аутентификации.

Int32(8)

Длина содержимого сообщения в байтах, включая само поле длины.

Int32(9)

Указывает, что требуется аутентификация на базе SSPI.

Authenticationsscontinue (B)

Byte1('R')

Определяет, что сообщение является запросом аутентификации.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

Int32(8)

Указывает, что это сообщение содержит данные GSSAPI или SSPI.

Byten

Данные аутентификации для GSSAPI или SSPI.

AuthenticationSASL (B)

Byte1('R')

Определяет, что сообщение является запросом аутентификации.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

Int32(10)

Указывает, что требуется аутентификация на базе SASL.

Тело сообщения представляет собой список механизмов аутентификации SASL в порядке предпочтений сервера. За последним именем механизма аутентификации должен стоять завершающий нулевой байт. Для каждого механизма передается следующее:

String

Имя механизма аутентификации 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

PID обслуживающего процесса.

Int32

Секретный ключ этого обслуживающего процесса.

Bind (F)

Byte1('B')

Определяет, что сообщение содержит команду Bind.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

String

Имя целевого портала (при пустой строке выбирается безымянный портал).

String

Имя исходного подготовленного оператора (при пустой строке выбирается безымянный подготовленный оператор).

Int16

Число кодов форматов следующих параметров (обозначается ниже символом C). Может равняться нулю, указывая, что параметров нет или все они используют формат по умолчанию (текстовый); либо одному, и тогда указанный код формата применяется ко всем параметрам; либо может равняться фактическому числу параметров.

Int16[C]

Код формата параметров. В настоящее время допускаются коды ноль (текстовый формат) или один (двоичный формат).

Int16

Число следующих значений параметров (может быть нулевым). Оно должно соответствовать числу параметров, необходимых для запроса.

Затем для каждого параметра отображается следующая пара полей:

Int32

Длина значения параметра, в байтах (сам счетчик длины не считается). Может равняться нулю. В качестве особого случая -1 указывает на значение NULL. В случае NULL никакие байты значений далее не следуют.

Byten

Значение параметра в формате, указанном соответствующим кодом формата. Переменная n задает длину значения.

За последним параметром отображаются следующие поля:

Int16

Число кодов форматов для следующих столбцов результата (обозначается ниже символом R). Может равняться нулю, указывая, что столбцов результата нет или для них для всех должен использоваться формат по умолчанию (текстовый); либо одному, и тогда указанный код формата применяется ко всем столбцам результата (если таковые имеются); либо может равняться фактическому числу столбцов результата запроса.

Int16[R]

Код формата столбцов результата. В настоящее время допускаются коды ноль (текстовый формат) или один (двоичный формат).

BindComplete (B)

Byte1('2')

Определяет, что сообщение сигнализирует о завершении Bind.

Int32(4)

Длина содержимого сообщения в байтах, включая само поле длины.

CancelRequest (F)

Int32(16)

Длина содержимого сообщения в байтах, включая само поле длины.

Int32 (80877102)

Код запроса на отмену. Это значение отбирается так, чтобы содержать 1234 в старших 16 битах и 5678 в младших 16 битах. (Во избежание путаницы этот код не должен совпадать с номером версии протокола.)

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

Командный тег. Обычно это одно слово, определяющее, какая команда SQL была завершена.

Для команды INSERT в качестве тега передается INSERT oid число_строк, где число_строк — это количество вставленных строк. В поле oid передавался идентификатор объекта вставленной строки, если число_строк было равно 1 и в целевой таблице содержались OID, но системные столбцы с OID больше не поддерживаются; поэтому oid всегда равно 0.

Для команды DELETE в качестве тега передается DELETE число_строк, где число_строк — это количество удаленных строк.

Для команды UPDATE в качестве тега передается UPDATE число_строк, где число_строк — это количество обновленных строк.

Для команды SELECT или CREATE TABLE AS в качестве тега передается SELECT число_строк, где число_строк — это количество извлеченных строк.

Для команды MOVE в качестве тега передается MOVE число_строк, где число_строк — это количество строк, на которое изменилась позиция курсора.

Для команды FETCH в качестве тега передается FETCH число_строк, где число_строк — это количество строк, извлеченных через курсор.

Для команды COPY в качестве тега передается COPY число_строк, где число_строк — это количество скопированных строк.

CopyData (F и B)

Byte1('d')

Определяет, что в сообщении передаются данные COPY.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

Byten

Данные, образующие часть потока данных 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 указывает, что для всей операции COPY применяется двоичный формат (подобный формату DataRow). Дополнительную информацию см. в описании команды COPY.

Int16

Количество столбцов в копируемых данных (обозначается ниже символом N).

Int16[N]

Код формата для всех столбцов. В настоящее время допускаются коды ноль (текстовый формат) или один (двоичный формат). Если для всей операции копирования применяется текстовый формат, все эти коды должны быть равны нулю.

CopyOutResponse (B)

Byte1('H')

Определяет, что сообщение содержит ответ на запуск исходящего копирования. За этим сообщением последуют данные операции исходящего копирования.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

Int8

Int16

Количество столбцов в копируемых данных (обозначается ниже символом N).

Int16[N]

CopyBothResponse (B)

Byte1('W')

Определяет, что сообщение содержит ответ на запуск двустороннего копирования. Это сообщение используется только для потоковой репликации.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

Int8

Int16

Количество столбцов в копируемых данных (обозначается ниже символом N).

Int16[N]

DataRow (B)

Byte1('D')

Определяет, что сообщение содержит строку данных.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

Int16

Число последующих значений столбцов (может равняться нулю).

Затем для каждого столбца отображается следующая пара полей:

Int32

Длина значения столбца, в байтах (сам счетчик длины не считается). Может равняться нулю. В качестве особого случая -1 указывает на значение NULL. В случае NULL никакие байты значений далее не следуют.

Byten

Значение столбца в формате, определенном соответствующим кодом формата. Переменная n задает длину значения.

Describe (F)

Byte1('D')

Определяет, что сообщение содержит команду Describe.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

Byte1

'S' для описания подготовленного оператора или 'P' для описания портала.

String

Имя готового оператора или портала, описание которого запрашивается (при пустой строке выбирается безымянный подготовленный оператор или портал).

EmptyQueryResponse (B)

Byte1('I')

Определяет, что сообщение содержит ответ на пустую строку запроса. (Это сообщение заменяет CommandComplete.)

Int32(4)

Длина содержимого сообщения в байтах, включая само поле длины.

ErrorResponse (B)

Byte1('E')

Определяет, что сообщение об ошибке.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

Тело сообщения состоит из одного или нескольких определенных полей, за которыми идет завершающий нулевой байт. Поля могут отображаться в любом порядке. Для каждого поля передается следующее:

Byte1

Код, определяющий тип поля; ноль обозначает конец сообщения, после которого не следует никаких строк. Типы полей, определенные в настоящее время, перечислены в разделе Поля сообщений с ошибками и замечаниями. Поскольку в будущем могут добавиться и другие типы полей, клиенты должны просто игнорировать поля нераспознанного типа.

String

Значение поля.

Execute (F)

Byte1('E')

Определяет, что сообщение содержит команду Execute.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

String

Имя портала, подлежащего выполнению (при пустой строка выбирается безымянный портал).

Int32

Максимальное число строк, которое должно быть возвращено, если портал содержит запрос, возвращающий строки (в противном случае игнорируется). Ноль означает «без ограничений».

Flush (F)

Byte1('H')

Определяет, что сообщение содержит команду Flush.

Int32(4)

Длина содержимого сообщения в байтах, включая само поле длины.

FunctionCall (F)

Byte1('F')

Определяет, что сообщение содержит вызов функции.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

Int32

Задает идентификатор объекта вызываемой функции.

Int16

Число кодов форматов следующих аргументов (обозначается ниже символом C). Может равняться нулю, указывая, что аргументов нет или для них для всех должен использоваться формат по умолчанию (текстовый); либо одному, и тогда указанный код формата применяется ко всем аргументам; либо может равняться фактическому числу аргументов.

Int16[C]

Код формата аргументов. В настоящее время допускаются коды ноль (текстовый формат) или один (двоичный формат).

Int16

Задает число аргументов, передаваемых функции.

Затем для каждого аргумента отображается следующая пара полей:

Int32

Длина значения аргумента, в байтах (сам счетчик длины не считается). Может равняться нулю. В качестве особого случая -1 указывает на значение NULL. В случае NULL никакие байты значений далее не следуют.

Byten

Значение аргумента в формате, определенном соответствующим кодом формата. Переменная n задает длину значения.

За последним аргументом идет следующее поле:

Int16

Код формата результата функции. В настоящее время допускаются коды ноль (текстовый формат) или один (двоичный формат).

FunctionCallResponse (B)

Byte1('V')

Определяет что сообщение содержит результат вызова функции.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

Int32

Длина значения результата функции, в байтах (сам счетчик длины не считается). Может равняться нулю. В качестве особого случая -1 указывает на значение NULL. В случае NULL никакие байты значений далее не следуют.

Byten

Значение результата функции в формате, определенном соответствующим кодом формата. Переменная n задает длину значения.

GSSResponse (F)

Byte1('p')

Определяет, что сообщение содержит ответ GSSAPI или SSPI. Обратите внимание, что оно также используется для ответов SASL и при аутентификации пароля. Точный тип сообщения можно определить из контекста.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

Byten

Данные сообщения, специфичные для GSSAPI/SSPI.

NegotiateProtocolVersion (B)

Byte1('v')

Определяет, что сообщение содержит согласование версии протокола.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

Int32

Новейшая младшая версия протокола, поддерживаемая сервером, для запрошенной клиентом старшей версии.

Int32

Число параметров протокола, не распознанных сервером.

Затем для параметров протокола, не распознанного сервером, передается следующее:

String

Имя параметра.

NoData (B)

Byte1('n')

Определяет, что сообщение сигнализирует об отсутствии данных.

Int32(4)

Длина содержимого сообщения в байтах, включая само поле длины.

NoticeResponse (B)

Byte1('N')

Определяет, что сообщение содержит замечание.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

Byte1

String

Значение поля.

NotificationResponse (B)

Byte1('A')

Определяет, что сообщение содержит уведомление.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

Int32

PID обслуживающего процесса, отправляющего уведомление.

String

Имя канала, для которого было выдано уведомление.

String

Строка «информационного наполнения», сопровождающего уведомление.

ParameterDescription (B)

Byte1('t')

Определяет, что сообщение содержит описание параметра.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

Int16

Число параметров, используемых оператором (может равняться нулю).

Затем для каждого параметра передается следующее:

Int32

Задает идентификатор объекта типа данных параметра.

ParameterStatus (B)

Byte1('S')

Определяет, что сообщение содержит отчет о состоянии параметра времени выполнения.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

String

Имя параметра времени выполнения, состояние которого передается.

String

Текущее значение параметра.

Parse (F)

Byte1('P')

Определяет, что сообщение содержит команду Parse.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

String

Имя целевого подготовленного оператора (при пустой строке выбирается безымянный подготовленный оператор).

String

Строка запроса, подлежащая разбору.

Int16

Число заданных типов данных параметров (может равняться нулю). Обратите внимание, что это значение представляет не число параметров, которые могут отображаться в строке запроса, а число параметров, для которых клиент хочет предварительно задать типы.

Затем для каждого параметра передается следующее:

Int32

Задает идентификатор объекта типа данных параметра. Указание нулевого значения равнозначно отсутствию указания типа.

ParseComplete (B)

Byte1('1')

Определяет, что сообщение сигнализирует о завершении Parse.

Int32(4)

Длина содержимого сообщения в байтах, включая само поле длины.

PasswordMessage (F)

Byte1('p')

Определяет, что сообщение содержит пароль. Обратите внимание, что оно также используется для ответов GSSAPI, SSPI и SASL. Точный тип сообщения можно определить из контекста.

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

Если поле можно определить как столбец определенной таблицы, идентификатор объекта таблицы; в противном случае — ноль.

Int16

Если поле можно определено как столбец определенной таблицы, то номер атрибута для этого столбца; в противном случае ноль.

Int32

Идентификатор объекта типа данных поля.

Int16

Размер типа данных (см. pg_type.typlen). Обратите внимание, что отрицательные значения означают, что тип имеет переменную ширины.

Int32

Модификатор типа (см. pg_attribute.atttypmod). Смысл модификатора зависит от типа.

Int16

Код формата для данного поля. В настоящее время допускаются коды ноль (текстовый формат) или один (двоичный формат). В сообщении RowDescription, возвращаемом Describe в варианте оператора, код формата еще не известен и всегда будет равен нулю.

SASLInitialResponse (F)

Byte1('p')

Определяет, что сообщение содержит начальный ответ SASL. Обратите внимание, что оно также используется для ответов GSSAPI, SSPI и при аутентификации по паролю. Точный тип сообщения определяется из контекста.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

String

Имя механизма аутентификации SASL, выбранного клиентом.

Int32

Длина последующего сообщения «Начальный ответ клиента», специфичного для механизма SASL, либо -1, если начального ответа нет.

Byten

Данные сообщения «Начальный ответ», специфичные для механизма SASL.

SASLResponse (F)

Byte1('p')

Определяет, что сообщение содержит ответ SASL. Обратите внимание, что оно также используется для ответов GSSAPI, SSPI и при аутентификации по паролю. Точный тип сообщения можно определить из контекста.

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

Byten

Данные сообщения, специфичные для механизма SASL.

SSLRequest (F)

Int32(8)

Длина содержимого сообщения в байтах, включая само поле длины.

Int32 (80877103)

Код запроса SSL. Это значение отбирается так, чтобы содержать 1234 в старших 16 битах и 5679 в младших 16 битах. (Во избежание путаницы этот код не должен совпадать с номером версии протокола.)

GSSENCRequest (F)

Int32(8)

Длина содержимого сообщения в байтах, включая само поле длины.

Int32 (80877104)

Код запроса GSSAPI Encryption. Это значение отбирается так, чтобы содержать 1234 в старших 16 битах и 5680 в младших 16 битах. (Во избежание путаницы этот код не должен совпадать с номером версии протокола.)

StartupMessage (F)**

Int32

Длина содержимого сообщения в байтах, включая само поле длины.

Int32(196608)

Номер версии протокола. В старших 16 битах задается старший номер версии, в младших 16 битах — младший.

За номером версии протокола следует одна или несколько пар из имени параметра и строки его значения. За последней парой имя/значение должен стоять завершающий нулевой байт. Параметры могут отображаться в любом порядке. Обязательным является только параметр user, остальные могут отсутствовать. Каждый параметр задается так:

String

Имя параметра. В настоящее время принимаются имена:

user

Имя пользователя базы данных, с которым выполняется подключение. Является обязательным; значения по умолчанию нет.

database

База данных, к которой выполняется подключение. По умолчанию используется имя пользователя.

options

Аргументы командной строки для обслуживающего процесса. (Этот способ не рекомендуется; лучше устанавливать отдельные параметры времени выполнения.) Пробелы в этой строке воспринимаются как отдельные аргументы, если не экранировать их обратным слэшем (\); чтобы представить обратный слэш буквально, нужно его продублировать (\\).

replication

Используется для подключения в режиме потоковой репликации, где вместо операторов SQL может выполняться небольшой набор команд репликации. Допустимые значение: true, false (по умолчанию) и database.

В дополнение к вышеуказанным могут задаваться и другие параметры. Имена параметров, начинающиеся с _pq_., зарезервированы для использования в качестве расширений протокола, а остальные воспринимаются как параметры времени выполнения, которые задаются во время запуска сервера. Такие параметры будут применяться при запуске обслуживающего процесса (после разбора аргументов командной строки, если таковые имеются) и будут действовать как параметры сеанса по умолчанию.

String

Значение параметра.

Sync (F)

Byte1('S')

Определяет, что сообщение содержит команду Sync.

Int32(4)

Длина содержимого сообщения в байтах, включая само поле длины.

Terminate (F)

Byte1('X')

Определяет, что сообщение завершает сеанс.

Int32(4)

Длина содержимого сообщения в байтах, включая само поле длины.