32.1. Функции управления подключением к базе данных #
Следующие функции имеют дело с созданием подключения к серверу PostgreSQL. Прикладная программа может иметь несколько подключений к серверу, открытых одновременно. (Одна из причин этого заключается в необходимости доступа к более чем одной базе данных.) Каждое соединение представляется объектом PGconn
, который можно получить от функции PQconnectdb
, PQconnectdbParams
или PQsetdbLogin
. Обратите внимание, что эти функции всегда возвращают ненулевой указатель на объект, кроме случая, когда не остаётся свободной памяти даже для объекта PGconn
. Прежде чем передавать запросы через объект подключения, следует вызвать функцию PQstatus
для проверки возвращаемого значения в случае успешного подключения.
Предупреждение
Если к базе данных, которая не приведена в соответствие шаблону безопасного использования схем, имеют доступ недоверенные пользователи, начинайте сеанс с удаления доступных им для записи схем из пути поиска (search_path
). Для этого можно присвоить параметру с ключом options
значение -csearch_path=
. Также можно выполнить PQexec(
после подключения. Это касается не только psql, но и любых других интерфейсов для выполнения произвольных SQL-команд.соединение
, "SELECT pg_catalog.set_config('search_path', '', false)")
Предупреждение
В системе Unix создание дочернего процесса на основе процесса, уже имеющего открытые подключения с помощью libpq, может привести к непредсказуемым результатам, потому что родительский и дочерний процессы совместно используют одни и те же сокеты и ресурсы операционной системы. По этой причине подобный подход не рекомендуется. Однако использование системного вызова exec
из дочернего процесса для загрузки нового исполняемого файла является безопасным.
PQconnectdbParams
#Создаёт новое подключение к серверу баз данных.
PGconn *PQconnectdbParams(const char * const *keywords, const char * const *values, int expand_dbname);
Эта функция открывает новое соединение с базой данных, используя параметры, содержащиеся в двух массивах, завершающихся символом
NULL
. Первый из них,keywords
, определяется как массив строк, каждая из которых представляет собой ключевое слово. Второй,values
, даёт значение для каждого ключевого слова. В отличие от функцииPQsetdbLogin
, описываемой ниже, её набор параметров может быть расширен без изменения сигнатуры функции, поэтому при разработке новых приложений предпочтительнее использовать данную функцию (или её неблокирующие аналогиPQconnectStartParams
иPQconnectPoll
).Ключевые слова-параметры, распознаваемые в настоящее время, приведены в Подразделе 32.1.2.
Передаваемые массивы могут быть пустыми (в этом случае будут использоваться все параметры по умолчанию) или содержать одно или несколько имён/значений параметров. При этом они должны быть одинаковой длины. Просмотр массивов завершается, как только в массиве
keywords
встречаетсяNULL
. Если элемент массиваvalues
, соответствующий отличному отNULL
элементуkeywords
, содержит пустую строку или NULL, такой параметр пропускается и просматривается следующая пара элементов массива.Когда
expand_dbname
имеет ненулевое значение, первый параметрdbname
может содержать строку подключения. В этом случае она «разворачивается» в отдельные параметры подключения, извлечённые из этой строки. Значение считается строкой подключения, а не просто именем базы данных, если оно содержит знак равно (=
) или начинается с обозначения схемы URI. (Подробнее форматы строк подключения описаны в Подразделе 32.1.1.) Таким способом обрабатывается только первое вхождениеdbname
, следующие параметрыdbname
будут восприниматься как просто имя базы данных.Как правило, массивы параметров обрабатываются от начала к концу. Если какой-либо параметр указывается неоднократно, использоваться будет последнее значение (отличное от
NULL
и непустое). Это справедливо, в частности, и тогда, когда ключевое слово, заданное в строке подключения, конфликтует с заданным в массивеkeywords
. Таким образом, программист может по своему усмотрению решить, будут ли значения в массиве переопределять значения, заданными в строке подключения, или переопределяться ими. Элементы массива, предшествующие развёрнутому значениюdbname
, могут быть переопределены значениями в строке подключения, которые в свою очередь переопределяются элементами массива, следующими послеdbname
(и в этом случае речь идёт о непустых значениях).После разбора всех элементов массива и развёрнутой строки подключения (если она задана), параметры подключения, которые остались незаданными, получают значения по умолчанию. Если незаданному параметру соответствует установленная переменная окружения (см. Раздел 32.15), будет использоваться её значение. Если такая переменная не задана, для параметра будет использоваться встроенное значение по умолчанию.
PQconnectdb
#Создаёт новое подключение к серверу баз данных.
PGconn *PQconnectdb(const char *conninfo);
Эта функция открывает новое соединение с базой данных, используя параметры, полученные из строки
conninfo
.Передаваемая строка может быть пустой. В этом случае используются все параметры по умолчанию. Она также может содержать одно или более значений параметров, разделённых пробелами, или URI. За подробностями обратитесь к Подразделу 32.1.1.
PQsetdbLogin
#Создаёт новое подключение к серверу баз данных.
PGconn *PQsetdbLogin(const char *pghost, const char *pgport, const char *pgoptions, const char *pgtty, const char *dbName, const char *login, const char *pwd);
Это предшественница функции
PQconnectdb
с фиксированным набором параметров. Она имеет такую же функциональность, за исключением того, что отсутствующие параметры всегда принимают значения по умолчанию. ПодставьтеNULL
или пустую строку в качестве любого из фиксированных параметров, которые должны принять значения по умолчанию.Если параметр
dbName
содержит знак=
или имеет допустимый префикс URI для подключения, то он воспринимается в качестве строкиconninfo
точно таким же образом, как если бы он был передан функцииPQconnectdb
, а оставшиеся параметры применяются, как указано дляPQconnectdbParams
.pgtty
больше не используется, и любое переданное значение будет проигнорировано.PQsetdb
#Создаёт новое подключение к серверу баз данных.
PGconn *PQsetdb(char *pghost, char *pgport, char *pgoptions, char *pgtty, char *dbName);
Это макрос, который вызывает
PQsetdbLogin
с нулевыми указателями в качестве значений параметровlogin
иpwd
. Обеспечивает обратную совместимость с очень старыми программами.PQconnectStartParams
PQconnectStart
PQconnectPoll
#Создают подключение к серверу баз данных неблокирующим способом.
PGconn *PQconnectStartParams(const char * const *keywords, const char * const *values, int expand_dbname); PGconn *PQconnectStart(const char *conninfo); PostgresPollingStatusType PQconnectPoll(PGconn *conn);
Три эти функции используются для того, чтобы открыть подключение к серверу баз данных таким образом, чтобы поток исполнения вашего приложения не был заблокирован при выполнении удалённой операции ввода/вывода в процессе подключения. Суть этого подхода в том, чтобы ожидание завершения операций ввода/вывода могло происходить в главном цикле приложения, а не внутри функций
PQconnectdbParams
илиPQconnectdb
, с тем, чтобы приложение могло управлять этой операцией параллельно с другой работой.С помощью функции
PQconnectStartParams
подключение к базе данных выполняется, используя параметры, взятые из массивовkeywords
иvalues
, а управление осуществляется с помощьюexpand_dbname
, как описано выше дляPQconnectdbParams
.С помощью функции
PQconnectStart
подключение к базе данных выполняется, используя параметры, взятые из строкиconninfo
, как описано выше дляPQconnectdb
.Ни
PQconnectStartParams
, ниPQconnectStart
, ниPQconnectPoll
не заблокируются до тех пор, пока выполняется ряд ограничений:Параметр
hostaddr
должен использоваться так, чтобы для разрешения заданного имени не требовалось выполнять запросы DNS. Подробнее этот параметр описан в Подразделе 32.1.2.Если вы вызываете
PQtrace
, сделайте так, чтобы поток, в который выводится трассировочная информация, не заблокировался.Перед вызовом
PQconnectPoll
вы должны перевести сокет в соответствующее состояние, как описано ниже.
Чтобы начать неблокирующий запрос на подключение, вызовите
PQconnectStart
илиPQconnectStartParams
. Если результатом будет null, значит libpq не смогла выделить память для новой структурыPGconn
. В противном случае возвращается действительный указательPGconn
(хотя он ещё не представляет установленное подключение к базе данных). Затем вызовитеPQstatus(conn)
. Если результатом будетCONNECTION_BAD
, значит попытка подключения уже не будет успешной, возможно, из-за неверных параметров.Если вызов
PQconnectStart
илиPQconnectStartParams
оказался успешным, теперь нужно опросить libpq для продолжения процедуры подключения. ВызовитеPQsocket(conn)
для получения дескриптора нижележащего сокета, через который устанавливается соединение. (Внимание: этот сокет может меняться от вызова к вызовуPQconnectPoll
.) Организуйте цикл таким образом: еслиPQconnectPoll(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 = "Подключение..."; break; case CONNECTION_MADE: feedback = "Подключён к серверу..."; break; . . . default: feedback = "Подключение..."; }
Параметр подключения
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 миллион). Тайм-аут не ограничен при значении-1
у параметраend_time
. Тайм-аут завершается мгновенно (без блокировок) при значении0
у параметраend_time
(или любого значения до настоящего времени). Значения тайм-аута можно рассчитать, добавляя желаемое число микросекунд к результату работы функции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
, который завершается элементом, имеющим нулевой указательkeyword
. Если выделить память не удалось, то возвращается нулевой указатель. Обратите внимание, что текущие значения по умолчанию (поля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
для любого параметра, не присутствующего в строке подключения, будет иметь значениеNULL
в полеval
; значения по умолчанию не подставляются.Если
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
(см. выше) тем, что действуют неблокирующим способом. На эти функции налагаются те же ограничения, что и на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
стандартный вариант обработки файлов с зашифрованными ключами клиентских сертификатов, используя 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, для них модули могут по своему усмотрению получать пароль через стандартный обработчик OpenSSL или через свой собственный.Пользовательский обработчик может полностью переопределить функцию
PQdefaultSSLKeyPassHook_OpenSSL
, либо делегировать ей необрабатываемые им случаи, либо сначала вызывать её и предпринимать какие-то другие действия, если она возвратит 0.Этот обработчик не должен нарушать обычный ход выполнения, выбрасывая исключения, вызывая
longjmp(...)
и т. п. Он должен завершиться нормально.PQgetSSLKeyPassHook_OpenSSL
#PQgetSSLKeyPassHook_OpenSSL
возвращает текущий обработчик пароля для ключа клиентского сертификата либоNULL
, если такой обработчик не установлен.PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);
32.1.1. Строки параметров подключения #
Ряд функций libpq разбирают заданную пользователем строку для извлечения параметров подключения. Есть два принятых формата этих строк: простая строка ключ/значение и URI. Строки URI в основном соответствуют RFC 3986, но могут содержать также строки подключения с несколькими узлами, как описано ниже.
32.1.1.1. Строки параметров подключения вида «ключ/значение» #
Согласно формату ключ/значение, установка каждого параметра выполняется в форме ключ
=
значение
, с пробелами между параметрами. Пробелы вокруг знака равенства не являются обязательными. Для записи пустого значения или значения, содержащего пробелы, заключите его в одинарные кавычки, например, keyword = 'a value'
. Одинарные кавычки и символы обратной косой черты внутри значения нужно обязательно экранировать с помощью символа обратной косой черты, т. е., \'
и \\
.
Пример:
host=localhost port=5432 dbname=mydb connect_timeout=10
Ключевые слова-параметры, распознаваемые в настоящее время, приведены в Подразделе 32.1.2.
32.1.1.2. URI для подключения #
Основная форма URI подключения:
postgresql://[пользователь
@][сервер
][/база_данных
][?указание_параметра
] гдепользователь
:имя_пользователя
[:пароль
] исервер
: [узел
][:порт
][,...] иуказание_параметра
:имя
=значение
[&...]
В качестве обозначения схемы URI может использоваться postgresql://
или postgres://
. Остальные части URI являются необязательными. В следующих примерах показан допустимый синтаксис URI:
postgresql:// postgresql://localhost postgresql://localhost:5433 postgresql://localhost/mydb postgresql://user@localhost postgresql://user:secret@localhost postgresql://other@localhost/otherdb?connect_timeout=10&application_name=myapp postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application_name=myapp
Значения, которые обычно задаются в иерархической части URI, также можно задать в именованных параметрах. Например:
postgresql:///mydb?host=localhost&port=5433
Все именованные параметры должны соответствовать ключевым словам, перечисленным в Подраздел 32.1.2, за исключением того, что вхождения ssl=true
заменяются на sslmode=require
для совместимости с URI-строками JDBC.
Если URI подключения содержит в какой-либо из частей символы со специальным значением, он должен кодироваться в формате с процентами. Например, так выглядит URI, в котором знак равно (=
) заменён на %3D
, а знак пробела — на %20
:
postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff
Сервер можно представить либо сетевым именем, либо IP-адресом. При использовании протокола IPv6 нужно заключить адрес в квадратные скобки:
postgresql://[2001:db8::1234]/database
Часть host
интерпретируется в соответствии с описанием параметра host. Так, если эта часть строки пуста или выглядит как абсолютный путь, выбирается соединение через Unix-сокеты, в противном случае инициируется соединение по TCP/IP. Учтите однако, что символ косой черты в иерархической части URI является зарезервированным. Поэтому, чтобы указать нестандартный каталог Unix-сокета, нужно поступить одним из двух способов: не задавать эту часть в URI и указать сервер в именованном параметре либо закодировать путь в части host
с процентами:
postgresql:///dbname?host=/var/lib/postgresql postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
В одном URI можно задать несколько компонентов узлов, каждый с необязательным указанием порта. URI вида postgresql://host1:port1,host2:port2,host3:port3/
равнозначно строке подключения вида host=host1,host2,host3 port=port1,port2,port3
. Как описывается ниже, эти узлы будут перебираться по очереди, пока не будет установлено подключение.
32.1.1.3. Указание нескольких узлов #
В строке подключения можно задать несколько узлов, к которым клиент будет пытаться подключиться в заданном порядке. Параметры host
, hostaddr
и port
в формате ключ/значение принимают списки значений, разделённых запятыми. В каждом определяемом параметре должно содержаться одинаковое число элементов, чтобы, например, первый элемент hostaddr
соответствовал первому элементу host
, второй — второму host
и так далее. Исключение составляет port
— если этот параметр содержит только один элемент, он применяется ко всем узлам.
В формате URI внутри компонента host
можно указать несколько пар host:port
, разделённых запятыми.
В любом формате одно имя узла может переводиться в несколько сетевых адресов. Например, часто бывает, что один узел имеет и адрес IPv4, и адрес IPv6.
Когда задаются несколько узлов или когда одно имя узла переводится в несколько адресов, все узлы и адреса перебираются по порядку, пока подключение не будет установлено. Если ни один из адресов не будет доступен, произойдёт сбой подключения. Если подключение устанавливается успешно, но происходит ошибка аутентификации, остальные узлы в списке не перебираются.
Если используется файл паролей, в нём можно задать разные пароли для разных узлов. Все остальные параметры подключения будут одинаковыми для всех узлов; например, нельзя задать для разных узлов различные имена пользователей.
32.1.2. Ключевые слова-параметры #
Ключевые слова-параметры, распознаваемые в настоящее время, следующие:
host
#Имя узла для подключения. Если это имя выглядит как указание абсолютного пути, выбирается подключение через Unix-сокет, а не через TCP/IP, и данное значение определяет имя каталога, содержащего файл сокета. (В Unix-системах абсолютный путь начинается с косой черты, а в Windows абсолютные пути также могут начинаться с буквы диска.) Если имя узла начинается с
@
, оно воспринимается как Unix-сокет в абстрактном пространстве имён (в настоящее время поддерживается в Linux и Windows). По умолчанию, если параметрhost
отсутствует или пуст, выполняется подключение к Unix-сокету в/tmp
(или в том каталоге сокетов, который был задан при сборке PostgreSQL). В Windows по умолчанию выполняется подключение кlocalhost
.Также принимается разделённый запятыми список имён узлов; при этом данные имена будут перебираться по порядку. Для пустых элементов списка применяется поведение по умолчанию, описанное выше. За подробностями обратитесь к Подразделу 32.1.1.3.
hostaddr
#Числовой IP-адрес узла для подключения. Он должен быть представлен в стандартном формате адресов IPv4, например,
172.28.40.9
. Если ваша машина поддерживает IPv6, вы можете использовать и адреса IPv6. Если в этом параметре передана непустая строка, для подключения всегда используется TCP/IP. В отсутствие этого параметра целевой IP-адрес будет получен из имени, заданного в параметреhost
, либо если вhost
задан IP-адрес, будет использоваться непосредственно он.Использование
hostaddr
позволяет приложению обойтись без разрешения имён, что может быть важно для приложений с жёсткими временными ограничениями. Однако имя узла требуется для методов аутентификации GSSAPI или SSPI, а также для проверки полномочий на основе SSL-сертификатов в режимеverify-full
. Применяются следующие правила:Если адрес
host
задаётся безhostaddr
, осуществляется разрешение имени. (При использованииPQconnectPoll
разрешение производится, когдаPQconnectPoll
рассматривает это имя в первый раз, и может заблокироватьPQconnectPoll
на неопределённое время.)Если указан
hostaddr
, аhost
не указан, тогда значениеhostaddr
даёт сетевой адрес сервера. Попытка подключения завершится неудачей, если метод аутентификации требует наличия имени узла.Если указаны как
host
, так иhostaddr
, тогда значениеhostaddr
даёт сетевой адрес сервера, а значениеhost
игнорируется, если только метод аутентификации его не потребует. В таком случае оно будет использоваться в качестве имени узла.
Заметьте, что аутентификация может завершиться неудачей, если
host
не является именем сервера с сетевым адресомhostaddr
. Также заметьте, что когда указывается иhost
, иhostaddr
, соединение в файле паролей идентифицируется по значениюhost
(см. Раздел 32.16).Также принимается разделённый запятыми список значений
hostaddr
, при этом данные узлы будут перебираться по порядку. Вместо пустого элемента в этом списке будет подставлено имя соответствующего узла или, если и оно не определено, имя узла по умолчанию. За подробностями обратитесь к Подразделу 32.1.1.3.Если не указаны ни имя узла, ни его адрес, libpq будет производить подключение, используя локальный Unix-сокет; в Windows она будет пытаться подключиться к
localhost
.port
#Номер порта, к которому нужно подключаться на сервере, либо расширение имени файла сокета для соединений через Unix-сокеты. Если в параметрах
host
илиhostaddr
задано несколько серверов, в данном параметре может задаваться через запятую список портов такой же длины, либо может указываться один номер порта для всех узлов. Пустая строка или пустой элемент в списке через запятую воспринимается как номер порта по умолчанию, установленный при сборке PostgreSQL.dbname
#Имя базы данных. По умолчанию оно совпадает с именем пользователя. В определённых контекстах это значение проверяется на соответствие расширенным форматам; см. Подраздел 32.1.1 для получения подробной информации.
user
#Имя пользователя PostgreSQL, используемое для подключения. По умолчанию используется то же имя, которое имеет в операционной системе пользователь, от лица которого выполняется приложение.
password
#Пароль, используемый в случае, когда сервер требует аутентификации по паролю.
passfile
#Задаёт имя файла, в котором будут храниться пароли (см. Раздел 32.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
означает, что для соединения должно задействоваться связывание каналов,prefer
— клиент будет выбирать связывание, если оно поддерживается, аdisable
предотвращает использование этого механизма. По умолчанию подразумевается вариантprefer
, если PostgreSQL собирается с поддержкой SSL; в противном случае —disable
.Механизм связывания каналов позволяет серверу подтвердить свою подлинность клиенту. Он работает только для подключений поверх SSL с серверами PostgreSQL версии 11 и новее, когда используется метод аутентификации
SCRAM
.connect_timeout
#Максимальное время ожидания подключения (задаётся десятичным целым числом, например:
10
). При нуле, отрицательном или не заданном значении ожидание будет бесконечным. Этот тайм-аут применяется для каждого отдельного IP-адреса или имени сервера. Например, если вы зададите адреса двух серверов и значениеconnect_timeout
будет равно 5, тайм-аут при неудачной попытке подключения к каждому серверу истечёт через 5 секунд, а общее время ожидания подключения может достигать 10 секунд.client_encoding
#Этим устанавливается конфигурационный параметр
client_encoding
для данного подключения. В дополнение к значениям, которые принимает соответствующий параметр сервера, вы можете использовать значениеauto
. В этом случае правильная кодировка определяется на основе текущей локали на стороне клиента (в системах Unix это переменная системного окруженияLC_CTYPE
).options
#Задаёт параметры командной строки, которые будут отправлены серверу при установлении соединения. Например, значение
-c geqo=off
или--geqo=off
установит для параметра сеансаgeqo
значениеoff
. Пробелы в этой строке считаются разделяющими аргументы командной строки, если только перед ними не стоит обратная косая черта (\
); чтобы записать собственно обратную косую черту, её нужно продублировать (\\
). Подробное описание возможных параметров можно найти в Главе 19.application_name
#Устанавливает значение для конфигурационного параметра application_name.
fallback_application_name
#Устанавливает альтернативное значение для конфигурационного параметра application_name. Это значение будет использоваться, если для параметра
application_name
не было передано никакого значения с помощью параметров подключения или переменной системного окруженияPGAPPNAME
. Задание альтернативного имени полезно для универсальных программ-утилит, которые желают установить имя приложения по умолчанию, но позволяют пользователю изменить его.keepalives
#Управляет использованием сообщений keepalive протокола TCP на стороне клиента. Значение по умолчанию равно 1, что означает использование сообщений. Вы можете изменить его на 0, если эти сообщения не нужны. Для соединений, установленных через Unix-сокеты, этот параметр игнорируется.
keepalives_idle
#Управляет длительностью периода отсутствия активности, выраженного числом секунд, по истечении которого TCP должен отправить сообщение keepalive серверу. При значении 0 действует системная величина. Этот параметр игнорируется для соединений, установленных через Unix-сокеты, или если сообщения keepalive отключены. Он поддерживается только в системах, воспринимающих параметр сокета
TCP_KEEPIDLE
или равнозначный, и в Windows; в других системах он не оказывает влияния.keepalives_interval
#Задаёт количество секунд, по прошествии которых сообщение keepalive протокола TCP, получение которого не подтверждено сервером, должно быть отправлено повторно. При значении 0 действует системная величина. Этот параметр игнорируется для соединений, установленных через Unix-сокеты, или если сообщения keepalive отключены. Он поддерживается только в системах, воспринимающих параметр сокета
TCP_KEEPINTVL
или равнозначный, и в Windows; в других системах он не оказывает влияния.keepalives_count
#Задаёт количество сообщений keepalive протокола TCP, которые могут быть потеряны, прежде чем соединение клиента с сервером будет признано неработающим. Нулевое значение этого параметра указывает, что будет использоваться системное значение по умолчанию. Этот параметр игнорируется для соединений, установленных через Unix-сокеты, или если сообщения keepalive отключены. Он поддерживается только в системах, воспринимающих параметр сокета
TCP_KEEPCNT
или равнозначный; в других системах он не оказывает влияния.tcp_user_timeout
#Управляет длительностью интервала (в миллисекундах), в течение которого данные могут оставаться неподтверждёнными, прежде чем соединение будет принудительно закрыто. При значении 0 действует системная величина. Этот параметр игнорируется для соединений, установленных через Unix-сокеты. Он поддерживается только в системах, воспринимающих параметр сокета
TCP_USER_TIMEOUT
; в других системах он не оказывает влияния.replication
#Этот параметр определяет, должно ли подключение использовать протокол репликации вместо обычного протокола. Этот вариант используют внутри механизмы репликации PostgreSQL и такие средства, как pg_basebackup, но он может также применяться и сторонними приложениями. За подробным описанием протокола репликации обратитесь к Разделу 53.4.
Поддерживаются следующие значения этого параметра, без учёта регистра:
true
,on
,yes
,1
Подключение осуществляется в режиме физической репликации.
database
Подключение осуществляется в режиме логической репликации, целевая база данных задаётся параметром
dbname
.false
,off
,no
,0
Подключение выполняется в обычном режиме; это поведение по умолчанию.
В режиме физической или логической репликации может использоваться только простой протокол запросов.
gssencmode
#Этот параметр определяет, будет ли согласовываться с сервером защищённое GSS соединение по протоколу TCP/IP, и если да, то в какой очередности. Всего предусмотрено три режима:
disable
пытаться установить только соединение без шифрования GSSAPI
prefer
(по умолчанию)если уже имеются учётные данные GSSAPI (в кеше учётных данных), сначала попытаться установить соединение с шифрованием GSSAPI; если эта попытка не удастся или подходящих данных нет, попробовать соединение без шифрования GSSAPI. Это значение по умолчанию, если PostgreSQL был скомпилирован с поддержкой GSSAPI.
require
пытаться установить только соединение с шифрованием GSSAPI
sslmode
игнорируется при использовании Unix-сокетов. Если PostgreSQL скомпилирован без поддержки GSSAPI, использование вариантаrequire
приведёт к ошибке, в то время как параметрprefer
будет принят, но libpq в действительности не будет пытаться установить зашифрованное GSSAPI соединение.sslmode
#Этот параметр определяет, будет ли согласовываться с сервером защищённое SSL-соединение по протоколу TCP/IP, и если да, то в какой очередности. Всего предусмотрено шесть режимов:
disable
следует пытаться установить только соединение без использования SSL
allow
сначала следует попытаться установить соединение без использования SSL; если попытка будет неудачной, нужно попытаться установить SSL-соединение
prefer
(по умолчанию)сначала следует попытаться установить SSL-соединение; если попытка будет неудачной, нужно попытаться установить соединение без использования SSL
require
следует попытаться установить только SSL-соединение. Если присутствует файл корневого центра сертификации, то нужно верифицировать сертификат таким же способом, как будто был указан параметр
verify-ca
verify-ca
следует попытаться установить только SSL-соединение, при этом проконтролировать, чтобы сертификат сервера был выпущен доверенным центром сертификации (CA)
verify-full
следует попытаться установить только SSL-соединение, при этом проконтролировать, чтобы сертификат сервера был выпущен доверенным центром сертификации (CA) и чтобы имя запрошенного сервера соответствовало имени в сертификате
В Разделе 32.19 приведено подробное описание работы этих режимов.
sslmode
игнорируется при использовании Unix-сокетов. Если PostgreSQL скомпилирован без поддержки 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
). Этот параметр доступен, если только PostgreSQL скомпилирован с поддержкой SSL.sslnegotiation
#Данный параметр управляет согласованием шифрования по протоколу SSL с сервером (при использовании SSL). В режиме по умолчанию
postgres
клиент узнаёт у сервера, поддерживает ли тот SSL. В режимеdirect
клиент начинает стандартный обмен сообщениями по SSL сразу же после установления соединения по TCP/IP. Самым гибким является традиционный протокол согласований PostgreSQL, обладающий разными серверными конфигурациями. Если известно, что сервер поддерживает прямые подключения по SSL, то этот способ уменьшает количество дополнительных обращений, тем самым снижая задержку соединения, и позволяет использовать сетевое оборудование с поддержкой SSL, совместимое с другими протоколами. Режимdirect
появился в 17-й версии PostgreSQL.postgres
запустить протокол согласования PostgreSQL. Это режим по умолчанию, если параметр не задан.
direct
начать обмен сообщениями по SSL сразу же после установления соединения по TCP/IP. Данный режим возможен только при значении sslmode=require или более строгом значении, поскольку значение с менее строгой проверкой может привести к возврату на незашифрованную аутентификацию, если сервер не поддерживает прямой обмен сообщениями по SSL.
sslcompression
#Если установлено значение 1, данные, передаваемые через SSL-соединения, будут сжиматься. Если установлено значение 0 (по умолчанию), сжатие будет отключено. Этот параметр игнорируется, если установлено подключение без SSL.
Сжатие SSL в настоящее время считается небезопасным, и использовать его уже не рекомендуется. В OpenSSL 1.1.0 сжатие отключено по умолчанию, к тому же во многих дистрибутивах оно отключается и с более ранними версиями. А если сервер не поддерживает сжатие, включение этого параметра не окажет никакого влияния. В PostgreSQL 14 сжатие полностью отключено на сервере.
Если вопросы безопасности не стоят на первом месте, сжатие может ускорить передачу данных, когда узким местом является сеть. Отключение сжатия может улучшить время отклика и пропускную способность, если ограничивающим фактором является производительность CPU.
sslcert
#Этот параметр предписывает имя файла для SSL-сертификата клиента, заменяющего файл по умолчанию
~/.postgresql/postgresql.crt
. Этот параметр игнорируется, если SSL-подключение не выполнено.sslkey
#Этот параметр предписывает местоположение секретного ключа, используемого для сертификата клиента. Он может либо указывать имя файла, которое будет использоваться вместо имени по умолчанию
~/.postgresql/postgresql.key
, либо он может указывать ключ, полученный от внешнего «криптомодуля» (криптомодули — это загружаемые модули OpenSSL). Спецификация внешнего криптомодуля должна состоять из имени модуля и ключевого идентификатора, зависящего от конкретного модуля, разделённых двоеточием. Этот параметр игнорируется, если SSL-подключение не выполнено.sslpassword
#Этот параметр задаёт пароль для секретного ключа, указанного в
sslkey
, что позволяет хранить на диске закрытые ключи клиентских сертификатов в зашифрованном виде, даже когда применять интерактивный ввод пароля непрактично.Когда для этого параметра задаётся непустое значение, приглашение OpenSSL
Enter PEM pass phrase:
(Введите пароль для PEM:) не выводится. По умолчанию это приглашение выдаётся, если вlibpq
передаётся зашифрованный ключ клиентского сертификата.Если ключ не зашифрован, этот параметр игнорируется. Данный параметр не действует для ключей, которыми оперируют дополнительные модули OpenSSL, если только модуль не пользуется представленной в OpenSSL функцией-обработчиком запроса пароля.
Для этого параметра нет соответствующей переменной окружения, а также не реализована возможность задать его в
.pgpass
. Однако его можно задать в определении свойств подключения в файле служб. Пользователям, которых не устраивает такой простой способ задания пароля, следует использовать специальные модули и средства OpenSSL, например PKCS#11 или криптографические USB-устройства.sslcertmode
#Этот параметр определяет, может ли сертификат клиента быть отправлен серверу и должен ли сервер запрашивать его. Всего предусмотрено три режима:
disable
Сертификат клиента не отправляется, даже если он доступен (расположен по умолчанию или указан в sslcert).
allow
(по умолчанию)Сертификат может быть отправлен, если сервер запрашивает его и клиент может его отправить.
require
Сервер должен запрашивать сертификат. Установить подключение не удастся, если клиент не отправляет сертификат, а сервер всё равно успешно аутентифицирует клиента.
Примечание
Установка
sslcertmode=require
не повышает безопасность, поскольку нет гарантии, что сервер правильно проверяет сертификат. Серверы PostgreSQL обычно запрашивают сертификаты TLS от клиентов независимо от того, проверяют они их или нет. Этот параметр может быть полезен при устранении неполадок в более сложных схемах TLS.sslrootcert
#Этот параметр указывает имя файла, содержащего SSL-сертификаты, выданные Центром сертификации (CA). Если файл существует, сертификат сервера будет проверен на предмет его подписания одним из этих центров. Имя по умолчанию —
~/.postgresql/root.crt
.Вместо этого можно указать специальное значение
system
, и в этом случае будут загружены доверенные сертификаты корневых ЦС. Точное расположение этих корневых сертификатов зависит от реализации SSL и платформы. В частности, для OpenSSL расположение можно уточнить в переменных окруженияSSL_CERT_DIR
иSSL_CERT_FILE
.Примечание
При использовании
sslrootcert=system
значениеsslmode
, заданное по умолчанию, меняется наverify-full
, и любое значение с менее строгой проверкой приведёт к ошибке. В большинстве случаев нетрудно получить доверенный для системы сертификат по имени управляемого узла, что делаетverify-ca
и все более слабые режимы бесполезными.Если указать файл сертификата с именем
system
, оно будет распознаваться как особое значениеsystem
, поэтому при наличии файла с таким именем следует задать альтернативный путь, напримерsslrootcert=./system
.sslcrl
#Этот параметр указывает имя файла, содержащего список отозванных серверных сертификатов (CRL) для SSL. Сертификаты, перечисленные в этом файле, если он существует, будут отвергаться при попытке установить подлинность сертификата сервера. Если ни sslcrl, ни sslcrldir не заданы, используется файл
~/.postgresql/root.crl
.sslcrldir
#Этот параметр указывает имя каталога, содержащего список отозванных серверных сертификатов (CRL) для SSL. Сертификаты, перечисленные в файлах данного каталога, если он существует, будут считаться неприемлемыми при проверке подлинности сертификата сервера.
Каталог необходимо подготовить с помощью команды OpenSSL
openssl rehash
илиc_rehash
. За подробностями обратитесь к документации OpenSSL.Параметры
sslcrl
иsslcrldir
можно указывать вместе.sslsni
#Со значением, равным 1 (по умолчанию), libpq включает расширение TLS «Server Name Indication» (SNI) для подключений с поддержкой SSL. При значении, равном 0, данное расширение отключается.
Указание имени сервера (SNI) может использоваться прокси-серверами с поддержкой SSL для маршрутизации соединений без расшифровывания потока SSL. (Обратите внимание, что если прокси-сервер не распознаёт пакеты инициализации протокола PostgreSQL, для
sslnegotiation
необходимо задать режимdirect
.) Однако при включении SNI имя целевого сервера передаётся по сети в открытом виде, что в некоторых случаях может быть нежелательно.requirepeer
#Этот параметр указывает имя пользователя операционной системы, предназначенное для сервера, например,
requirepeer=postgres
. При создании подключения через Unix-сокет, если этот параметр установлен, клиент проверяет в самом начале процедуры подключения, что серверный процесс запущен от имени указанного пользователя; если это не так, соединение аварийно прерывается с ошибкой. Этот параметр можно использовать, чтобы обеспечить аутентификацию сервера, подобную той, которая доступна с помощью SSL-сертификатов при соединениях по протоколу TCP/IP. (Заметьте, что если Unix-сокет находится в каталоге/tmp
или в другом каталоге, запись в который разрешена всем пользователям, тогда любой пользователь сможет запустить сервер, прослушивающий сокет в том каталоге. Используйте этот параметр, чтобы гарантировать, что вы подключены к серверу, запущенному доверенным пользователем.) Он поддерживается только на платформах, для которых реализован метод аутентификацииpeer
; см. Раздел 20.9.ssl_min_protocol_version
#Этот параметр определяет, с какой минимальной версией протокола SSL/TLS может быть установлено подключение. Допустимые значения:
TLSv1
,TLSv1.1
,TLSv1.2
иTLSv1.3
. Набор поддерживаемых протоколов зависит от используемой версии OpenSSL; старые версии могут не поддерживать последние протоколы. По умолчанию минимальной считается версияTLSv1.2
, что соответствует рекомендациям, актуальным в индустрии на момент написания этой документации.ssl_max_protocol_version
#Этот параметр определяет, с какой максимальной версией протокола SSL/TLS может быть установлено подключение. Допустимые значения:
TLSv1
,TLSv1.1
,TLSv1.2
иTLSv1.3
. Набор поддерживаемых протоколов зависит от используемой версии OpenSSL; старые версии могут не поддерживать последние протоколы. Если этот параметр не задан, при подключении будет действовать ограничение версии сверху, установленное на стороне сервера (при наличии такового). Возможность ограничения максимальной версии протокола полезна прежде всего при тестировании или когда какой-либо компонент работает с новым протоколом некорректно.krbsrvname
#Имя службы Kerberos, которое будет использоваться при аутентификации GSSAPI. Чтобы аутентификация Kerberos прошла успешна, оно должно соответствовать имени службы, заданному в конфигурации сервера. (См. также Раздел 20.6.) По умолчанию обычно выбирается имя
postgres
, но его можно сменить при сборке PostgreSQL, передав ключ--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
, который содержит дополнительные параметры подключения. Это позволяет приложениям указывать только имя сервиса, поскольку параметры подключения могут поддерживаться централизованно. См. Раздел 32.17.target_session_attrs
#Этот параметр может накладывать ограничения на свойства сеансов, которые будут считаться приемлемыми. Обычно он используется вместе с указанием имён нескольких серверов и позволяет выбрать из них первый подходящий вариант. Есть шесть режимов:
any
(по умолчанию)любое успешное соединение приемлемо
read-write
сеанс должен принимать транзакции чтения-записи по умолчанию (то есть сервер не должен находиться в режиме горячего резерва, а у параметра
default_transaction_read_only
должно быть значениеoff
)read-only
сеанс не должен принимать транзакции чтения-записи по умолчанию (противоположный случай)
primary
сервер не должен находиться в режиме горячего резерва
standby
сервер должен находиться в режиме горячего резерва
prefer-standby
сначала пытаться найти резервный сервер, но если ни один из перечисленных серверов не является резервным, попробовать снова в режиме
any
load_balance_hosts
#Управляет порядком, в котором клиент пытается подключиться к доступным узлам и адресам. Если попытка подключения окажется успешной, клиент не будет пытаться подключиться к другим узлам и адресам. Этот параметр обычно используется вместе с несколькими именами узлов или записью DNS, которая возвращает несколько IP-адресов. Его также можно использовать вместе с target_session_attrs, например для балансировки нагрузки только между резервными серверами. После успешного подключения все последующие запросы по возвращённому подключению будут отправлены на один и тот же сервер. В настоящее время существует два режима:
disable
(по умолчанию)Балансировка нагрузки между узлами не выполняется. Узлы перебираются по очереди, а адреса — в том порядке, в котором они получены от DNS или файлов узлов.
random
Узлы и адреса перебираются в случайном порядке. Это значение наиболее полезно при одновременном открытии нескольких соединений, возможно с разных компьютеров. Таким образом, нагрузка может распределяться между соединениями нескольких серверов PostgreSQL.
Хотя случайная балансировка нагрузки по своей природе почти никогда не приводит к полностью равномерному распределению, статистически она довольно близка к этому. Важно то, что этот алгоритм использует два уровня случайного выбора: сначала узлы разрешаются в случайном порядке, затем перед разрешением следующего узла все разрешённые адреса текущего узла перебираются в случайном порядке. Такое поведение может сильно влиять на количество подключений, которые получает каждый узел в определённых случаях, например, когда некоторые узлы разрешают больше адресов, чем другие. Но такое влияние можно использовать и намеренно. Например, чтобы увеличить количество подключений к более крупному серверу, можно несколько раз указать его имя в соответствующей строке.
При использовании этого значения рекомендуется также выбрать подходящее значение для connect_timeout, потому что в таком случае, если один из узлов, используемых для балансировки нагрузки, не отвечает, будет использоваться новый узел.
.