32.2. Функции статуса подключения#
32.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 SE 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 SE передача 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
.