Функции, показывающие состояние подключения

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

Совет
Разработчики приложений libpq должны тщательно поддерживать абстракцию PGconn. Чтобы изучить содержимое PGconn, используйте описанные ниже функции доступа. Обращение к внутренним полям PGconn через libpq-int.h не рекомендуется, поскольку они могут измениться в будущем.

Следующие функции возвращают значения параметров, установленных при подключении. Эти значения фиксируются на время существования соединения. Если используется строка подключения с несколькими хостами, значения PQhost, PQport и PQpass могут измениться, если производится новое подключение с тем же объектом PGconn. Другие значения фиксируются на время существования объекта PGconn.

PQdb

Возвращает имя базы данных, с которой установлено соединение.

char *PQdb(const PGconn *conn);

PQuser

Возвращает имя пользователя, установившего соединение.

char *PQuser(const PGconn *conn);

PQpass

Возвращает пароль, использованный при подключении.

char *PQpass(const PGconn *conn);

PQpass вернет либо пароль, заданный в параметрах подключения, либо, если таковой отсутствует, пароль, полученный из файла паролей. В последнем случае, если в параметрах подключения было указано несколько хостов, полагаться на результат PQpass нельзя, пока не установится соединение. Состояние подключения можно проверить с помощью функции PQstatus.

PQhost

Возвращает имя сервера активного соединения. Это может быть имя хоста, IP-адрес или путь к каталогу, если подключение производится через сокет Unix. (Вариант с путем можно отличить благодаря тому, что это всегда будет абсолютный путь, начинающийся с /.)

char *PQhost(const PGconn *conn);

Если в параметрах подключения был задан и host, и hostaddr, то PQhost вернет информацию из host. Если был задан только hostaddr, то вернется его значение. если в параметрах подключения было задано несколько хостов, PQhost возвращает хост, с которым фактически было установлено соединение.

Функция PQhost возвращает NULL, если аргумент conn равен NULL. В противном случае при ошибке во время получения информации о хосте (это возможно, если соединение не было установлено до конца или произошла ошибка), она возвращает пустую строку.

Если в параметрах подключения было указано несколько хостов, полагаться на результат PQhost нельзя, пока не установится соединение. Состояние подключения можно проверить с помощью функции PQstatus.

PQhostaddr

Возвращает IP-адрес сервера активного соединение. Это может быть адрес, в который разрешилось имя хоста, или IP-адрес, предоставленный посредством параметра hostaddr.

char *PQhostaddr(const PGconn *conn);

Функция PQhostaddr возвращает NULL, если аргумент conn равен NULL. В противном случае при ошибке во время получения информации о хосте (это возможно, если соединение не было установлено до конца или произошла ошибка), она возвращает пустую строку.

PQport

Возвращает порт активного соединения.

char *PQport(const PGconn *conn);

Если в параметрах подключения было задано несколько портов, функция PQport возвращает порт, к которому фактически произошло подключение.

Функция PQport возвращает NULL, если аргумент conn равен NULL. В противном случае при ошибке во время получения информации о хосте (это возможно, если соединение не было установлено до конца или произошла ошибка), она возвращает пустую строку.

Если в параметрах подключения было задано несколько портов, полагаться на результат PQport нельзя, пока не установится соединение. Состояние подключения можно проверить с помощью функции PQstatus.

PQtty

Сейчас эта функция ничего не делает, но оставлена для обратной совместимости. Она всегда возвращает пустую строку или NULL, если аргумент conn равен NULL.

char *PQtty(const PGconn *conn);

PQoptions

Возвращает параметры командной строки, переданные в запросе на подключение.

char *PQoptions(const PGconn *conn);

Следующие функции возвращают данные о состоянии, которое может измениться при выполнении операций на объекте PGconn.

PQstatus

Возвращает статус подключения.

ConnStatusType PQstatus(const PGconn *conn);

Статус может принимать одно из ряда значений. Однако только два из них видны извне процедуры асинхронного подключения: CONNECTION_OK and CONNECTION_BAD. Успешное подключение к базе данных имеет статус CONNECTION_OK. О неудавшейся попытке подключения сигнализирует статус CONNECTION_BAD. Обычно статус OK остается до вызова функции PQfinish, но ошибка связи может привести к преждевременной смене статуса на CONNECTION_BAD. В таком случае приложение может попытаться восстановить подключение, вызвав функцию PQreset.

О других кодах статуса, которые могут быть возвращены, можно узнать в описании функций PQconnectStartParams, PQconnectStart и PQconnectPoll.

PQtransactionStatus

Возвращает текущий статус сервера, касающийся транзакций.

PGTransactionStatusType PQtransactionStatus(const PGconn *conn);

Статус может быть PQTRANS_IDLE (в настоящее время простаивает), PQTRANS_ACTIVE (команда в процессе обработки), PQTRANS_INTRANS (простаивает, но находится в блоке действительной транзакции) или PQTRANS_INERROR (простаивает, но находится в блоке неудавшейся транзакции). Статус PQTRANS_UNKNOWN выводится, если соединение не работает. Статус PQTRANS_ACTIVE выводится, только когда запрос был отправлен серверу и еще не завершился.

PQparameterStatus

Отыскивает текущее значение параметра сервера.

const char *PQparameterStatus(const PGconn *conn, const char *paramName);

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

Параметры, выводимые в текущей версии, включают server_version, server_encoding, client_encoding, application_name, default_transaction_read_only, in_hot_standby, is_superuser, session_authorization, DateStyle, IntervalStyle, TimeZone, integer_datetimes, и standard_conforming_strings. Обратите внимание, что параметры server_version, server_encoding и integer_datetimes нельзя изменить после запуска.

Если для standard_conforming_strings не выводится никакого значения, приложения могут предположить, что оно равно off, то есть что обратные слэши в строковых литералах воспринимаются как управляющие символы. Кроме того, присутствие этого параметра можно считать указанием на то, что синтаксис строки с экранированием (E'...') является приемлемым.

Хотя возвращаемый указатель объявляется с квалификатором const, на самом деле он указывает на изменяемое хранилище, связанное со структурой PGconn. Неразумно предполагать, что этот указатель останется действительным при последующих запросах.

PQprotocolVersion

Запрашивает используемый клиент-серверный протокол.

int PQprotocolVersion(const PGconn *conn);

Приложения могут пожелать использовать эту функцию, чтобы определить, поддерживаются ли определенные функциональные возможности. В настоящее время возможными значениями являются 3 (протокол версии 3.0) или ноль (соединение не работает). Версия протокола не изменится после завершения операции подключения, но теоретически может измениться во время переподключения.

PQserverVersion

Возвращает целое число, представляющее версию сервера.

int PQserverVersion(const PGconn *conn);

Приложения могут использовать эту функцию, чтобы определить версию сервера баз данных, к которому они подключены. Результат формируется путем умножения основной версии сервера на 10000 и добавления дополнительного номера версии. Например, версия 1.5 будет возвращена как 10005. Если соединение не работает, возвращается ноль.

Если номер версии состоит из трех чисел, то основную версию представляют первые два числа. Для таких версий функция PQserverVersion использует для каждой части по две цифры; например, версия 1.4.1 будет возвращена как 10401.

Таким образом, для получения логического номера основной версии, чтобы определить совместимость функционала, приложения должны разделить результат PQserverVersion на 100, а не на 10000. Во всех выпускаемых сериях номера дополнительных версий (с исправлениями) отличаются только двумя последними цифрами.

PQerrorMessage

Возвращает последнее сообщение об ошибке, сгенерированное операцией в данном соединении.

char *PQerrorMessage(const PGconn *conn);

Почти все функции libpq в случае сбоя будут передавать сообщение для функции PQerrorMessage. Обратите внимание, что по соглашению libpq непустой результат PQerrorMessage может состоять из нескольких строк и будет включать завершающий символ перевода строки. Вызывающая функция не должна напрямую освобождать память, выделенную под результат. Она освободится, когда связанный с ней описатель PGconn будет передан функции PQfinish. Не следует ожидать, что результирующая строка останется той же самой после нескольких операций со структурой PGconn.

PQsocket

Получает номер дескриптора файла сокета соединения с сервером. Допустимый дескриптор будет больше или равен 0; результат -1 показывает, что в данный момент не открыто ни одно соединение с сервером. (Это значение не изменится во время обычной работы, но может измениться во время установки или переустановки подключения.)

int PQsocket(const PGconn *conn);

PQbackendPID

Возвращает ID серверного процесса (PID), обрабатывающего это соединение.

int PQbackendPID(const PGconn *conn);

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

PQconnectionNeedsPassword

Возвращает true (1), если методу аутентификации соединения требовался пароль, но тот не был предоставлен. Возвращает false (0), если пароль не требовался.

int PQconnectionNeedsPassword(const PGconn *conn);

Эту функцию можно применить после неудавшейся попытки подключения, чтобы решить, запросить ли у пользователя пароль.

PQconnectionUsedPassword

Возвращает true (1), если метод аутентификации соединения использовал пароль. Возвращает false (0), если это не так.

int PQconnectionUsedPassword(const PGconn *conn);

Эту функцию можно применить как после неудавшейся, так и после успешной попытки подключения, чтобы определить, требовал ли сервер ввести пароль.
.

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

PQsslInUse

Возвращает true (1), если для подключения используется SSL, и false (0), если не используется.

int PQsslInUse(const PGconn *conn);

PQsslAttribute

Возвращает связанную с SSL информацию о подключении.

const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);

Список доступных атрибутов зависит от использованной библиотеки SSL и типа подключения. Если атрибут недоступен, возвращает NULL.

Как правило, доступны следующие атрибуты:

  • library
    Имя используемой реализации SSL. (В настоящее время реализуется только "OpenSSL")

  • protocol
    Используемая версия SSL/TLS. Принятые значения: "TLSv1", "TLSv1.1" и "TLSv1.2", но реализация может возвращать и другие строки, если используется какой-то другой протокол.

  • key_bits
    Количество битов в ключе, используемом алгоритмом шифрования.

  • cipher
    Краткое имя используемой комбинации шифров, например, "DHE-RSA-DES-CBC3-SHA". Эти имена у каждой реализации SSL свои.

  • compression
    Возвращает "on", если используется сжатие SSL; в противном случае возвращает "off".

PQsslAttributeNames

Возвращает массив имен доступных атрибутов SSL. Этот массив завершается указателем NULL.

const char * const * PQsslAttributeNames(const PGconn *conn);

PQsslStruct

Возвращает указатель на специфичный для реализации SSL объект, описывающий подключение.

void *PQsslStruct(const PGconn *conn, const char *struct_name);

Доступная структура (или структуры) зависит от используемой реализации SSL. Для OpenSSL существует одна структура, доступная под именем «OpenSSL», и эта функция возвращает указатель на структуру OpenSSL типа SSL. Чтобы применить эту функцию, можно воспользоваться кодом со следующими строками:

#include <libpq-fe.h>
#include <openssl/ssl.h>

...

    SSL *ssl;

    dbconn = PQconnectdb(...);
    ...

    ssl = PQsslStruct(dbconn, "OpenSSL");
    if (ssl)
    {
        /* использовать функции OpenSSL для обращения к ssl */
    }

Эту структуру можно использовать для проверки уровней шифрования, проверки сертификатов сервера и т. д. Информацию об этой структуре см. в документации по OpenSSL.

PQgetssl

Возвращает структуру SSL, использовавшуюся при подключении, или NULL, если SSL не используется.

void *PQgetssl(const PGconn *conn);

Эта функция равнозначна PQsslStruct(conn, "OpenSSL"). Ее не следует применять в новых приложениях, поскольку возвращаемая структура специфична для OpenSSL и не будет доступна в случае использования другой реализации SSL. Чтобы проверить, использует ли подключение SSL, вызовите вместо нее PQsslInUse, а чтобы получить более подробную информацию о подключении — PQsslAttribute.

Copyright © KVANTOM LLC, 2019-2023