31.2. Функции статуса подключения#

31.2. Функции статуса подключения
31.2. Функции статуса подключения
Назад НаверхГлава 31. libpq — C БиблиотекаНачало Далее

31.2. Функции статуса подключения #

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

Подсказка

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 и 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, если параметр неизвестен.

Параметры, сообщаемые в текущем выпуске, включают:

application_nameis_superuser
client_encodingscram_iterations
DateStyleserver_encoding
default_transaction_read_onlyserver_version
in_hot_standbysession_authorization
integer_datetimesstandard_conforming_strings
IntervalStyleTimeZone

(server_encoding, TimeZone и integer_datetimes не сообщались в выпусках до 8.0; standard_conforming_strings не сообщались в выпусках до 8.1; IntervalStyle не сообщались в выпусках до 8.4; application_name не сообщались в выпусках до 9.0; default_transaction_read_only и in_hot_standby не сообщались в выпусках до 14; scram_iterations не сообщались в выпусках до 16.) Обратите внимание, что server_version, server_encoding и integer_datetimes не могут изменяться после запуска.

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

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

PQprotocolVersion #

Интеррогирует используемый протокол между клиентом и сервером. 

int PQprotocolVersion(const PGconn *conn);

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

PQserverVersion #

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

int PQserverVersion(const PGconn *conn);

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

До основной версии 10 PostgreSQL использовал трехчастные номера версий, в которых первые две части вместе представляли основную версию. Для этих версий PQserverVersion использует две цифры для каждой части; например, версия 9.1.5 будет возвращена как 90105, а версия 9.2.0 будет возвращена как 90200.

Поэтому, для определения совместимости функций, приложения должны делить результат 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);

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

PQconnectionUsedGSSAPI #

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

int PQconnectionUsedGSSAPI(const PGconn *conn);

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

Следующие функции возвращают информацию, связанную с 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, если соединение не использует SSL или указанное имя атрибута не определено для используемой библиотеки.

Следующие атрибуты обычно доступны:

library

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

protocol

Версия SSL/TLS, используемая. Обычные значения это "TLSv1", "TLSv1.1" и "TLSv1.2", но реализация может возвращать другие строки, если используется другой протокол.

key_bits

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

cipher

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

compression

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

В качестве особого случая, атрибут library может быть запрошен без подключения, передавая NULL в качестве аргумента conn. Результатом будет имя библиотеки SSL по умолчанию или NULL, если libpq был скомпилирован без поддержки SSL. (До версии 15 Tantor SE-1C передача NULL в качестве аргумента conn всегда приводила к NULL. Клиентские программы, которым необходимо различать новые и старые реализации этого случая, могут проверить макрос LIBPQ_HAS_SSL_LIBRARY_DETECTION).

PQsslAttributeNames #

Возвращает массив имен атрибутов SSL, которые могут быть использованы в PQsslAttribute(). Массив завершается нулевым указателем. 

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

Если conn имеет значение NULL, возвращаются атрибуты, доступные для библиотеки SSL по умолчанию, или пустой список, если libpq был скомпилирован без поддержки SSL. Если conn не NULL, возвращаются атрибуты, доступные для используемой библиотеки SSL для соединения, или пустой список, если соединение не зашифровано.

PQsslStruct #

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

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

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

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

...

    SSL *ssl;

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

    ssl = PQsslStruct(dbconn, "OpenSSL");
    if (ssl)
    {
        /* use OpenSSL functions to access ssl */
    }

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

PQgetssl #

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

void *PQgetssl(const PGconn *conn);

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

Назад Наверх Далее
31.1. Функции управления подключением к базе данных Начало 31.3. Функции выполнения команд