Postgres Pro Enterprise
1817161514131211109.6
Postgres Pro Standard
1817161514131211109.6
RUENRU EN
pgbouncer
Пред. НаверхG.2. Серверные приложенияНачало След.

pgbouncer

pgbouncer — пул соединений Postgres Pro

Синтаксис

В системах Linux:

pgbouncer [-d] [-R] [-v] [-u пользователь] pgbouncer.ini

pgbouncer -V | -h

В Windows:

pgbouncer [-v] [-u пользователь] pgbouncer.ini

pgbouncer -V | -h

Для использования pgbouncer в виде службы Windows есть дополнительные аргументы:

pgbouncer.exe --regservice pgbouncer.ini

pgbouncer.exe --unregservice pgbouncer.ini

Описание

pgbouncer — это программа, управляющая пулом соединений Postgres Pro. Любое конечное приложение может подключиться к pgbouncer, как если бы это был непосредственно сервер Postgres Pro, и pgbouncer создаст подключение к реальному серверу, либо задействует одно из ранее установленных подключений.

Предназначение pgbouncer — минимизировать издержки, связанные с установлением новых подключений к Postgres Pro.

Чтобы не нарушать семантику транзакций при переключении подключений, pgbouncer поддерживает несколько видов пулов:

Пул сеансов

Наиболее корректный метод. Когда клиент подключается, ему назначается одно серверное подключение на всё время, пока клиент остаётся подключённым. Когда клиент отключается, это подключение к серверу возвращается в пул. Этот метод работает по умолчанию.

Пул транзакций

Подключение к серверу назначается клиенту только на время транзакции. Когда pgbouncer замечает, что транзакция завершена, это подключение возвращается в пул.

Пул операторов

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

Административный интерфейс pgbouncer состоит из нескольких новых команд SHOW, доступных при подключении к специальной «виртуальной» базе данных pgbouncer.

Быстрый запуск

Базовая настройка и использование демонстрируются ниже.

  1. Создайте файл pgbouncer.ini. Подробнее он описывается на странице man pgbouncer(5). Например:

    [databases]
template1 = host=localhost dbname=template1 auth_user=someuser

[pgbouncer]
listen_port = 6432
listen_addr = localhost
auth_type = md5
auth_file = userlist.txt
logfile = pgbouncer.log
pidfile = pgbouncer.pid
admin_users = someuser

  2. Создайте файл userlist.txt со списком пользователей, которым разрешено подключение:

    "некоторый_пользователь" "его_пароль_на_сервере"

  3. Запустите pgbouncer:

    $ pgbouncer -d pgbouncer.ini

    Примечание

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

    pgbouncer --regservice

  4. Сделайте так, чтобы ваше приложение (или клиент psql) подключалось к pgbouncer, а не к серверу Postgres Pro непосредственно:

    $ psql -p 6432 -U someuser template1

  5. Для управления pgbouncer подключитесь к специальной административной базе данных pgbouncer и выполните SHOW HELP;, чтобы ознакомиться с его справкой:

    $ psql -p 6432 -U someuser pgbouncer
pgbouncer=# SHOW HELP;
NOTICE:  Console usage
DETAIL:
  SHOW [HELP|CONFIG|DATABASES|FDS|POOLS|CLIENTS|SERVERS|SOCKETS|LISTS|VERSION|...]
  SET key = arg
  RELOAD
  PAUSE
  SUSPEND
  RESUME
  SHUTDOWN
  [...]

  6. Если вы вносили изменения в файл pgbouncer.ini, его можно перезагрузить командой:

    pgbouncer=# RELOAD;

Параметры

-d, --daemon

Запустить в фоновом режиме. Без этого указания процесс будет работать на переднем плане. При запуске в фоновом режиме необходимо явное указание параметра pidfile, а также logfile или syslog. В фоновом режиме сообщения не будут записываться в stderr.

Примечание

Это не работает в Windows, там pgbouncer нужно запускать в виде службы.

-R, --reboot

Примечание

Этот параметр устарел. Вместо него следует применять последовательный перезапуск с несколькими процессами pgbouncer с одним и тем же принимающим портом, используя so_reuseport.

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

Примечание

Это работает, только если ОС поддерживает сокеты Unix и в конфигурации определён параметр unix_socket_dir. Не работает в Windows. Также при этом не поддерживаются подключения TLS, они сбрасываются.

-u пользователь, --user пользователь

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

-v, --verbose

Увеличить детализацию вывода. Может использоваться неоднократно.

-q, --quiet

Приглушить вывод: не выводить ничего в stderr. Это не влияет на уровень выводимых сообщений, а только отключает вывод в stderr. Предназначено для применения в скриптах init.d.

-V, --version

Вывести версию.

-h, --help

Вывести короткую справку.

--regservice

Win32: Зарегистрировать pgbouncer в качестве службы Windows. Имя службы будет определяться значением параметра конфигурации service_name.

--unregservice

Win32: Разрегистрировать службу Windows.

Административная консоль

Эта консоль доступна при обычном подключении к базе pgbouncer:

$ psql -p 6432 pgbouncer

Подключаться к этой консоли разрешено только пользователям, перечисленным в параметрах конфигурации admin_users или stats_users. (За исключением режима auth_mode=any, когда в качестве stats_user может подключиться любой пользователь.)

Кроме того, пользователю pgbouncer разрешено подключение без пароля, если это подключение устанавливается через сокет Unix и у клиента тот же uid пользователя Unix, что и у работающего процесса.

Административная консоль в настоящее время поддерживает только простой протокол запросов. Некоторые драйверы используют расширенный протокол запросов для всех команд; эти драйверы не будут работать в данном случае.

Команды вывода информации

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

SHOW STATS

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

database

База данных, для которой представлена статистика.

total_xact_count

Общее число транзакций SQL, прошедших через pgbouncer.

total_query_count

Общее число SQL-запросов, прошедших через pgbouncer.

total_received

Общий объём сетевого трафика (в байтах), который получил pgbouncer.

total_sent

Общий объём сетевого трафика (в байтах), который передал pgbouncer.

total_xact_time

Общее время (в микросекундах), в течение которого pgbouncer использовал подключения к Postgres Pro, выполняя запросы или простаивая.

total_query_time

Общее время (в микросекундах), в течение которого pgbouncer активно использовал подключения к Postgres Pro, выполняя запросы.

total_wait_time

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

avg_xact_count

Среднее число транзакций в секунду за последний период статистики.

avg_query_count

Среднее число запросов в секунду за последний период статистики.

avg_recv

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

avg_sent

Средняя скорость передачи данных клиентам (байт в секунду).

avg_xact_time

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

avg_query_time

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

avg_wait_time

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

SHOW STATS_TOTALS

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

SHOW STATS_AVERAGES

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

SHOW TOTALS

Выводит ту же статистику, что SHOW STATS, но по всем базам данных в целом.

SHOW SERVERS

type

«S» для серверов

user

Имя пользователя, с которым pgbouncer подключается к серверу.

database

Имя базы данных.

state

Состояние подключения pgbouncer к серверу, один из вариантов: active, idle, used, tested, new, active_cancel или being_canceled.

addr

IP-адрес сервера Postgres Pro.

port

Порт сервера Postgres Pro.

local_addr

Исходный адрес подключения на локальной машине.

local_port

Исходный порт подключения на локальной машине.

connect_time

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

request_time

Время выдачи последнего запроса.

wait

Не используется для серверных подключений.

wait_us

Не используется для серверных подключений.

close_needed

1, если соединение будет закрыто при ближайшей возможности в связи с выполнением команды RECONNECT либо в связи с изменением параметров соединения, вызванным перезагрузкой файла конфигурации или изменениями в DNS.

ptr

Адрес внутреннего объекта для данного подключения. Используется как уникальный идентификатор.

link

Адрес клиентского подключения, с которым связан сервер.

remote_pid

Идентификатор обслуживающего серверного процесса (PID). Когда подключение выполняется через сокет Unix и ОС может выдать PID процесса, это PID, полученный от ОС. В противном случае этот идентификатор извлекается из пакета для отмены, переданного сервером; это будет интересующий PID при подключении к серверу Postgres Pro, но если подключение обслуживает другой pgbouncer, это будет случайное число.

tls

Информация о TLS-подключении; пустая строка, если TLS не используется.

application_name

Строка, содержащая параметр application_name, заданный для связанного клиентского подключения, или пустая строка, если он не задан или если подключение отсутствует.

SHOW CLIENTS

type

«C» для клиентов.

user

Пользователь, подключённый со стороны клиента.

database

Имя базы данных.

state

Состояние клиентского подключения: active, waiting, active_cancel_req или waiting_cancel_req.

addr

IP-адрес клиента.

port

Порт клиента.

local_addr

Конечный адрес подключения на локальной машине.

local_port

Конечный порт подключения на локальной машине.

connect_time

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

request_time

Время последнего запроса клиента.

wait

Текущая длительность ожидания (в секундах).

wait_us

Дробная часть текущей длительности ожидания (в микросекундах).

close_needed

Не используется для клиентов.

ptr

Адрес внутреннего объекта для данного подключения. Используется как уникальный идентификатор.

link

Адрес серверного подключения, с которым связан клиент.

remote_pid

Идентификатор процесса (PID), в случае, если клиент подключается через сокет UNIX и ОС может выдать этот идентификатор.

tls

Информация о TLS-подключении; пустая строка, если TLS не используется.

application_name

Строка, содержащая параметр application_name, заданный клиентом для данного подключения, или пустая строка, если он не задан или если подключение отсутствует.

SHOW POOLS

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

database

Имя базы данных.

user

Имя пользователя.

cl_active

Число клиентских подключений, которые либо связаны с подключениями к серверу, либо простаивают без запросов, ожидающих обработки.

cl_waiting

Число клиентских подключений, которые отправили запросы, но ещё не получили подключения к серверу.

cl_active_cancel_req

Число клиентских подключений, которые передали серверу команды отмены запроса и ожидают ответ сервера.

cl_waiting_cancel_req

Число клиентских подключений, для которых серверу в данный момент передаются команды отмены запросов.

sv_active

Число серверных подключений, связанных с клиентами.

sv_active_cancel

Число серверных подключений, для которых в данный момент передаются команды отмены запросов.

sv_being_canceled

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

sv_idle

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

sv_used

Число серверных подключений, которые простаивают дольше server_check_delay, поэтому перед повторным использованием для них нужно выполнять server_check_query.

sv_tested

Число серверных подключений, для которых в данный момент выполняются запросы server_reset_query или server_check_query.

sv_login

Число серверных подключений, через которые в данный момент выполняется вход на сервер.

maxwait

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

maxwait_us

Дробная часть максимального времени ожидания (в микросекундах).

pool_mode

Действующий режим пула.

SHOW PEER_POOLS

Для каждого настроенного узла создаётся новая запись peer_pool.

database

Идентификатор настроенной записи узла.

cl_active_cancel_req

Число клиентских подключений, которые передали серверу команды отмены запроса и ожидают ответ сервера.

cl_waiting_cancel_req

Число клиентских подключений, для которых серверу в данный момент передаются команды отмены запросов.

sv_active_cancel

Число серверных подключений, для которых в данный момент передаются команды отмены запросов.

sv_login

Число серверных подключений, через которые в данный момент выполняется вход на сервер.

SHOW LISTS

Показывает следующие внутренние сведения, в столбцах (не строках):

databases

Число баз данных.

users

Число пользователей.

pools

Число пулов.

free_clients

Число свободных клиентов.

used_clients

Число активных клиентов.

login_clients

Число клиентов в состоянии входа (login).

free_servers

Число свободных серверов.

used_servers

Число задействованных серверов.

dns_names

Количество имён DNS в кеше.

dns_zones

Количество зон DNS в кеше.

dns_queries

Количество выполняющихся запросов к DNS.

dns_pending

Не используется.

SHOW USERS

name

Имя пользователя.

pool_mode

Переопределение pool_mode для пользователя либо NULL, если должен использоваться режим по умолчанию.

SHOW DATABASES

name

Имя настроенной записи базы данных.

host

Узел, к которому подключается pgbouncer.

port

Порт, к которому подключается pgbouncer.

database

Реальное имя базы данных, к которой подключается pgbouncer.

force_user

Когда пользователь указан в строке соединения, подключение между pgbouncer и Postgres Pro должно устанавливаться от его имени, вне зависимости от пользователя на стороне клиента.

pool_size

Максимальное число серверных подключений.

min_pool_size

Минимальное число серверных подключений.

reserve_pool

Максимальное число дополнительных подключений для этой базы данных.

pool_mode

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

max_connections

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

current_connections

Текущее число подключений для этой базы.

paused

1, если база данных находится в состоянии паузы, иначе — 0.

disabled

1, если база данных находится в отключённом состоянии, иначе — 0.

SHOW PEERS

peer_id

Идентификатор настроенной записи узла.

host

Узел, к которому подключается pgbouncer.

port

Порт, к которому подключается pgbouncer.

pool_size

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

SHOW FDS

Внутренняя команда, которая показывает список файловых дескрипторов и их внутреннее состояние.

При подключении пользователя с именем pgbouncer через сокет Unix из процесса с UID, совпадающим с UID текущего процесса, ему передаются реальные файловые дескрипторы. Это применяется для выполнения перезагрузки «на лету».

Примечание

В Windows это не работает.

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

fd

Числовое значение файлового дескриптора (ФД).

task

Предназначение; возможны следующие варианты: pooler, client или server.

user

Пользователь подключения, занимающего этот ФД.

database

База данных подключения, занимающего этот ФД.

addr

IP-адрес подключения, занимающего данный ФД; unix, если это сокет Unix.

port

Порт подключения, занимающего данный ФД.

cancel

Ключ отмены для данного подключения.

link

Файловый дескриптор ответной стороны сервера/клиента. NULL, если подключение простаивает.

SHOW SOCKETS, SHOW ACTIVE_SOCKETS

Выводит низкоуровневую информацию обо всех или только активных сокетах. В вывод включается информация, выводимая командами SHOW CLIENTS и SHOW SERVERS, а также дополнительные сведения низкого уровня.

SHOW CONFIG

Выводит текущие параметры конфигурации, по одному в строке со следующими столбцами:

key

Имя переменной конфигурации.

value

Значение переменной конфигурации.

default

Значение по умолчанию.

changeable

Значение yes или no, показывающее, можно ли изменить переменную во время работы. Если значение no, переменная может быть изменена только при перезагрузке. Чтобы изменить переменную во время работы, воспользуйтесь командой SET.

SHOW MEM

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

SHOW DNS_HOSTS

Выводит имена узлов, содержащиеся в кеше DNS.

hostname

Имя узла.

ttl

Сколько секунд остаётся до очередного внешнего поиска.

addrs

Список адресов, разделённых запятыми.

SHOW DNS_ZONES

Показывает зоны DNS в кеше.

zonename

Имя зоны.

serial

Текущий серийный номер.

count

Имена узлов, относящихся к этой зоне.

SHOW VERSION

Показывает строку с версией pgbouncer.

SHOW STATE

Показывает параметры состояния pgbouncer. Текущие состояния: активное, состояние паузы и приостановленное.

Команды управления процессом

PAUSE [бд]

pgbouncer пытается отключиться от всех серверов. При закрытии каждого подключения к серверу ожидается освобождение этого подключения в соответствии с режимом пула серверов (в режиме пула транзакций должна завершиться транзакция, в режиме пула операторов должен завершиться оператор, а в режиме пула сеансов должен отключиться клиент). Выполнение этой команды заканчивается, только когда отключатся все подключения. Эта команда должна применяться во время перезапуска базы данных.

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

Новые подключения клиентов к базе, поставленной на паузу, будут находиться в состоянии ожидания, пока не будет выполнена команда RESUME.

DISABLE бд

Запрещает любые новые подключения клиентов к указанной базе данных.

ENABLE бд

Разрешает новые подключения клиентов после предыдущей команды DISABLE.

RECONNECT бд

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

Эта команда может быть полезна, когда изменяется конфигурация подключения к серверу, например, нужно постепенно переключиться на новый сервер. Эту команду не нужно выполнять, если вы меняете строку соединения в pgbouncer.ini и перезагружаете конфигурацию (см. RELOAD) или когда меняются адреса в DNS, так как равнозначное действие будет выполнено автоматически. Эта команда может быть полезна, только если подключения pgbouncer маршрутизируются какими-то внешними средствами.

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

KILL бд

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

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

SUSPEND

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

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

RESUME [бд]

Восстанавливает работу после предыдущей команды KILL, PAUSE или SUSPEND.

SHUTDOWN

Приводит к завершению процесса pgbouncer.

RELOAD

Указывает процессу pgbouncer перезагрузить файлы конфигурации и обновить значения изменяемых параметров, а именно основной файл конфигурации, а также файлы, указанные в параметрах auth_file и auth_hba_file.

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

WAIT_CLOSE [бд]

Ожидает, пока для всех серверных подключений к указанной базе (или ко всем базам) не сбросится признак close_needed (см. Подраздел «SHOW SERVERS»). Эту команду можно вызвать после RECONNECT или RELOAD, чтобы, например, в скриптах переключения узлов, дождаться применения изменений конфигураций в полном объёме.

Другие команды

SET ключ = аргумент

Изменяет параметр конфигурации (см. также Подраздел «SHOW CONFIG»). Например:

SET log_connections = 1;
SET server_check_query = 'select 2';

(Заметьте, что эта команда выполняется в консоли администратора pgbouncer и задаёт параметры pgbouncer. Команда SET, выполненная в другой базе данных, будет передана на выполнению серверу Postgres Pro, как и любая другая SQL-команда.)

Сигналы

SIGHUP

Перезагрузка конфигурации. Равносильно выполнению команды RELOAD в консоли.

SIGINT

Безопасное отключение. Равносильно выполнению команд PAUSE и SHUTDOWN в консоли.

SIGTERM

Немедленное отключение. Равносильно выполнению команды SHUTDOWN в консоли.

SIGUSR1

Равносильно выполнению команды PAUSE в консоли.

SIGUSR2

Равносильно выполнению команды PAUSE в консоли.

Параметры libevent

Из документации libevent:

Поддержку epoll, kqueue, devpoll, poll или select можно отключить, установив переменную окружения