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

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

Byten
Данные аутентификации GSSAPI.

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

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

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

CopyOutResponse (B)

Byte1('H')
Показывает, что это сообщение является ответом на запуск исходящего копирования. За этим сообщением последуют данные исходящего копирования.

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

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

CopyBothResponse (B)

Byte1('W')
Показывает, что это сообщение является ответом на запуск двустороннего копирования. Это сообщение используется только для потоковой репликации.

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

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 задает длину значения (см. выше).

GSSENCRequest (F)

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

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

GSSResponse (F)

Byte1('p')
Показывает, что это сообщение является ответом GSSAPI. Обратите внимание, что оно также используется для ответных сообщений при аутентификации SASL и по паролю. Конкретный тип сообщения можно определить из контекста.

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

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

NegotiateProtocolVersion (B)

Byte1('v')
Показывает, что это сообщение согласования версии протокола.

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

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

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

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

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

NoData (B)

Byte1('n')
Показывает, что это сообщение, сигнализирующее об отсутствии данных.

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

NoticeResponse (B)

Byte1('N')
Показывает, что это сообщение является замечанием.

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

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 и 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 и по паролю. Конкретный тип сообщения определяется из контекста.

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

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

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

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

SASLResponse (F)

Byte1('p')
Показывает, что это сообщение является ответом SASL. Обратите внимание, что оно также используется для ответных сообщений при аутентификации GSSAPI и по паролю. Конкретный тип сообщения определяется из контекста.

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

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

SSLRequest (F)

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

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

StartupMessage (F)

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

Int32(196608)
Номер версии протокола. Старшие 16 битов являются основным номером версии (3 для протокола, описываемого здесь). Младшие 16 битов являются дополнительным номером версии (0 для протокола, описываемого здесь).

За номером версии протокола следуют одна или несколько пар из имени параметра и строки значения. За последней парой имя/значение должен следовать завершающий нулевой байт. Параметры могут идти в любом порядке. Обязательным является параметр 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)
Длина содержимого сообщения в байтах, включая само поле длины.