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

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

---

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

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

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

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

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

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

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

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

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

PQconnectdb #

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

PGconn *PQconnectdb(const char *conninfo);

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

Переданная строка может быть пустой, чтобы использовать все параметры по умолчанию, или она может содержать одну или несколько настроек параметров, разделенных пробелами, или она может содержать URI. См. Раздел 31.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-запросов. См. документацию по этому параметру в Раздел 31.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);

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

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

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

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

Пример:

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

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

31.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

Все именованные параметры должны соответствовать ключевым словам, перечисленным в Раздел 31.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. Как далее описано, каждый хост будет пробоваться по очереди, пока не будет успешно установлено соединение.

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

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

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

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

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

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

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

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

host #

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

Также принимается список имен хостов, разделенных запятыми, в котором каждое имя хоста в списке пробуется по порядку; пустой элемент в списке выбирает поведение по умолчанию, как объяснено выше. См. Раздел 31.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 используется для идентификации соединения в файле паролей (см. Раздел 31.16).

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

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

port #

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

dbname #

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

user #

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

password #

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

passfile #

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

require_auth #

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

Методы могут быть отрицательными с добавлением префикса !, в этом случае сервер не должен пытаться использовать указанный метод; любой другой метод принимается, и сервер может вообще не аутентифицировать клиента. Если предоставлен список, разделенный запятыми, сервер не может пытаться использовать любой из указанных отрицательных методов. Отрицательные и неотрицательные формы не могут быть объединены в одной настройке.

В качестве последнего особого случая, метод none требует, чтобы сервер не использовал запрос аутентификации. (Он также может быть отрицан, чтобы требовать какую-либо форму аутентификации.)

Могут быть указаны следующие методы:

password

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

md5

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

gss

Сервер должен либо запросить рукопожатие Kerberos через GSSAPI, либо установить GSS-зашифрованный канал (см. также gssencmode).

scram-sha-256

Сервер должен успешно завершить обмен аутентификацией SCRAM-SHA-256 с клиентом.

none

Сервер не должен запрашивать у клиента обмен аутентификацией. (Это не запрещает аутентификацию клиентского сертификата через TLS, а также аутентификацию GSS через его зашифрованный транспорт.)

channel_binding #

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

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

connect_timeout #

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

client_encoding #

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

options #

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

application_name #

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

fallback_application_name #

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

keepalives #

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

keepalives_idle #

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

keepalives_interval #

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

keepalives_count #

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

tcp_user_timeout #

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

replication #

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

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

true, on, yes, 1

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

database

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

false, off, no, 0

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

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

gssencmode #

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

disable

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

prefer (default)

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

require

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

gssencmode игнорируется при обмене данными через Unix-сокеты. Если Tantor BE скомпилирован без поддержки 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 и что запрашиваемое имя сервера соответствует имени в сертификате

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

sslmode игнорируется для обмена данными через Unix-сокет. Если Tantor BE скомпилирован без поддержки 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 BE скомпилирован с поддержкой SSL.

sslcompression #

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

Сжатие SSL в настоящее время считается небезопасным, и его использование больше не рекомендуется. OpenSSL 1.1.0 по умолчанию отключает сжатие, и многие дистрибутивы операционных систем также отключают его в предыдущих версиях, поэтому установка этого параметра в значение on не будет иметь никакого эффекта, если сервер не принимает сжатие. Tantor BE 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.

sslcertmode #

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

disable

Клиентский сертификат никогда не отправляется, даже если он доступен (по умолчанию или предоставлен через sslcert).

allow (default)

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

require

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

Примечание

sslcertmode=require не добавляет никакой дополнительной безопасности, так как нет гарантии, что сервер правильно проверяет сертификат; серверы PostgreSQL обычно запрашивают TLS сертификаты у клиентов, независимо от того, проверяют ли они их или нет. Эта опция может быть полезна при устранении неполадок в более сложных настройках TLS.

sslrootcert #

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

Специальное значение system может быть указано вместо этого, в этом случае будут загружены доверенные корневые сертификаты УЦ из реализации SSL. Точные расположения этих корневых сертификатов зависят от реализации SSL и платформы. Для OpenSSL в частности, расположения могут быть дополнительно изменены с помощью переменных окружения SSL_CERT_DIR и SSL_CERT_FILE.

Примечание

Когда используется sslrootcert=system, значение по умолчанию sslmode изменяется на verify-full, и любое более слабое значение приведет к ошибке. В большинстве случаев получить сертификат, доверенный системой, для контролируемого имени хоста не составляет труда, что делает verify-ca и все более ослабленные режимы бесполезными.

Магическое значение system будет иметь приоритет над локальным файлом сертификата с таким же именем. Если по какой-то причине вы оказались в этой ситуации, используйте альтернативный путь, например, sslrootcert=./system.

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; см. Раздел 19.8.

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 прошла успешно. (См. также Раздел 19.6). Значение по умолчанию обычно postgres, но его можно изменить при сборке Tantor BE с помощью опции --with-krb-srvnam команды configure. В большинстве сред выполнения этот параметр не требует изменений. Некоторые реализации Kerberos могут требовать другого имени службы, например, Microsoft Active Directory, которая требует, чтобы имя службы было в верхнем регистре (POSTGRES).

gsslib #

Библиотека GSS для использования при аутентификации GSSAPI. В настоящее время этот параметр игнорируется.

gssdelegation #

Перенаправить (делегировать) учетные данные GSS на сервер. По умолчанию 0, что означает, что учетные данные не будут перенаправлены на сервер. Установите это значение на 1, чтобы учетные данные перенаправлялись, когда это возможно.

service #

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

target_session_attrs #

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

any (default)

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

read-write

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

read-only

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

primary

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

standby

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

prefer-standby

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

load_balance_hosts #

Управляет порядком, в котором клиент пытается подключиться к доступным хостам и адресам. Как только попытка подключения будет успешной, другие хосты и адреса не будут пробоваться. Этот параметр обычно используется в сочетании с несколькими именами хостов или DNS-записью, которая возвращает несколько IP-адресов. Этот параметр можно использовать в сочетании с target_session_attrs для, например, балансировки нагрузки только на резервных серверах. После успешного подключения, последующие запросы на возвращенное соединение будут отправляться на тот же сервер. В настоящее время существует два режима:

disable (default)

Балансировка нагрузки между хостами не выполняется. Хосты проверяются в порядке их предоставления, а адреса проверяются в порядке их получения от DNS или файла hosts.

random

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

Хотя случайное балансирование нагрузки из-за своей случайной природы почти никогда не приводит к полностью равномерному распределению, оно статистически приближается к нему. Важный аспект здесь заключается в том, что этот алгоритм использует два уровня случайного выбора: сначала хосты будут разрешены в случайном порядке. Затем, перед разрешением следующего хоста, все разрешенные адреса для текущего хоста будут проверены в случайном порядке. Такое поведение может значительно исказить количество подключений, которые получает каждый узел, в определенных случаях, например, когда некоторые хосты разрешаются на большее количество адресов, чем другие. Но такое искажение также можно использовать намеренно, например, чтобы увеличить количество подключений, которые получает более крупный сервер, предоставляя его имя хоста несколько раз в строке хоста.

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

---

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