32.1. Функции управления подключением к базе данных#

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

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

32.1.1. Строки подключения
32.1.2. Ключевые слова параметров

Следующие функции отвечают за установление соединения с сервером базы данных Tantor SE. Приложение может иметь несколько открытых соединений с сервером одновременно. (Одна из причин для этого - доступ к нескольким базам данных). Каждое соединение представлено структурой PGconn. объект, который получается из функции PQconnectdb, PQconnectdbParams или PQsetdbLogin. Обратите внимание, что эти функции всегда возвращают указатель на ненулевой объект, если, возможно, не хватает памяти даже для выделения объекта PGconn. Функцию PQstatus следует вызывать для проверки возвращаемого значения успешного подключения перед отправкой запросов через объект подключения.

Предупреждение

Если ненадежные пользователи имеют доступ к базе данных, которая не приняла безопасный шаблон использования схем, начните каждую сессию с удаления общедоступных схем из search_path. Можно установить параметр ключевого слова options со значением -csearch_path=. В качестве альтернативы можно выполнить PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)") после подключения. Это соображение не является специфичным для libpq; оно применимо к любому интерфейсу для выполнения произвольных SQL-команд.

Предупреждение

На Unix, создание процесса с открытыми соединениями libpq может привести к непредсказуемым результатам, поскольку родительский и дочерний процессы разделяют одни и те же сокеты и ресурсы операционной системы. По этой причине такое использование не рекомендуется, хотя выполнение функции exec из дочернего процесса для загрузки нового исполняемого файла безопасно.

PQconnectdbParams

Устанавливает новое соединение с сервером базы данных. 

PGconn *PQconnectdbParams(const char * const *keywords,
                          const char * const *values,
                          int expand_dbname);

Эта функция открывает новое подключение к базе данных, используя параметры, взятые из двух NULL-терминированных массивов. Первый, keywords, определен как массив строк, каждая из которых является ключевым словом. Второй, values, задает значение для каждого ключевого слова. В отличие от PQsetdbLogin ниже, набор параметров может быть расширен без изменения сигнатуры функции, поэтому использование этой функции (или ее неблокирующих аналогов PQconnectStartParams и PQconnectPoll) предпочтительно для нового программирования приложений.

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

Все переданные массивы могут быть пустыми, чтобы использовать все параметры по умолчанию, или могут содержать одну или несколько настроек параметров. Они должны быть одинаковой длины. Обработка остановится при первом вхождении NULL в массиве keywords. Кроме того, если значение values, связанное с ненулевым значением keywords, является NULL или пустой строкой, это значение будет проигнорировано, и обработка продолжится с следующей парой элементов массива.

Когда expand_dbname не равно нулю, значение для первого ключевого слова dbname проверяется, чтобы увидеть, является ли оно строкой подключения. Если это так, оно “расширяется” в отдельные параметры подключения, извлеченные из строки. Значение считается строкой подключения, а не просто именем базы данных, если оно содержит знак равенства (=) или начинается с указателя схемы URI. (Подробнее о форматах строки подключения см. в разделе Раздел 32.1.1). Только первое вхождение dbname обрабатывается таким образом; любой последующий параметр dbname обрабатывается как обычное имя базы данных.

В общем случае массивы параметров обрабатываются от начала до конца. Если ключевое слово повторяется, используется последнее значение (которое не является NULL или пустым). Это правило особенно применяется, когда ключевое слово, найденное в строке подключения, конфликтует с ключевым словом, появляющимся в массиве keywords. Таким образом, программист может определить, могут ли элементы массива переопределять или быть переопределены значениями, взятыми из строки подключения. Элементы массива, появляющиеся перед расширенным параметром dbname, могут быть переопределены полями строки подключения, и в свою очередь эти поля переопределяются элементами массива, появляющимися после параметра dbname (но только если эти элементы предоставляют непустые значения).

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

PQconnectdb

Устанавливает новое соединение с сервером базы данных. 

PGconn *PQconnectdb(const char *conninfo);

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

Переданная строка может быть пустой, чтобы использовать все параметры по умолчанию, или она может содержать одну или несколько настроек параметров, разделенных пробелами, или она может содержать URI. См. Раздел 32.1.1 для получения подробной информации.

PQsetdbLogin

Устанавливает новое соединение с сервером базы данных. 

PGconn *PQsetdbLogin(const char *pghost,
                     const char *pgport,
                     const char *pgoptions,
                     const char *pgtty,
                     const char *dbName,
                     const char *login,
                     const char *pwd);

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

Если тег dbName содержит знак = или имеет допустимый префикс подключения URI, он рассматривается как строка conninfo точно так же, как если бы он был передан в PQconnectdb, а оставшиеся параметры затем применяются так, как указано для PQconnectdbParams.

pgtty больше не используется и любое переданное значение будет проигнорировано.

PQsetdb

Устанавливает новое соединение с сервером базы данных. 

PGconn *PQsetdb(char *pghost,
                char *pgport,
                char *pgoptions,
                char *pgtty,
                char *dbName);

Это макрос, который вызывает PQsetdbLogin с нулевыми указателями для параметров login и pwd. Он предоставляется для обратной совместимости с очень старыми программами.

PQconnectStartParams
PQconnectStart
PQconnectPoll

Установите соединение с сервером базы данных в неблокирующем режиме. 

PGconn *PQconnectStartParams(const char * const *keywords,
                             const char * const *values,
                             int expand_dbname);

PGconn *PQconnectStart(const char *conninfo);

PostgresPollingStatusType PQconnectPoll(PGconn *conn);

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

С помощью тега PQconnectStartParams устанавливается соединение с базой данных, используя параметры, взятые из массивов keywords и values, и управляемое параметром expand_dbname, как описано выше для PQconnectdbParams.

С помощью функции PQconnectStart создается соединение с базой данных, используя параметры, взятые из строки conninfo, как описано выше для PQconnectdb.

Ни PQconnectStartParams ни PQconnectStart ни PQconnectPoll не будут блокировать, при условии соблюдения ряда ограничений:

  • Параметр hostaddr должен быть использован правильно, чтобы избежать выполнения DNS-запросов. См. документацию по этому параметру в Раздел 32.1.2 для получения подробной информации.

  • Если вы вызываете PQtrace, убедитесь, что объект потока, в который вы осуществляете трассировку, не будет блокироваться.

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

Для начала неблокирующего запроса на подключение вызовите функцию PQconnectStart или PQconnectStartParams. Если результат равен null, то libpq не смог выделить новую структуру PGconn. В противном случае будет возвращен действительный указатель на PGconn (хотя пока еще не представляющий действительное подключение к базе данных). Затем вызовите PQstatus(conn). Если результат равен CONNECTION_BAD, то попытка подключения уже не удалась, обычно из-за недопустимых параметров подключения.

Если функция PQconnectStart или PQconnectStartParams успешно выполняется, следующим этапом является опрос libpq, чтобы он мог продолжить последовательность подключения. Используйте функцию PQsocket(conn), чтобы получить дескриптор сокета, лежащего в основе соединения с базой данных. (Осторожно: не предполагайте, что сокет остается тем же самым при вызовах PQconnectPoll). Повторяйте следующий цикл: ЕслиPQconnectPoll в последний раз вернула PGRES_POLLING_READING, подождите, пока сокет будет готов к чтению (как указано функцией select(), poll() или аналогичной системной функцией). Затем снова вызовите PQconnectPoll(conn). Соответственно, если PQconnectPoll(conn) в последний раз вернула PGRES_POLLING_WRITING, подождите, пока сокет будет готов к записи, затем снова вызовите PQconnectPoll(conn). На первой итерации, то есть, если вы еще не вызывали PQconnectPoll(conn), ведите себя так, как если бы она в последний раз вернула PGRES_POLLING_WRITING. Продолжайте этот цикл, пока PQconnectPoll(conn) не вернет PGRES_POLLING_FAILED, указывающий на неудачу процедуры подключения, или PGRES_POLLING_OK, указывающий на успешное установление соединения.

В любой момент соединения можно проверить его состояние, вызвав функцию PQstatus. Если эта функция возвращает значение CONNECTION_BAD, то процедура соединения завершилась неудачно; если функция возвращает значение CONNECTION_OK, то соединение готово. Оба этих состояния можно определить по возвращаемому значению функции PQconnectPoll, описанной выше. Во время (и только во время) асинхронной процедуры соединения могут возникать и другие состояния. Они указывают на текущий этап процедуры соединения и могут быть полезны, например, для обратной связи с пользователем. Эти состояния:

CONNECTION_STARTED

Ожидание установления соединения.

CONNECTION_MADE

Соединение установлено; ожидание отправки.

CONNECTION_AWAITING_RESPONSE

Ожидание ответа от сервера.

CONNECTION_AUTH_OK

Получена аутентификация; ожидание завершения запуска бэкенда.

CONNECTION_SSL_STARTUP

Установка SSL шифрования.

CONNECTION_SETENV

Согласование параметров, зависящих от окружения.

CONNECTION_CHECK_WRITABLE

Проверка возможности подключения для обработки записи транзакций.

CONNECTION_CONSUME

Сохранение всех сообщений ответа на подключении.

Обратите внимание, что, хотя эти константы останутся (для поддержания совместимости), приложение никогда не должно полагаться на их порядок или наличие, или на то, что статус всегда будет одним из этих документированных значений. Приложение может сделать что-то вроде этого: 

switch(PQstatus(conn))
{
        case CONNECTION_STARTED:
            feedback = "Connecting...";
            break;

        case CONNECTION_MADE:
            feedback = "Connected to server...";
            break;
.
.
.
        default:
            feedback = "Connecting...";
}

Время ожидания подключения connect_timeout игнорируется при использовании PQconnectPoll; это ответственность приложения решить, прошло ли слишком много времени. В противном случае, последовательное выполнение PQconnectStart и цикла PQconnectPoll эквивалентно PQconnectdb.

Обратите внимание, что когда PQconnectStart или PQconnectStartParams возвращает ненулевой указатель, вы должны вызвать PQfinish, когда закончите работу с ним, чтобы освободить структуру и все связанные блоки памяти. Это необходимо сделать даже в случае неудачной попытки подключения или ее отмены.

PQconndefaults

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

PQconninfoOption *PQconndefaults(void);

typedef struct
{
    char   *keyword;   /* The keyword of the option */
    char   *envvar;    /* Fallback environment variable name */
    char   *compiled;  /* Fallback compiled in default value */
    char   *val;       /* Option's current value, or NULL */
    char   *label;     /* Label for field in connect dialog */
    char   *dispchar;  /* Indicates how to display this field
                          in a connect dialog. Values are:
                          ""        Display entered value as is
                          "*"       Password field - hide value
                          "D"       Debug option - don't show by default */
    int     dispsize;  /* Field size in characters for dialog */
} PQconninfoOption;

Возвращает массив параметров подключения. Это может быть использовано для определения всех возможных параметров PQconnectdb и их текущих значений по умолчанию. Возвращаемое значение указывает на массив структур PQconninfoOption, который заканчивается записью с указателем keyword равным null. Если память не может быть выделена, возвращается null указатель. Обратите внимание, что текущие значения по умолчанию (val) зависят от переменных среды и другого контекста. Отсутствующий или недопустимый файл службы будет молча проигнорирован. Вызывающие функции должны рассматривать данные параметров подключения как доступные только для чтения.

После обработки массива опций освободите его, передав его в PQconninfoFree. Если этого не сделать, для каждого вызова PQconndefaults будет утекать небольшое количество памяти.

PQconninfo

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

PQconninfoOption *PQconninfo(PGconn *conn);

Возвращает массив параметров подключения. Это может быть использовано для определения всех возможных параметров PQconnectdb и значений, которые были использованы для подключения к серверу. Возвращаемое значение указывает на массив структур PQconninfoOption, который заканчивается записью с нулевым указателем keyword. Все замечания, указанные выше для PQconndefaults, также применимы к результату PQconninfo.

PQconninfoParse

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

PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);

Разбирает строку подключения и возвращает полученные параметры в виде массива; или возвращает NULL, если возникла проблема со строкой подключения. Эта функция может использоваться для извлечения параметров PQconnectdb в предоставленной строке подключения. Возвращаемое значение указывает на массив структур PQconninfoOption, который заканчивается записью с нулевым указателем на keyword.

Все допустимые параметры будут присутствовать в результирующем массиве, но для параметра PQconninfoOption, отсутствующего в строке подключения, значение val будет установлено в NULL; значения по умолчанию не вставляются.

Если errmsg не равно NULL, то *errmsg устанавливается в NULL в случае успеха, иначе в malloc'd строку ошибки, объясняющую проблему. (Также возможно, что *errmsg устанавливается в NULL, а функция возвращает NULL; это указывает на состояние нехватки памяти).

После обработки массива опций, освободите его, передав его в PQconninfoFree. Если этого не сделать, для каждого вызова PQconninfoParse будет утекать некоторая память. Соответственно, если происходит ошибка и errmsg не равно NULL, обязательно освободите строку ошибки с помощью PQfreemem.

PQfinish

Закрывает соединение с сервером. Также освобождает память, используемую объектом PGconn. 

void PQfinish(PGconn *conn);

Обратите внимание, что даже если попытка подключения к серверу не удалась (как указано в PQstatus), приложение должно вызвать PQfinish для освобождения памяти, используемой объектом PGconn. Указатель PGconn не должен использоваться снова после вызова PQfinish.

PQreset

Сбрасывает канал связи с сервером. 

void PQreset(PGconn *conn);

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

PQresetStart
PQresetPoll

Сбросьте канал связи с сервером в неблокирующем режиме. 

int PQresetStart(PGconn *conn);

PostgresPollingStatusType PQresetPoll(PGconn *conn);

Эти функции закрывают соединение с сервером и пытаются установить новое соединение, используя все те же ранее использованные параметры. Это может быть полезно для восстановления после ошибки, если рабочее соединение было потеряно. Они отличаются от PQreset (выше) тем, что действуют в неблокирующем режиме. Эти функции страдают от тех же ограничений, что и PQconnectStartParams, PQconnectStart и PQconnectPoll.

Для инициирования сброса соединения вызовите PQresetStart. Если он возвращает 0, сброс не удался. Если он возвращает 1, проверьте сброс, используя функцию PQresetPoll точно так же, как вы бы создали соединение, используя функцию PQconnectPoll.

PQpingParams

PQpingParams сообщает о состоянии сервера. Он принимает параметры подключения, идентичные тем, что описаны выше для PQconnectdbParams. Для получения состояния сервера не обязательно указывать правильное имя пользователя, пароль или имя базы данных; однако, если будут предоставлены неправильные значения, сервер зарегистрирует неудачную попытку подключения. 

PGPing PQpingParams(const char * const *keywords,
                    const char * const *values,
                    int expand_dbname);

Функция возвращает одно из следующих значений:

PQPING_OK

Сервер работает и, по-видимому, принимает соединения.

PQPING_REJECT

Сервер работает, но находится в состоянии, которое не позволяет устанавливать соединения (запуск, остановка или восстановление после сбоя).

PQPING_NO_RESPONSE

Сервер не может быть связан. Это может указывать на то, что сервер не запущен, или что есть проблема с заданными параметрами подключения (например, неправильный номер порта), или что есть проблема с сетевым подключением (например, брандмауэр блокирует запрос на подключение).

PQPING_NO_ATTEMPT

Не была предпринята попытка связаться с сервером, поскольку предоставленные параметры явно неверны или возникла проблема на стороне клиента (например, нехватка памяти).

PQping

PQping сообщает о состоянии сервера. Он принимает параметры подключения, идентичные тем, что описаны выше для PQconnectdb. Для получения состояния сервера не обязательно указывать правильное имя пользователя, пароль или имя базы данных; однако, если будут предоставлены неправильные значения, сервер зарегистрирует неудачную попытку подключения. 

PGPing PQping(const char *conninfo);

Возвращаемые значения такие же, как и для PQpingParams.

PQsetSSLKeyPassHook_OpenSSL

PQsetSSLKeyPassHook_OpenSSL позволяет приложению переопределить libpq's стандартную обработку зашифрованных файлов ключей клиентского сертификата с использованием sslpassword или интерактивного запроса. 

void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);

Приложение передает указатель на функцию обратного вызова с сигнатурой: 

int callback_fn(char *buf, int size, PGconn *conn);

который libpq затем вызовет вместо своего стандартного обработчика PQdefaultSSLKeyPassHook_OpenSSL. Обратный вызов должен определить пароль для ключа и скопировать его в буфер результата buf размером size. Строка в buf должна быть завершена нулевым символом. Обратный вызов должен вернуть длину пароля, сохраненного в buf, исключая нулевой символ. В случае ошибки обратный вызов должен установить buf[0] = '\0' и вернуть 0. См. PQdefaultSSLKeyPassHook_OpenSSL в исходном коде libpq для примера.

Если пользователь указал явное расположение ключа, его путь будет находиться в conn->sslkey при вызове обратного вызова. Он будет пустым, если используется путь к ключу по умолчанию. Для ключей, которые являются указателями на движок, реализации движка могут использовать обратный вызов пароля OpenSSL или определить свою собственную обработку.

Приложение обратного вызова может выбрать делегировать необработанные случаи PQdefaultSSLKeyPassHook_OpenSSL, или вызвать его первым и попробовать что-то другое, если он возвращает 0, или полностью переопределить его.

Обратный вызов не должен использовать исключения, longjmp(...) и т. д. для управления нормальным потоком выполнения. Он должен завершиться нормально.

PQgetSSLKeyPassHook_OpenSSL

PQgetSSLKeyPassHook_OpenSSL возвращает текущую функцию обратного вызова для пароля ключа клиентского сертификата или NULL, если она не была установлена. 

PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);

32.1.1. Строки подключения

Несколько функций libpq разбирают строку, указанную пользователем, чтобы получить параметры подключения. Существуют два принятых формата для этих строк: простые строки ключ/значение и URI. URI обычно следуют RFC 3986, за исключением того, что допускаются строки подключения с несколькими хостами, как дополнительно описано ниже.

32.1.1.1. Ключевое слово/Значение строки подключения

В формате ключевое слово/значение каждая настройка параметра имеет вид keyword = value, с пробелом(и) между настройками. Пробелы вокруг знака равенства настройки являются необязательными. Чтобы записать пустое значение или значение, содержащее пробелы, заключите его в одинарные кавычки, например keyword = 'a value'. Одинарные кавычки и обратные слеши внутри значения должны быть экранированы обратным слешем, т.е. \' и \\.

Пример: 

host=localhost port=5432 dbname=mydb connect_timeout=10

Распознаваемые ключевые слова параметров перечислены в Раздел 32.1.2.

32.1.1.2. URI подключения

Общий формат для подключения URI выглядит так: 

postgresql://[userspec@][hostspec][/dbname][?paramspec]

where userspec is:

user[:password]

and hostspec is:

[host][:port][,...]

and paramspec is:

name=value[&...]

Схема обозначения URI может быть либо postgresql://, либо postgres://. Каждая из оставшихся частей URI является необязательной. Ниже приведены примеры правильного синтаксиса URI: 

postgresql://
postgresql://localhost
postgresql://localhost:5433
postgresql://localhost/mydb
postgresql://user@localhost
postgresql://user:secret@localhost
postgresql://other@localhost/otherdb?connect_timeout=10&application_name=myapp
postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application_name=myapp

Значения, которые обычно появляются в иерархической части URI, могут быть заданы в виде именованных параметров. Например: 

postgresql:///mydb?host=localhost&port=5433

Все именованные параметры должны соответствовать ключевым словам, перечисленным в Раздел 32.1.2, за исключением того, что для совместимости с соединениями JDBC URI экземпляры ssl=true переводятся в sslmode=require.

Соединение URI должно быть закодировано с использованием процентного кодирования, если оно содержит символы с особым значением в любой из его частей. Вот пример, где знак равенства (=) заменен на %3D, а пробел - на %20: 

postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff

Часть с хостом может быть либо именем хоста, либо IP-адресом. Чтобы указать IPv6-адрес, заключите его в квадратные скобки: 

postgresql://[2001:db8::1234]/database

Часть с хостом интерпретируется так, как описано для параметра host. В частности, выбирается соединение через Unix-доменный сокет, если часть с хостом либо пуста, либо выглядит как абсолютный путь, в противном случае инициируется соединение TCP/IP. Однако следует отметить, что слэш является зарезервированным символом в иерархической части URI. Поэтому, чтобы указать нестандартный каталог Unix-доменного сокета, либо опустите часть с хостом URI и укажите хост как именованный параметр, либо примените процентную кодировку пути в части с хостом URI: 

postgresql:///dbname?host=/var/lib/postgresql
postgresql://%2Fvar%2Flib%2Fpostgresql/dbname

Возможно указать несколько компонентов хоста, каждый из которых может иметь необязательный компонент порта, в одном URI. URI вида postgresql://host1:port1,host2:port2,host3:port3/ эквивалентен строке подключения вида host=host1,host2,host3 port=port1,port2,port3. Как далее описано, каждый хост будет пробоваться по очереди, пока не будет успешно установлено соединение.

32.1.1.3. Указание нескольких хостов

Возможно указать несколько хостов для подключения, чтобы они были попробованы в указанном порядке. В формате Ключ/Значение, параметры host, hostaddr и port принимают значения, разделенные запятыми. В каждом указанном параметре должно быть указано одинаковое количество элементов, так что, например, первый hostaddr соответствует первому имени хоста, второй hostaddr соответствует второму имени хоста и так далее. Исключение составляет случай, когда указан только один port, он применяется ко всем хостам.

В формате URI подключения вы можете перечислить несколько пар host:port, разделенных запятыми в компоненте host URI.

В любом формате одно имя хоста может соответствовать нескольким сетевым адресам. Обычным примером является хост, у которого есть и IPv4-адрес, и IPv6-адрес.

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

Если используется файл паролей, вы можете иметь разные пароли для разных хостов. Все остальные параметры подключения одинаковы для каждого хоста в списке; невозможно, например, указать разные имена пользователей для разных хостов.

32.1.2. Ключевые слова параметров

В настоящее время распознаваемыми ключевыми словами параметров являются:

host

Имя хоста, к которому нужно подключиться. Если имя хоста выглядит как абсолютный путь, то это указывает на использование межпроцессного взаимодействия Unix-домена вместо TCP/IP-соединения; значение представляет собой имя каталога, в котором хранится файл сокета. (В Unix абсолютный путь начинается с косой черты. В Windows также распознаются пути, начинающиеся с буквы диска). Если имя хоста начинается с @, оно считается сокетом Unix-домена в абстрактном пространстве имен (в настоящее время поддерживается в Linux и Windows). Поведение по умолчанию, когда host не указан или пуст, заключается в подключении к сокету Unix-домена. в /tmp (или в любой другой каталог сокетов, указанный при сборке Tantor SE). На Windows и на машинах без сокетов Unix-домена, соединение по умолчанию устанавливается с localhost.

Также принимается список имен хостов, разделенных запятыми, в котором каждое имя хоста в списке пробуется по порядку; пустой элемент в списке выбирает поведение по умолчанию, как объяснено выше. См. Раздел 32.1.1.3 для получения подробной информации.

hostaddr

Числовой IP-адрес хоста, к которому нужно подключиться. Он должен быть в стандартном формате IPv4, например, 172.28.40.9. Если ваша машина поддерживает IPv6, вы также можете использовать эти адреса. Всегда используется TCP/IP-соединение, когда для этого параметра указана непустая строка. Если этот параметр не указан, значение host будет искаться для определения соответствующего IP-адреса, или, если host указывает IP-адрес, то этот адрес будет использоваться напрямую.

Использование тега hostaddr позволяет приложению избежать поиска имени хоста, что может быть важным в приложениях с ограниченным временем. Однако, для методов аутентификации GSSAPI или SSPI, а также для проверки SSL-сертификата с использованием verify-full, требуется указание имени хоста. Применяются следующие правила:

  • Если указан тег host без тега hostaddr, выполняется поиск имени хоста. (При использовании функции PQconnectPoll поиск выполняется, когда функция PQconnectPoll впервые рассматривает это имя хоста, и это может привести к блокировке функции PQconnectPoll на значительное время).

  • Если hostaddr указан без host, значение для hostaddr представляет собой сетевой адрес сервера. Попытка подключения завершится неудачей, если метод аутентификации требует имя хоста.

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

Обратите внимание, что аутентификация, скорее всего, не выполнится, если host не является именем сервера по сетевому адресу hostaddr. Кроме того, когда указаны оба параметра host и hostaddr, host используется для идентификации соединения в файле паролей (см. Раздел 32.16).

Также принимается список значений hostaddr, разделенных запятыми, в котором каждый хост из списка пробуется по порядку. Пустой элемент в списке приводит к использованию соответствующего имени хоста или имени хоста по умолчанию, если оно также пусто. Подробности см. в разделе Раздел 32.1.1.3.

Без указания имени хоста или адреса хоста, libpq будет подключаться с использованием локального сокета домена Unix; или на Windows и на машинах без сокетов домена Unix, он будет пытаться подключиться к localhost.

port

Номер порта для подключения к хосту сервера или расширение имени файла сокета для подключений в Unix-домене. Если в параметрах host или hostaddr указано несколько хостов, этот параметр может указывать список портов, разделенных запятыми, такой же длины, как список хостов, или может указывать один номер порта, который будет использоваться для всех хостов. Пустая строка или пустой элемент в списке, разделенном запятыми, указывает на номер порта по умолчанию, установленный при построении Tantor SE.

dbname

Имя базы данных. По умолчанию совпадает с именем пользователя. В некоторых контекстах значение проверяется на наличие расширенных форматов; см. Раздел 32.1.1 для получения дополнительной информации о них.

user

Tantor SE имя пользователя для подключения. По умолчанию будет таким же, как имя операционной системы пользователя, запускающего приложение.

password

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

passfile

Указывает имя файла, используемого для хранения паролей (см. Раздел 32.16). По умолчанию используется ~/.pgpass, или %APPDATA%\postgresql\pgpass.conf в Microsoft Windows. (Если этот файл не существует, ошибка не сообщается).

channel_binding

Эта опция управляет использованием клиентом привязки канала. Значение require означает, что соединение должно использовать привязку канала, prefer означает, что клиент выберет привязку канала, если она доступна, а disable предотвращает использование привязки канала. По умолчанию, если Tantor SE скомпилирован с поддержкой SSL, значение по умолчанию - prefer, в противном случае значение по умолчанию - disable.

Привязка канала - это метод, с помощью которого сервер аутентифицирует себя перед клиентом. Он поддерживается только в SSL-соединениях с серверами Tantor SE версии 11 или выше, использующими метод аутентификации SCRAM.

connect_timeout

Максимальное время ожидания подключения, в секундах (записывается в виде десятичного целого числа, например, 10). Нулевое, отрицательное или не указанное значение означает бесконечное ожидание. Минимально допустимое значение тайм-аута составляет 2 секунды, поэтому значение 1 интерпретируется как 2. Этот тайм-аут применяется отдельно к каждому имени хоста или IP-адресу. Например, если вы указываете два хоста и значение connect_timeout равно 5, каждый хост будет отключаться, если подключение не будет установлено в течение 5 секунд, поэтому общее время ожидания подключения может составить до 10 секунд.

compression

Запрос на сжатие трафика libpq. Клиент отправляет запрос с перечислением алгоритмов сжатия. Клиент может запросить сжатие, включив опцию "compression" в строке подключения. Это может быть логическое значение для включения или отключения сжатия ("true"/"false", "on"/"off", "yes"/"no", "1"/"0"), "any" или явное перечисление алгоритмов сжатия, разделенных запятыми, которые могут включать уровень сжатия ("zlib,lz4:2"). Если сжатие включено, но алгоритм явно не указан, клиентская библиотека отправляет свой полный список поддерживаемых алгоритмов. Сервер пересекает полученные алгоритмы сжатия с разрешенными (управляется через настройку сервера libpq_compression). Если пересечение не пусто, сервер отвечает с сообщением CompressionAck, содержащим окончательный список алгоритмов сжатия, которые могут использоваться для сжатия сообщений libpq между клиентом и сервером. Если пересечение пусто (сервер не принимает ни один из запрошенных алгоритмов), то он отвечает с сообщением CompressionAck, содержащим пустой список, и клиент решает, продолжать ли без сжатия или сообщить об ошибке.

После отправки сообщения CompressionAck сервер может отправить сообщение SetCompressionMethod для установки текущего алгоритма сжатия для сжатия трафика от сервера к клиенту. После получения сообщения CompressionAck клиент может отправить сообщение SetCompressionMethod для установки текущего алгоритма сжатия для сжатия трафика от клиента к серверу. Сжатые данные передаются с помощью сообщений CompressedData.

Поддержка алгоритмов сжатия должна быть включена при компиляции сервера. В настоящее время поддерживаются две библиотеки: zlib (по умолчанию) и lz4 (если Postgres был настроен с опцией --with-lz4). В обоих случаях используется режим потоковой передачи. По умолчанию клиент не запрашивает сжатие. Обратите внимание, что использование сжатия вместе с SSL может создавать дополнительные уязвимости: CRIME

client_encoding

Это устанавливает параметр конфигурации client_encoding для данного соединения. В дополнение к значениям, принимаемым соответствующей опцией сервера, вы можете использовать auto, чтобы определить правильную кодировку из текущей локали в клиенте (переменная окружения LC_CTYPE в системах Unix).

options

Указывает параметры командной строки, которые будут отправлены на сервер при установлении соединения. Например, установка значения -c geqo=off устанавливает значение параметра geqo в сессии на off. Пробелы внутри этой строки считаются разделителями аргументов командной строки, если они не экранированы обратной косой чертой (\); для представления буквальной обратной косой черты используйте \\. Для подробного обсуждения доступных параметров см. Глава 19.

application_name

Указывает значение для параметра конфигурации application_name.

fallback_application_name

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

keepalives

Определяет, используются ли клиентские TCP keepalive. Значение по умолчанию - 1, что означает включено, но вы можете изменить его на 0, что означает выключено, если keepalive не требуется. Этот параметр игнорируется для соединений, установленных через Unix-доменный сокет.

keepalives_idle

Управляет количеством секунд бездействия, после которого TCP должен отправить сообщение keepalive на сервер. Значение нуль использует системное значение по умолчанию. Этот параметр игнорируется для соединений, установленных через Unix-доменный сокет или если keepalives отключены. Он поддерживается только на системах, где доступна опция сокета TCP_KEEPIDLE или эквивалентная ей, а также на Windows; на других системах он не имеет эффекта.

keepalives_interval

Управляет количеством секунд, через которое должно быть повторно отправлено сообщение TCP keepalive, которое не было подтверждено сервером. Значение ноль использует системное значение по умолчанию. Этот параметр игнорируется для соединений, установленных через Unix-доменный сокет, или если keepalive отключены. Он поддерживается только на системах, где доступна опция TCP_KEEPINTVL или эквивалентная опция сокета, а также на Windows; на других системах он не имеет эффекта.

keepalives_count

Определяет количество TCP keepalive-пакетов, которые могут быть потеряны, прежде чем соединение клиента с сервером будет считаться неработающим. Значение ноль использует системное значение по умолчанию. Этот параметр игнорируется для соединений, установленных через Unix-доменный сокет, или если keepalive отключены. Он поддерживается только на системах, где доступна опция сокета TCP_KEEPCNT или эквивалентная ей; на других системах он не имеет эффекта.

tcp_user_timeout

Определяет количество миллисекунд, в течение которых переданные данные могут оставаться без подтверждения, прежде чем соединение будет принудительно закрыто. Значение нуль использует системное значение по умолчанию. Этот параметр игнорируется для соединений, установленных через Unix-доменный сокет. Он поддерживается только на системах, где доступна опция TCP_USER_TIMEOUT; на других системах он не имеет эффекта.

replication

Этот параметр определяет, должно ли соединение использовать протокол репликации вместо обычного протокола. Именно этот протокол используют соединения репликации PostgreSQL, а также инструменты, такие как pg_basebackup, внутренне, но им может также пользоваться стороннее приложение. Для описания протокола репликации см. Раздел 53.4.

Поддерживаются следующие значения, которые нечувствительны к регистру:

true, on, yes, 1

Соединение переходит в режим физической репликации.

database

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

false, off, no, 0

Соединение является обычным, что является поведением по умолчанию.

В физическом или логическом режиме репликации может использоваться только простой протокол запросов.

gssencmode

Эта опция определяет, будет ли и с каким приоритетом установлено безопасное TCP/IP-соединение с сервером с использованием протокола GSS. Существуют три режима:

disable

только попробуйте незашифрованное подключение без GSSAPI

prefer (default)

если присутствуют учетные данные GSSAPI (т.е. в кеше учетных данных), сначала попробуйте установить зашифрованное соединение с использованием GSSAPI; если это не удается или учетных данных нет, попробуйте установить не зашифрованное соединение. Это является настройкой по умолчанию, когда Tantor SE был скомпилирован с поддержкой GSSAPI.

require

только попробуйте GSSAPI-зашифрованное соединение

gssencmode игнорируется при обмене данными через Unix-сокеты. Если Tantor SE скомпилирован без поддержки GSSAPI, использование опции require вызовет ошибку, в то время как опция prefer будет принята, но libpq фактически не будет пытаться установить зашифрованное соединение с использованием GSSAPI.

sslmode

Этот параметр определяет, будет ли и с каким приоритетом установлено безопасное TCP/IP-соединение с сервером с использованием SSL. Существует шесть режимов:

disable

только попробуйте не-SSL соединение

allow

попробуйте сначала незащищенное SSL подключение; если это не удастся, попробуйте защищенное SSL подключение

prefer (default)

Попробуйте сначала установить соединение с использованием SSL; если это не удастся, попробуйте установить не-SSL соединение.

require

только попробуйте установить соединение SSL. Если присутствует файл корневого CA, проверьте сертификат так же, как если бы был указан параметр verify-ca

verify-ca

только попробуйте установить соединение SSL и проверьте, что сертификат сервера выдан доверенным удостоверяющим центром (CA)

verify-full

только попробуйте установить соединение SSL, проверьте, что сертификат сервера выдан доверенным CA и что запрашиваемое имя сервера соответствует имени в сертификате

См. Раздел 32.19 для подробного описания того, как работают эти параметры.

sslmode игнорируется для обмена данными через Unix-сокет. Если Tantor SE скомпилирован без поддержки SSL, использование опций require, verify-ca или verify-full вызовет ошибку, в то время как опции allow и prefer будут приняты, но libpq фактически не будет пытаться установить SSL соединение.

Обратите внимание, что если возможно использование шифрования GSSAPI, то оно будет предпочтительнее использования шифрования SSL, независимо от значения параметра sslmode. Чтобы принудительно использовать шифрование SSL в среде, где работает инфраструктура GSSAPI (например, сервер Kerberos), также установите параметр gssencmode в значение disable.

requiressl

Этот параметр устарел в пользу настройки sslmode.

Если установлено значение 1, требуется SSL соединение с сервером (это эквивалентно sslmode require). libpq затем откажется подключаться, если сервер не принимает SSL соединение. Если установлено значение 0 (по умолчанию), libpq будет согласовывать тип соединения с сервером (эквивалентно sslmode prefer). Этот параметр доступен только если Tantor SE скомпилирован с поддержкой SSL.

sslcompression

Если установлено значение 1, данные, отправляемые по SSL-соединениям, будут сжиматься. Если установлено значение 0, сжатие будет отключено. По умолчанию установлено значение 0. Этот параметр игнорируется, если установлено соединение без SSL.

Сжатие SSL в настоящее время считается небезопасным, и его использование больше не рекомендуется. OpenSSL 1.1.0 по умолчанию отключает сжатие, и многие дистрибутивы операционных систем также отключают его в предыдущих версиях, поэтому установка этого параметра в значение on не будет иметь никакого эффекта, если сервер не принимает сжатие. Tantor SE 14 полностью отключает сжатие внутри сервера.

Если безопасность не является основной проблемой, сжатие может улучшить пропускную способность, если узким местом является сеть. Отключение сжатия может улучшить время отклика и пропускную способность, если ограничивающим фактором является производительность ЦП.

sslcert

Этот параметр указывает имя файла клиентского SSL-сертификата, заменяя значение по умолчанию ~/.postgresql/postgresql.crt. Этот параметр игнорируется, если не устанавливается SSL-соединение.

sslkey

Этот параметр указывает расположение секретного ключа, используемого для клиентского сертификата. Он может указывать имя файла, которое будет использоваться вместо значения по умолчанию ~/.postgresql/postgresql.key, или он может указывать ключ, полученный из внешнего “движка” (движки - это загружаемые модули OpenSSL). Спецификация внешнего движка должна состоять из имени движка, разделенного двоеточием, и идентификатора ключа, специфичного для движка. Этот параметр игнорируется, если не устанавливается SSL-соединение.

sslpassword

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

Спецификация этого параметра с любым непустым значением подавляет приглашение Enter PEM pass phrase: , которое OpenSSL будет выводить по умолчанию, когда предоставляется зашифрованный ключ клиентского сертификата libpq.

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

Не существует эквивалентной переменной среды для этой опции, и нет возможности найти ее в файле .pgpass. Она может быть использована в определении подключения в файле службы. Пользователи с более сложными потребностями должны рассмотреть использование механизмов OpenSSL и инструментов, таких как PKCS#11 или устройства для выгрузки криптографии через USB.

sslrootcert

Этот параметр указывает имя файла, содержащего сертификаты удостоверяющих центров (CA). Если файл существует, сертификат сервера будет проверен на подпись одним из этих удостоверяющих центров. По умолчанию используется файл ~/.postgresql/root.crt.

sslcrl

Этот параметр указывает имя файла списка отзыва сертификатов (CRL) SSL-сервера. Сертификаты, перечисленные в этом файле, если он существует, будут отклонены при попытке аутентификации сертификата сервера. Если ни sslcrl, ни sslcrldir не установлены, это значение принимается как ~/.postgresql/root.crl.

sslcrldir

Этот параметр определяет имя каталога списка отзыва сертификатов (CRL) SSL-сервера. Сертификаты, перечисленные в файлах в этом каталоге, если он существует, будут отклонены при попытке аутентификации сертификата сервера.

Для подготовки каталога необходимо выполнить команду OpenSSL openssl rehash или c_rehash. Подробности см. в его документации.

Оба тега sslcrl и sslcrldir могут быть указаны вместе.

sslsni

Если установлено значение 1 (по умолчанию), libpq устанавливает расширение TLS “Server Name Indication” (SNI) на подключениях, включенных SSL. Установка этого параметра в 0 отключает данную функцию.

Серверное имя индикации может использоваться SSL-совместимыми прокси-серверами для маршрутизации соединений без необходимости расшифровки SSL-потока. (Обратите внимание, что для этого требуется прокси-сервер, который знает о протоколе рукопожатия PostgreSQL, а не просто любой SSL-прокси). Однако, SNI делает имя целевого хоста видимым в открытом виде в сетевом трафике, поэтому в некоторых случаях это может быть нежелательно.

requirepeer

Этот параметр указывает имя пользователя операционной системы сервера, например requirepeer=postgres. При установлении соединения через Unix-доменный сокет, если этот параметр установлен, клиент проверяет в начале соединения, что процесс сервера работает от имени указанного пользователя; если это не так, соединение прерывается с ошибкой. Этот параметр может использоваться для обеспечения аутентификации сервера, аналогичной доступной с использованием SSL-сертификатов в TCP/IP-соединениях. (Обратите внимание, что если Unix-доменный сокет находится в /tmp или другом общедоступном месте для записи, любой пользователь может запустить сервер, слушающий его. Используйте этот параметр для обеспечения соединения с сервером, запущенным от имени доверенного пользователя). Эта опция поддерживается только на платформах, для которых реализован метод аутентификации peer; см. Раздел 20.9.

ssl_min_protocol_version

Этот параметр определяет минимальную версию протокола SSL/TLS, разрешенную для соединения. Допустимые значения: TLSv1, TLSv1.1, TLSv1.2 и TLSv1.3. Поддерживаемые протоколы зависят от версии OpenSSL, используемой, более старые версии не поддерживают самые современные версии протоколов. Если не указано, используется значение по умолчанию TLSv1.2, которое соответствует лучшим практикам отрасли на данный момент.

ssl_max_protocol_version

Этот параметр определяет максимальную версию протокола SSL/TLS, разрешенную для соединения. Допустимые значения: TLSv1, TLSv1.1, TLSv1.2 и TLSv1.3. Поддерживаемые протоколы зависят от версии OpenSSL, используемой, старые версии не поддерживают самые современные версии протоколов. Если не установлено, этот параметр игнорируется, и соединение будет использовать максимальную границу, определенную бэкендом, если она установлена. Установка максимальной версии протокола полезна в основном для тестирования или если у некоторого компонента возникают проблемы с работой с более новым протоколом.

krbsrvname

Имя службы Kerberos, используемое при аутентификации с помощью GSSAPI. Оно должно совпадать с именем службы, указанным в конфигурации сервера, чтобы аутентификация Kerberos прошла успешно. (См. также Раздел 20.6). Значение по умолчанию обычно postgres, но его можно изменить при сборке Tantor SE с помощью опции --with-krb-srvnam команды configure. В большинстве сред выполнения этот параметр не требует изменений. Некоторые реализации Kerberos могут требовать другого имени службы, например, Microsoft Active Directory, которая требует, чтобы имя службы было в верхнем регистре (POSTGRES).

gsslib

Используемая библиотека GSS для аутентификации GSSAPI. В настоящее время это не учитывается, за исключением сборок для Windows, которые включают поддержку как GSSAPI, так и SSPI. В этом случае установите значение gssapi, чтобы заставить libpq использовать библиотеку GSSAPI для аутентификации вместо используемого по умолчанию SSPI.

service

Имя службы для использования дополнительных параметров. Оно указывает имя службы в pg_service.conf, которая содержит дополнительные параметры подключения. Это позволяет приложениям указывать только имя службы, чтобы параметры подключения можно было централизованно поддерживать. См. Раздел 32.17.

target_session_attrs

Этот параметр определяет, должны ли сессии иметь определенные свойства, чтобы быть приемлемыми. Обычно он используется в сочетании с несколькими именами хостов для выбора первой приемлемой альтернативы среди нескольких хостов. Существует шесть режимов:

any (default)

любое успешное соединение допустимо

read-write

session должна по умолчанию принимать транзакции на чтение и запись (то есть сервер не должен находиться в режиме горячего резервирования и параметр default_transaction_read_only должен быть off)

read-only

сессия по умолчанию не должен принимать чтение-запись транзакции (наоборот)

primary

сервер не должен находиться в режиме горячего резервирования

standby

сервер должен находиться в режиме горячего резервирования

prefer-standby

сначала попробуйте найти резервный сервер, но если ни один из перечисленных хостов не является резервным сервером, попробуйте снова в режиме any

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