Техподдержка

4.1.1. Функции управления соединением с базой данных

ДОКУМЕНТАЦИЯ

Выберите версию, форк и язык для СУБД Digital Q.DataBase, чтобы прочитать или скачать всю документацию.

Новости

01.09.2026

СУБД Digital Q.DataBase можно развернуть из готового Docker-образа

25.08.2026

СУБД Digital Q.DataBase: 8 ядер бесплатно — до 1 сентября!

Документация

Диасофт
Авторские права © 2016–2025 ООО "Диасофт Экосистема"

Скачать всю документацию:

pdf (13 mБ) EPUB (13 mБ) CHM (14 МБ)

4.1.1. Функции управления соединением с базой данных

Содержание

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

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

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

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

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

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

PQconnectdbParams #

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

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

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

Список распознаваемых в настоящее время ключевых слов параметров приведен в Раздел 4.1.1.2.

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

Когда expand_dbname имеет ненулевое значение, значение первого dbname ключевого слова проверяется на предмет того, является ли оно строкой подключения. В этом случае оно развертывается «в отдельные» параметры подключения, извлеченные из строки. Значение считается строкой подключения, а не просто именем базы данных, если оно содержит знак равенства (=) или начинается с Обозначение схемы URI. (Более подробные сведения о форматах строк подключения приведены в Раздел 4.1.1.1.) Подобным образом обрабатывается только первое вхождение dbname is treated in this way; любой последующий dbname параметр обрабатывается как обычное имя базы данных.

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

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

функция PQconnectdb #

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

PGconn *PQconnectdb(const char *conninfo);

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

Для использования всех параметров по умолчанию передаваемая строка может быть пустой, либо она может содержать одну или несколько настроек параметров, разделенных пробелами, либо она может содержать URI. См. Раздел 4.1.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-запросов. См. описание данного параметра в Раздел 4.1.1.2 для получения подробных сведений.
При вызове функции PQtraceнеобходимо убедиться, что объект потока , в который выполняется трассировка, не будет блокироваться.
Необходимо обеспечить нахождение сокета в соответствующем состоянии перед вызовом функция PQconnectPoll, как описано ниже.

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

Если PQconnectStart или PQconnectStartParams завершается успешно, то следующим этапом является выполнение опроса, libpq необходимого для продолжения процедуры установления соединения. Для этого вызовите функцию PQsocket(объект conn), чтобы получить дескриптор сокета, используемого для соединения с базой данных. (Внимание: не следует полагать, что сокет остается неизменным при различных функция PQconnectPoll вызовах функции.) Цикл следует организовать так: если функция PQconnectPoll(объект conn) в последний раз возвратила значение PGRES_POLLING_READING, ожидайте готовности сокета на чтение (согласно результатам select(), poll(), или аналогичная системная функция). Обратите внимание, что PQsocketPoll позволяет сократить объём шаблонного кода за счёт абстрагирования настройки select(2) или poll(2) если она доступна в используемой системе. Затем вызовите функцию функция PQconnectPoll(объект conn) снова. И наоборот, если функция PQconnectPoll(объект conn) в последний раз возвратила значение PGRES_POLLING_WRITING, подождите до готовности сокета к записи, а затем вызовите функция PQconnectPoll(объект conn) снова. На первой итерации, то есть если вы ещё не вызывали функцию функция PQconnectPoll, действуйте так, как если бы последним возвращённым значением было 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_GSS_STARTUP #: Согласование GSS-шифрования.
CONNECTION_CHECK_WRITABLE #: Проверка возможности выполнения транзакций записи в данном соединении.
CONNECTION_CHECK_STANDBY #: Проверка того, находится ли целевой сервер в режиме ожидания.
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 по окончании работы с ним, чтобы освободить структуру и все связанные с ней блоки памяти. Это необходимо сделать, даже если соединение попытка завершается неудачей или прерывается.

PQsocketPoll #

Выполните опрос дескриптора сокета, используемого соединением и полученного с помощью PQsocket. Основное назначение данной функции заключается в итеративном обходе процесса соединения последовательность, описанная в документации к PQconnectStartParams.

typedef pg_int64 pg_usec_time_t;

int PQsocketPoll(int sock, int forRead, int forWrite,
                 pg_usec_time_t end_time);

Данная функция выполняет опрос дескриптора файла, в том числе с возможностью задания тайм-аута. Если forRead имеет ненулевое значение, то функция завершит работу, когда сокет будет готов для чтения. Если параметр forWrite имеет ненулевое значение, функция завершит работу в тот момент, когда сокет будет готов для записи.

Тайм-аут задается параметром end_time, который — это время прекращения ожидания, выраженное в количестве микросекунд, прошедших с начала эпохи Unix (то есть, time_t умноженное на 1 миллион). Время ожидания бесконечно, если параметр end_time развертывается -1. Ожидание завершается немедленно (без блокировки), если параметр параметр end_time равен 0 (или любому моменту времени до текущего). Значения тайм-аута удобно вычислять, добавляя необходимое количество микросекунд к результату функции PQgetCurrentTimeUSec. Следует учитывать, что базовые системные вызовы могут иметь точность ниже микросекундной, в связи с чем фактическая задержка может быть неточной.

Функция возвращает значение больше 0 в случае, если указанное условие выполнено, 0 если время ожидания истекло, или -1 если произошла ошибка. Код ошибки можно получить из переменной errno(3) значение. В случае, если оба forRead и forWrite значения равны нулю, функция немедленно возвращает признак истечения времени ожидания.

PQsocketPoll реализована с использованием либо poll(2) или select(2), в зависимости от платформы. См. POLLIN и POLLOUT из poll(2), или readfds и writefds из select(2), для получения дополнительной информации.

PQconndefaults #

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

PQconninfoOption *PQconndefaults(void);

typedef struct
{
    char   *keyword;   /* Ключевое слово параметра */
    char   *envvar;    /* Имя резервной переменной окружения */
    char   *compiled;  /* Резервное значение по умолчанию, заданное при компиляции */
    char   *val;       /* Текущее значение параметра или значение NULL */
    char   *label;     /* Метка для поля в диалоговом окне соединения */
    char   *dispchar;  /* Указывает, как отображать данное поле
                          в диалоговом окне подключения. Возможные значения:
                          ""        Отображать введенное значение в исходном виде
                          "*"       Поле пароля — скрывать значение
                          "D"       Параметр отладки — не отображать по умолчанию */
    int     dispsize;  /* Размер поля в символах для диалогового окна */
} PQconninfoOption;

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

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

PQconninfo #

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

PQconninfoOption *PQconninfo(PGconn *conn);

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

PQconninfoParse #

Функция возвращает разобранные параметры соединения из предоставленной строки соединения.

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

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

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

Если errmsg не является значение NULL, то *errmsg принимает значение равным значение NULL в случае успешного выполнения; в противном случае — значение mallocвыделенной строки ошибки с описанием проблемы. (Также возможно, что *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 PQreset (см. выше) они отличаются тем, что работают в неблокирующем режиме. Для данных функций характерны те же ограничения, что и для функций PQconnectStart и PQconnectPoll. PQconnectStartParams, PQconnectStart и функция PQconnectPoll.

Чтобы инициировать сброс соединения, вызовите функцию PQresetStart. PQresetStart. Если функция возвращает 0, значит, сброс выполнить не удалось. Если функция возвращает 1, опрашивайте состояние сброса с помощью функции PQresetPoll. 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 затем будет вызывать библиотека libpq вместо своего стандартного PQdefaultSSLKeyPassHook_OpenSSL обработчика. Эта функция обратного вызова должна определить пароль для ключа и скопировать его в результирующий буфер buf размером size. Строка в параметре buf должна завершаться нулевым символом. Функция обратного вызова должна возвращать длину пароля, сохранённого в параметре buf, buf без учёта нулевого символа символ завершения. В случае ошибки функция обратного вызова должна установить buf[0] = '\0' и возвратить 0. См. PQdefaultSSLKeyPassHook_OpenSSL в libpqв качестве примера исходный код.

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

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

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

PQgetSSLKeyPassHook_OpenSSL #

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

PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);

4.1.1.1. Строки соединения #

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

4.1.1.1.1. Строки соединения в формате «ключ/значение» #

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

Пример:

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

Список поддерживаемых ключевых слов для параметров приведен в Раздел 4.1.1.2.

4.1.1.1.2. URI-адреса подключения #

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

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

где userspec имеет следующий вид:

user[:password]

и hostspec имеет следующий вид:

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

и paramspec имеет следующий вид:

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

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

Соединение URI необходимо закодировать с использованием percent-encoding если какая-либо из его частей содержит символы, имеющие специальное значение. Ниже приведен пример, в котором знак равенства (=) заменяется последовательностью %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. Как подробно описано ниже, попытка подключения к каждому узлу будет выполняться по очереди до тех пор, пока соединение не будет успешно установлено.

4.1.1.1.3. Указание нескольких узлов #

Для подключения можно указать несколько узлов, чтобы они опрашивались в заданном порядке. В формате «ключевое слово/значение» параметры host, hostaddr, и port принимают разделенные запятыми списки значений. В каждом из этих параметров должно быть указано одинаковое количество элементов указанного параметра, при этом, например, первый параметр соответствует первому имени хоста, hostaddr второй параметр — второму имени хоста и так hostaddr далее по порядку. В качестве исключения: если указан только один port параметр, он применяется ко всем хостам.

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

В любом из этих форматов одно имя хоста может соответствовать нескольким сетевым адресам. Распространённым примером такой ситуации является хост, имеющий как IPv4-, так и IPv6-адрес.

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

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

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

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

host #

Имя хоста для подключения. Если имя хоста выглядит как абсолютный путь имя, оно указывает на взаимодействие через сокеты домена Unix, а не через TCP/IP взаимодействия; значением является имя каталога, в котором хранится файл сокета. (В системе Unix абсолютный путь начинается с косой черты. В системе Windows также распознаются пути, начинающиеся с буквы диска.) Если имя узла начинается с @, оно трактуется как сокет домена Unix в абстрактном пространстве имен (в настоящее время поддерживается в Linux и Windows). Поведение по умолчанию, когда параметр host не указан или пуст, заключается в подключении к сокету домена Unix сокету в /tmp (или любой другой каталог сокетов, который был указан когда Digital Q.DataBase была собрана). В ОС Windows, по умолчанию выполняется подключение к localhost.

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

hostaddr #

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

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

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

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

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

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

port #

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

dbname #

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

user #

Digital Q.DataBase Имя пользователя для подключения. По умолчанию значение совпадает с именем пользователя в операционной системе, запустившего приложение.

password #

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

passfile #

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

require_auth #

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

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

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

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

password: Сервер должен запрашивать аутентификацию по паролю в открытом виде.
md5: Сервер должен запрашивать аутентификацию по паролю с хешированием MD5.
gss: Сервер должен либо запросить квитирование Kerberos через GSSAPI либо установить GSS-зашифрованный канал (см. также gssencmode).
sspi: Сервер должен запросить Windows SSPI аутентификацию.
scram-sha-256: Сервер должен успешно завершить процесс аутентификации SCRAM-SHA-256 при взаимодействии с клиентом.
none: Сервер не должен запрашивать у клиента прохождение процесса аутентификации. (Это не запрещает аутентификацию клиента по сертификату через TLS или аутентификацию GSS через зашифрованный транспорт.)

channel_binding #

Данный параметр управляет использованием привязки каналов на стороне клиента. Значение параметра require означает, что соединение должно использовать привязку каналов (channel binding), prefer означает, что клиент будет выбирать связывание каналов при его наличии, а disable предотвращает использование связывания каналов. По умолчанию используется значение развертывается prefer если Digital Q.DataBase библиотека скомпилирована с поддержкой SSL; в противном случае значением по умолчанию является disable.

Связывание каналов представляет собой метод аутентификации сервера перед клиентом. Данный метод поддерживается только для SSL-соединений при взаимодействии с Digital Q.DataBase серверами версии 11 или выше, использующими параметров SCRAM метод аутентификации.

connect_timeout #

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

client_encoding #

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

options #

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

application_name #

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

fallback_application_name #

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

параметры TCP keepalive #

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

keepalives_idle #

Определяет количество секунд бездействия, по истечении которых протокол TCP должен отправить серверу сообщение keepalive. Если указано значение ноль, используется системная настройка по умолчанию. Для соединений, установленных через сокеты домена Unix, или в случае, когда параметры TCP keepalive отключены, данный параметр игнорируется. Данный параметр поддерживается только в тех системах, где TCP_KEEPIDLE или доступен соответствующий параметр сокета, а также в ОС Windows; в остальных системах он не действует.

keepalives_interval #

Определяет интервал в секундах, по истечении которого сообщение TCP keepalive, не подтвержденное сервером, должно быть передано повторно. Если параметр равен нулю, используется системное значение по умолчанию. Данный параметр игнорируется для соединений через сокеты домена Unix или в случае, если параметры TCP keepalive отключены. Данный параметр поддерживается только в тех системах, где TCP_KEEPINTVL или доступен соответствующий параметр сокета, а также в ОС Windows; в остальных системах он не действует.

keepalives_count #

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

tcp_user_timeout #

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

репликация #

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

Поддерживаются следующие значения (регистр не важен):

true, on, yes, 1: Соединение переходит в режим физической репликации.
database: Соединение переходит в режим логической репликации с подключением к базе данных, указанной в параметре dbname параметр.
false, off, нет, 0: Данное соединение является обычным, что соответствует поведению по умолчанию.

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

gssencmode #

Данный параметр определяет необходимость или приоритет согласования защищенного GSS TCP/IP-соединения с сервером. Предусмотрено три режима:

disable: использовать толькоGSSAPIнезашифрованное соединение
prefer (по умолчанию): при наличии GSSAPI учетных данных (т. е. в кэше учетных данных) сначала предпринимается попытка установить зашифрованное GSSAPIсоединение; если она завершается неудачей или учетные данные отсутствуют, попробуйте установить не-GSSAPI-шифрованное соединение. Это режим по умолчанию, когда Digital Q.DataBase был скомпилирован с GSSAPI поддержкой.
require: только пытаться установить GSSAPIнезашифрованное соединение

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

sslmode #

Данный параметр определяет необходимость или приоритет согласования защищенного SSL TCP/IP-соединения с сервером. Предусмотрено шесть режимов:

disable: использовать толькоSSL соединение
allow: сначала предпринимается попытка установить не-SSL соединение; если она завершается ошибкой, предпринимается попытка установить SSL соединение
prefer (по умолчанию): сначала предпринимается попытка установить SSL соединение; в случае ошибки предпринимается попытка установить не-SSL соединение
require: предпринимается попытка установить только SSL соединение. Если файл корневого центра сертификации (CA) присутствует, сертификат проверяется так же, как в случае, когда verify-ca был указан
verify-ca: предпринимается попытка установить только SSL соединение и проверьте, что сертификат сервера выдан доверенным центром сертификации (CA)
verify-full: предпринимается попытка установить только SSL соединение, проверьте, что сертификат сервера выдан доверенным CA и что запрашиваемое имя узла сервера соответствует указанному в сертификате

См. Раздел 4.1.19 для получения подробного описания работы данных параметров.

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

sslnegotiation #

Данный параметр определяет способ согласования SSL-шифрования с сервером, если используется SSL. В режиме по умолчанию postgres клиент сначала запрашивает у сервера сведения о поддержке SSL. В direct режиме клиент инициирует стандартное SSL-рукопожатие сразу после установления TCP/IP-соединения. Традиционное Digital Q.DataBase согласование протокола является наиболее гибким при различных конфигурациях сервера. Если известно, что сервер поддерживает прямые соединения SSL direct, то последний вариант требует на один цикл приёма-передачи меньше, что снижает задержку соединения, а также позволяет использовать сетевые SSL-инструменты, не зависящие от протокола. Опция прямого подключения SSL была добавлена в Digital Q.DataBase версии 17.

postgres: выполнять Digital Q.DataBase протокола согласование. Данный вариант используется по умолчанию, если параметр не указан.
direct: начинать SSL-рукопожатие сразу после установления TCP/IP-соединения соединения. Это разрешено только при использовании параметра sslmode со значением require или выше, поскольку менее строгие настройки могут привести к непреднамеренному откату к аутентификации открытым текстом, если сервер не поддерживает прямое SSL-рукопожатие.

sslcompression #

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

В настоящее время SSL-сжатие считается небезопасным, и его использование более не рекомендуется. OpenSSL В версии 1.1.0 сжатие было отключено по умолчанию; во многих дистрибутивах операционных систем оно было отключено и в предыдущих версиях, поэтому установка параметра в значение on не даст результата, если сервер не поддерживает сжатие. Digital Q.DataBase В версии 14 поддержка сжатия в серверной части была полностью прекращена.

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

sslcert #

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

sslkey #

Данный параметр определяет расположение секретного ключа, используемого для клиентского сертификата. В нем может быть указано либо имя файла, которое будет использоваться вместо пути по умолчанию ~/.postgresql/postgresql.key, либо ключ, полученный из внешнего «engine» (криптографические модули представляют собой OpenSSL загружаемые модули). Спецификация внешнего модуля должна состоять из разделенных двоеточием имени модуля и соответствующего идентификатора ключа. Данный параметр игнорируется, если SSL-соединение не устанавливается.

sslpassword #

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

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

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

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

sslcertmode #

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

disable: Клиентский сертификат никогда не отправляется, даже если он доступен (находится в расположении по умолчанию или предоставлен через sslcert).
allow (по умолчанию): Сертификат может быть отправлен, если сервер запрашивает его и у клиента имеется соответствующий файл.
require: Сервер должен запросить сертификат. Установленное соединение будет разорвано, если клиент не отправит сертификат, а сервер при этом успешно аутентифицирует клиента.

Примечание

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

sslrootcert #

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

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

Примечание

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

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

sslcrl #

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

sslcrldir #

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

Каталог необходимо подготовить с помощью OpenSSL команды openssl rehash или c_rehash. См. подробности в документации к этой команде.

Оба значения sslcrl и sslcrldir могут быть указаны одновременно.

sslsni #

Если для данного параметра установлено значение 1 (по умолчанию), библиотека libpq устанавливает расширение TLS «Server Name Indication» (SNI) в соединениях с поддержкой протокола SSL. Данная функция отключается при установке значения 0 для этого параметра.

Расширение Server Name Indication может использоваться прокси-серверами с поддержкой SSL для маршрутизации соединений без необходимости расшифровки SSL-потока. (Учтите, что если прокси-сервер не поддерживает процедуру квитирования протокола PostgreSQL, то это потребует установки sslnegotiation равным direct.) Однако SNI приводит к тому, что имя целевого узла передаётся в открытом виде в сетевом трафике, поэтому это может быть нежелательным в некоторых случаях.

requirepeer #

Данный параметр определяет имя пользователя операционной системы для сервера, например: requirepeer=postgres. При установке соединения через сокет домена Unix, если данный параметр задан, в начале процесса соединения клиент проверяет, что процесс сервера запущен от имени указанного имени пользователя; в противном случае соединение прерывается с ошибкой. Данный параметр может использоваться для обеспечения аутентификации сервера, аналогичной той, что обеспечивается SSL-сертификатами при соединениях по протоколу TCP/IP. (Обратите внимание: если сокет домена Unix находится в /tmp или другом общедоступном для записи месте, любой пользователь может запустить там прослушивающий сервер. Используйте этот параметр, чтобы гарантировать подключение к серверу, запущенному доверенным пользователем.) Этот параметр поддерживается только на тех платформах, для которых peer реализован метод аутентификации; см. Раздел 3.5.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 данное имя должно совпадать с именем службы, указанным в конфигурации сервера. (См. также Раздел 3.5.6.) Обычно значением по умолчанию является postgres, однако его можно изменить на этапе сборки Digital Q.DataBase с помощью параметра параметров --with-krb-srvnam параметра параметра configure. В большинстве сред изменять данный параметр не требуется. Для некоторых реализаций Kerberos может потребоваться иное имя службы, например, Microsoft Active Directory требует, чтобы имя службы было указано в верхнем регистре (POSTGRES).

gsslib #

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

gssdelegation #

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

service #

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

target_session_attrs #

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

ни один из них (по умолчанию): любое успешное соединение считается допустимым
чтение-запись: сессия должна по умолчанию принимать транзакции в режиме чтение-запись (то есть сервер не должен находиться в режиме hot standby, а параметров default_transaction_read_only параметр должен иметь значение off)
только чтение: сессия по умолчанию не должна принимать транзакции в режиме чтение-запись (и наоборот)
основной: сервер не должен находиться в режиме hot standby
резервный сервер: сервер должен находиться в режиме горячего резерва
prefer-standby: сначала выполняется попытка поиска резервного сервера, но если ни один из перечисленных узлов не является резервным сервером, попытка повторяется в ни один из них режиме

load_balance_hosts #

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

disable (по умолчанию)

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

random

Узлы и адреса опрашиваются в случайном порядке. Данное значение параметра наиболее целесообразно использовать при одновременном открытии нескольких соединений, возможно, с разных рабочих станций. Такой подход позволяет распределять нагрузку соединений между несколькими Digital Q.DataBase серверами.

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

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

Наверх