31.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
) является предпочтительным при разработке новых приложений.Ключевые слова-параметры, распознаваемые в настоящее время, приведены в Подразделе 31.1.2.
Передаваемые массивы могут быть пустыми (в этом случае будут использоваться все параметры по умолчанию) или содержать одно или несколько имён/значений параметров. При этом они должны быть одинаковой длины. Просмотр массивов завершается, как только в массиве
keywords
встречаетсяNULL
. Если элемент массиваvalues
, соответствующий отличному отNULL
элементуkeywords
, содержит пустую строку или NULL, такой параметр пропускается и просматривается следующая пара элементов массива.Когда
expand_dbname
имеет ненулевое значение, первый параметрdbname
может содержать строку подключения. В этом случае она «разворачивается» в отдельные параметры подключения, извлечённые из этой строки. Значение считается строкой подключения, а не просто именем базы данных, если оно содержит знак равно (=
) или начинается с обозначения схемы URI. (Подробнее форматы строк подключения описаны в Подразделе 31.1.1.) Таким способом обрабатывается только первое вхождениеdbname
, следующие параметрыdbname
будут восприниматься как просто имя базы данных.Как правило, массивы параметров обрабатываются от начала к концу. Если какой-либо параметр указывается неоднократно, использоваться будет последнее значение (отличное от
NULL
и непустое). Это справедливо, в частности, и тогда, когда ключевое слово, заданное в строке подключения, конфликтует с заданным в массивеkeywords
. Таким образом, программист может по своему усмотрению решить, будут ли значения в массиве переопределять значения, заданными в строке подключения, или переопределяться ими. Элементы массива, предшествующие развёрнутому значениюdbname
, могут быть переопределены значениями в строке подключения, которые в свою очередь переопределяются элементами массива, следующими послеdbname
(и в этом случае речь идёт о непустых значениях).После разбора всех элементов массива и развёрнутой строки подключения (если она задана), параметры подключения, которые остались незаданными, получают значения по умолчанию. Если незаданному параметру соответствует установленная переменная окружения (см. Раздел 31.14), будет использоваться её значение. Если такая переменная не задана, для параметра будет использоваться встроенное значение по умолчанию.
PQconnectdb
Создаёт новое подключение к серверу баз данных.
PGconn *PQconnectdb(const char *conninfo);
Эта функция открывает новое соединение с базой данных, используя параметры, полученные из строки
conninfo
.Передаваемая строка может быть пустой. В этом случае используются все параметры по умолчанию. Она также может содержать одно или более значений параметров, разделённых пробелами, или URI. За подробностями обратитесь к Подразделу 31.1.1.
PQsetdbLogin
Создаёт новое подключение к серверу баз данных.
PGconn *PQsetdbLogin(const char *pghost, const char *pgport, const char *pgoptions, const char *pgtty, const char *dbName, const char *login, const char *pwd);
Это предшественница функции
PQconnectdb
с фиксированным набором параметров. Она имеет такую же функциональность, за исключением того, что непереданные параметры всегда принимают значения по умолчанию. ПодставьтеNULL
или пустую строку в качестве любого из фиксированных параметров, которые должны принять значения по умолчанию.Если параметр
dbName
содержит знак=
или имеет допустимый префикс URI для подключения, то он воспринимается в качестве строкиconninfo
точно таким же образом, как если бы он был передан функцииPQconnectdb
, а оставшиеся параметры затем применяются, как указано дляPQconnectdbParams
.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
иhost
используются так, чтобы прямой и обратный DNS-запросы не выполнялись. Подробнее эти параметры описаны в Подразделе 31.1.2.Если вы вызываете
PQtrace
, обеспечьте, чтобы поток, в который выводится трассировочная информация, не заблокировался.Перед вызовом
PQconnectPoll
вы должны перевести сокет в соответствующее состояние, как описано ниже.
Примечание: использование
PQconnectStartParams
аналогично использованиюPQconnectStart
, показанному ниже.Чтобы начать неблокирующий запрос на подключение, вызовите
conn = PQconnectStart("
. Если значениеconnection_info_string
")conn
пустое, то, значит, libpq не смогла распределить память для новой структурыPGconn
. В противном случае будет возвращён корректный указательPGconn
(хотя ещё и не представляющий действительного подключения к базе данных). После возврата изPQconnectStart
вызовитеstatus = PQstatus(conn)
. Еслиstatus
имеет значениеCONNECTION_BAD
, то, значит, вызовPQconnectStart
завершился сбоем.Если вызов
PQconnectStart
был успешным, теперь нужно опросить libpq, чтобы она могла продолжить процесс подключения. ИспользуйтеPQsocket(conn)
для получения дескриптора сокета, лежащего в основе соединения с базой данных. Организуйте цикл таким образом: еслиPQconnectPoll(conn)
в последний раз возвратилаPGRES_POLLING_READING
, то подождите, пока сокет не станет готовым к выполнению операции чтения (это покажет функцияselect()
,poll()
или подобная системная функция). Затем вызовитеPQconnectPoll(conn)
опять. И наоборот, еслиPQconnectPoll(conn)
в последний раз возвратилаPGRES_POLLING_WRITING
, то подождите, пока сокет не станет готовым к выполнению операции записи, затем вызовитеPQconnectPoll(conn)
снова. Если вам всё же приходится вызватьPQconnectPoll
, то есть сразу после вызоваPQconnectStart
, поступайте так, как будто она в последний раз возвратилаPGRES_POLLING_WRITING
. Продолжайте этот цикл до тех пор, покаPQconnectPoll(conn)
не возвратитPGRES_POLLING_FAILED
, показывая, что процедура подключения завершилась сбоем, илиPGRES_POLLING_OK
, показывая, что соединение было успешно установлено.В любое время в процессе подключения его состояние можно проверить, вызвав
PQstatus
. Если этот вызов возвратитCONNECTION_BAD
, значит, процедура подключения завершилась сбоем; если вызов возвратитCONNECTION_OK
, значит, соединение готово. Оба эти состояния можно определить на основе возвращаемого значения функцииPQconnectPoll
, описанной выше. Другие состояния могут также иметь место в течение (и только в течение) асинхронной процедуры подключения. Они показывают текущую стадию процедуры подключения и могут быть полезны, например, для предоставления обратной связи пользователю. Вот эти состояния:CONNECTION_STARTED
Ожидание, пока соединение будет установлено.
CONNECTION_MADE
Соединение установлено; ожидание отправки.
CONNECTION_AWAITING_RESPONSE
Ожидание ответа от сервера.
CONNECTION_AUTH_OK
Аутентификация получена; ожидание завершения запуска серверной части.
CONNECTION_SSL_STARTUP
Согласование SSL-шифрования.
CONNECTION_SETENV
Согласование значений параметров, зависящих от программной среды.
Заметьте, что, хотя эти константы и сохранятся (для поддержания совместимости), приложение никогда не должно полагаться на то, что они появятся в каком-то конкретном порядке или вообще появятся, а также на то, что состояние всегда примет одно из этих документированных значений. Приложение может сделать что-то наподобие:
switch(PQstatus(conn)) { case CONNECTION_STARTED: feedback = "Подключение..."; break; case CONNECTION_MADE: feedback = "Подключён к серверу..."; break; . . . default: feedback = "Подключение..."; }
Параметр подключения
connect_timeout
игнорируется, когда используетсяPQconnectPoll
; именно приложение отвечает за принятие решения о том, является ли истекшее время чрезмерным. В противном случае вызовPQconnectStart
с последующим вызовомPQconnectPoll в цикле
будут эквивалентны вызовуPQconnectdb
.Заметьте, что если функция
PQconnectStart
возвращает ненулевой указатель, то, закончив его использование, вы должны вызватьPQfinish
, чтобы освободить полученную структуру и все связанные с ней блоки памяти. Это нужно сделать, даже если попытка подключения не последует или окажется неуспешной.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
.
31.1.1. Строки параметров подключения
Ряд функций libpq получают параметры подключения, разбирая строки, заданные пользователем. Эти строки воспринимаются в двух форматах: простые строки ключ = значение
и URI, соответствующие RFC 3986.
31.1.1.1. Строки параметров подключения вида "ключ/значение"
Согласно первому формату, установка каждого параметра выполняется в форме keyword = value
. Пробелы вокруг знака равенства не являются обязательными. Для записи пустого значения или значения, содержащего пробелы, заключите его в одинарные кавычки, например, keyword = 'a value'
. Одинарные кавычки и символы обратной косой черты внутри значения нужно обязательно экранировать с помощью символа обратной косой черты, т. е., \'
и \\
.
Пример:
host=localhost port=5432 dbname=mydb connect_timeout=10
Ключевые слова-параметры, распознаваемые в настоящее время, приведены в Подразделе 31.1.2.
31.1.1.2. URI для подключения
Общая форма URI для подключения такова:
postgresql://[user[:password]@][host][:port][/dbname][?param1=value1&...]
В качестве обозначения схемы 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
Значения, которые обычно задаются в иерархической части URI, также можно задать в именованных параметрах. Например:
postgresql:///mydb?host=localhost&port=5433
Все именованные параметры должны соответствовать ключевым словам, перечисленным в Подраздел 31.1.2, за исключением того, что вхождения ssl=true
заменяются на sslmode=require
для совместимости с URI-строками JDBC.
Для включения символов, имеющих специальное значение, в любой части URI можно применять URL-кодирование (с использованием символа %).
Сервер можно представить либо сетевым именем, либо 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
31.1.2. Ключевые слова-параметры
Ключевые слова-параметры, распознаваемые в настоящее время, следующие:
host
Имя компьютера для подключения. Если оно начинается с косой черты, соединение будет установлено через Unix-сокет, а не по протоколу TCP/IP; значение задаёт имя каталога, содержащего файл сокета. По умолчанию, когда
host
не указан, подключение производится через Unix-сокет в каталоге/tmp
(или в том каталоге, который был назначен при сборке PostgreSQL). В системах, не поддерживающих Unix-сокеты, подключение по умолчанию производится кlocalhost
.hostaddr
Числовой IP-адрес компьютера для подключения. Он должен быть представлен в стандартном формате адресов IPv4, например,
172.28.40.9
. Если ваша машина поддерживает IPv6, вы можете использовать и эти адреса. Связь по протоколу TCP/IP используется всегда, когда в качестве этого параметра передана непустая строка.Использование
hostaddr
вместоhost
позволяет приложению избежать поиска на сервере имён, что может быть важно для приложений, имеющих временные ограничения. Однако, имя компьютера требуется для методов аутентификации GSSAPI или SSPI, а также для проверки полномочий на основе SSL-сертификатов в режимеverify-full
. Используются следующие правила:Если
host
указан, аhostaddr
не указан, тогда выполняется поиск на сервере имён.Если указан
hostaddr
, аhost
не указан, тогда значениеhostaddr
даёт сетевой адрес сервера. Попытка подключения завершится неудачей, если метод аутентификации требует наличия имени компьютера.Если указаны как
host
, так иhostaddr
, тогда значениеhostaddr
даёт сетевой адрес сервера, а значениеhost
игнорируется, если только метод аутентификации его не потребует. В таком случае оно будет использоваться в качестве имени компьютера.
Заметьте, что аутентификация может завершится неудачей, если
host
не является именем сервера, имеющего сетевой адресhostaddr
. Заметьте также, чтоhost
, а неhostaddr
используется для того, чтобы идентифицировать соединение в~/.pgpass
(см. Раздел 31.15).Если не указаны ни имя компьютера, ни его адрес, libpq будет производить подключение, используя локальный Unix-сокет; в системах, не поддерживающих Unix-сокеты, она будет пытаться подключиться к
localhost
.port
Номер порта для подключения к серверу или расширение имени файла-сокета для подключений в домене Unix.
dbname
Имя базы данных. По умолчанию оно совпадает с именем пользователя. В определённых контекстах это значение проверяется на соответствие расширенным форматам; см. Подраздел 31.1.1 для получения подробной информации.
user
Имя пользователя PostgreSQL, используемое для подключения. По умолчанию используется то же имя, которое имеет в операционной системе пользователь, от лица которого выполняется приложение.
password
Пароль, используемый в случае, когда сервер требует аутентификации по паролю.
connect_timeout
Максимальный период ожидания подключения, в секундах (записывается в виде строки, представляющей десятичное целое число).
client_encoding
Этим устанавливается конфигурационный параметр
client_encoding
для данного подключения. В дополнение к значениям, которые принимает соответствующий параметр сервера, вы можете использовать значениеauto
. В этом случае правильная кодировка определяется на основе текущей локали на стороне клиента (в системах Unix это переменная системного окруженияLC_CTYPE
).options
Задаёт параметры командной строки, которые будут отправлены серверу при установлении соединения. Например, значение
-c geqo=off
установит для параметра сеансаgeqo
значениеoff
. Пробелы в этой строке считаются разделяющими аргументы командной строки, если только перед ними не стоит обратная косая черта (\
); чтобы записать собственно обратную косую черту, её нужно продублировать (\\
). Подробное описание возможных параметров можно найти в Главе 18.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
или равнозначный; в других системах он не оказывает влияния.tty
Игнорируется (прежде он указывал, куда направить вывод отладочных сообщений сервера).
sslmode
Этот параметр определяет, будет ли согласовываться с сервером защищённое SSL-соединение по протоколу TCP/IP, и если да, то в какой очередности. Всего предусмотрено шесть режимов:
disable
следует пытаться установить только соединение без использования SSL
allow
сначала следует попытаться установить соединение без использования SSL; если попытка будет неудачной, нужно попытаться установить SSL-соединение
prefer
(по умолчанию)сначала следует попытаться установить SSL-соединение; если попытка будет неудачной, нужно попытаться установить соединение без использования SSL
require
следует попытаться установить только SSL-соединение. Если присутствует файл корневого центра сертификации, то нужно верифицировать сертификат таким же способом, как будто был указан параметр
verify-ca
verify-ca
следует попытаться установить только SSL-соединение, при этом проконтролировать, чтобы сертификат сервера был выпущен доверенным центром сертификации (CA)
verify-full
следует попытаться установить только SSL-соединение, при этом проконтролировать, чтобы сертификат сервера был выпущен доверенным центром сертификации (CA) и чтобы имя запрошенного сервера соответствовало имени в сертификате
В Разделе 31.18 приведено подробное описание работы этих режимов.
sslmode
игнорируется при использовании Unix-сокетов. Если PostgreSQL скомпилирован без поддержки SSL, использование параметровrequire
,verify-ca
илиverify-full
приведёт к ошибке, в то время как параметрыallow
иprefer
будут приняты, но libpq в действительности не будет пытаться установить SSL-соединение.requiressl
Использовать этот параметр не рекомендуется, в качестве замены предлагается установить
sslmode
.Если установлено значение 1, то требуется SSL-соединение с сервером (это эквивалентно
sslmode
require
). libpq в таком случае откажется подключаться, если сервер не принимает SSL-соединений. Если установлено значение 0 (по умолчанию), тогда libpq будет согласовывать тип подключения с сервером (эквивалентноsslmode
prefer
). Этот параметр доступен, если только PostgreSQL скомпилирован с поддержкой SSL.sslcompression
Если установлено значение 1 (по умолчанию), данные, пересылаемые через SSL-соединения, будут сжиматься (это требует OpenSSL версии 0.9.8 или более поздней). Если установлено значение 0, сжатие будет отключено (это требует OpenSSL версии 1.0.0 или более поздней). Этот параметр игнорируется, если выполнено подключение без SSL, или если используемая версия OpenSSL не поддерживает его.
Сжатие требует процессорного времени, но может улучшить пропускную способность, если узким местом является сеть. Отключение сжатия может улучшить время отклика и пропускную способность, если ограничивающим фактором является производительность CPU.
sslcert
Этот параметр предписывает имя файла для SSL-сертификата клиента, заменяющего файл по умолчанию
~/.postgresql/postgresql.crt
. Этот параметр игнорируется, если SSL-подключение не выполнено.sslkey
Этот параметр предписывает местоположение секретного ключа, используемого для сертификата клиента. Он может либо указывать имя файла, которое будет использоваться вместо имени по умолчанию
~/.postgresql/postgresql.key
, либо он может указывать ключ, полученный от внешнего «криптомодуля» (криптомодули — это загружаемые модули OpenSSL). Спецификация внешнего криптомодуля должна состоять из имени модуля и ключевого идентификатора, зависящего от конкретного модуля, разделённых двоеточием. Этот параметр игнорируется, если SSL-подключение не выполнено.sslrootcert
Этот параметр указывает имя файла, содержащего SSL-сертификаты, выданные Центром сертификации (CA). Если файл существует, сертификат сервера будет проверен на предмет его подписания одним из этих центров. Имя по умолчанию —
~/.postgresql/root.crt
.sslcrl
Этот параметр указывает имя файла, содержащего список отозванных SSL-сертификатов (CRL). Сертификаты, перечисленные в этом файле, если он существует, будут отвергаться при попытке установить подлинность сертификата сервера. Имя по умолчанию такое
~/.postgresql/root.crl
.requirepeer
Этот параметр указывает имя пользователя операционной системы, предназначенное для сервера, например,
requirepeer=postgres
. При создании подключения через Unix-сокет, если этот параметр установлен, клиент проверяет в самом начале процедуры подключения, что серверный процесс запущен от имени указанного пользователя; если это не так, соединение аварийно прерывается с ошибкой. Этот параметр можно использовать, чтобы обеспечить аутентификацию сервера, подобную той, которая доступна с помощью SSL-сертификатов при соединениях по протоколу TCP/IP. (Заметьте, что если Unix-сокет находится в каталоге/tmp
или в другом каталоге, запись в который разрешена всем пользователям, тогда любой пользователь сможет запустить сервер, прослушивающий сокет в том каталоге. Используйте этот параметр, чтобы гарантировать, что вы подключены к серверу, запущенному доверенным пользователем.) Он поддерживается только на платформах, для которых реализован метод аутентификацииpeer
; см. Подраздел 19.3.6.krbsrvname
Имя сервиса Kerberos, предназначенное для использования при аутентификации на основе GSSAPI. Оно должно соответствовать имени сервиса, указанному в конфигурации сервера, чтобы аутентификация на основе Kerberos прошла успешно. (См. также Подраздел 19.3.3.)
gsslib
Библиотека GSS, предназначенная для использования при аутентификации на основе GSSAPI. В настоящее время это действует только в сборках для Windows, поддерживающих одновременно и GSSAPI, и SSPI. Значение
gssapi
в таких сборках позволяет указать, что libpq должна использовать для аутентификации библиотеку GSSAPI, а не подразумеваемую по умолчанию SSPI.service
Имя сервиса, используемое для задания дополнительных параметров. Оно указывает имя сервиса в файле
pg_service.conf
, который содержит дополнительные параметры подключения. Это позволяет приложениям указывать только имя сервиса, поскольку параметры подключения могут поддерживаться централизованно. См. Раздел 31.16.