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

Все параметры, отчетливо видимые в текущей версии, включают 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_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). Обратите внимание, что server_version, server_encoding и integer_datetimes не могут изменяться после запуска.

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

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

PQprotocolVersion

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

int PQprotocolVersion(const PGconn *conn);

Приложения могут использовать эту функцию для определения поддержки определенных функций. В настоящее время возможные значения - 3 (протокол 3.0) или ноль (плохое соединение). Версия протокола не изменится после завершения запуска соединения, но теоретически она может измениться во время сброса соединения. Протокол 3.0 поддерживается серверными версиями Tantor BE 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);

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

Следующие функции возвращают информацию, связанную с 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 BE передача NULL в качестве аргумента conn всегда приводила к NULL. Клиентские программы, которым необходимо различать новые и старые реализации этого случая, могут проверить макрос LIBPQ_HAS_SSL_LIBRARY_DETECTION).

PQsslAttributeNames

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

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

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. Функции выполнения команд