Открыть страницу поиска
Привет, Я DocuDroid!
Открыть страницу ИИ Помощника
Оценка ИИ поиска
Спасибо за оценку нашего ИИ поиска!
Мы будем признательны, если вы поделитесь своими впечатлениями, чтобы мы могли улучшить наш ИИ поиск для вас и других читателей.
GitHub

Настройка и использование PgBouncer

Андрей Аксенов

PgBouncer — это легковесный менеджер пулов подключений к базам данных для PostgreSQL и Greengage DB.

В этом разделе описывается, как настроить и использовать PgBouncer с Greengage DB. Информацию об использовании PgBouncer с PostgreSQL см. на сайте PgBouncer.

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

Не используйте заданные в коде секреты в production-средах. Всегда следуйте рекомендациям по безопасной работе с данными:

  • Храните секреты в специализированных системах управления секретами (например, HashiCorp Vault).

  • Используйте переменные окружения или защищенные файлы конфигурации с ограниченными правами доступа.

  • Реализуйте регулярную ротацию ключей и применяйте надежные политики паролей.

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

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

Обзор

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

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

PgBouncer поддерживает три режима работы пула подключений:

  • Пул на уровне сессии (session pooling) — закрепляет серверное подключение за клиентом на всю сессию (режим по умолчанию).

  • Пул на уровне транзакции (transaction pooling) — выделяет подключение только на время выполнения транзакции и возвращает его в пул после ее завершения.

  • Пул на уровне запроса (statement pooling) — возвращает подключение в пул сразу после выполнения каждого запроса; транзакции из нескольких операторов не поддерживаются.

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

PgBouncer поддерживает стандартный для PostgreSQL/Greengage DB интерфейс подключения. Клиенты подключаются к хосту и порту PgBouncer, а не напрямую к мастеру.

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

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

Предварительные требования

Подготовка хостов

Для демонстрации интеграции кластера Greengage DB с PgBouncer используются следующие хосты:

  • Хост PgBouncer: полное доменное имя — pgbouncer.example.com, IP-адрес — 192.168.1.5.

  • Мастер-хост: полное доменное имя — mdw.example.com, IP-адрес — 192.168.1.10.

  • Клиентский хост: полное доменное имя — client.example.com, IP-адрес — 192.168.1.155.

  • Хост сервера каталогов (FreeIPA): имя — ipa.example.com, полное доменное имя — ipa.example.com.

Примечания по программному обеспечению и настройке:

  • Убедитесь, что выполнена инициализация СУБД (см. Инициализация СУБД).

  • На хосте PgBouncer должны быть установлены git и make.

Создание ролей

Перед использованием PgBouncer необходимо создать роли для административного и клиентского доступа. В этом примере создаются роль суперпользователя (dba) и роль обычного пользователя (alice).

Создайте роль dba, используя createuser:

$ createuser --pwprompt --superuser --echo dba

При появлении запроса введите пароль для новой роли. Пример вывода:

Enter password for new role:
Enter it again:
SELECT pg_catalog.set_config('search_path', '', false)
CREATE ROLE dba PASSWORD 'md556f6af8d612ee0840a32c255091f41a8' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;

MD5-хеш, полученный в результате выполнения CREATE ROLE, будет использован позже при настройке файла аутентификации PgBouncer.

Создайте роль alice:

$ createuser alice

Позже эта роль используется в примере настройки LDAP-аутентификации.

Установка PgBouncer

Клонирование репозитория Greengage DB

Чтобы установить PgBouncer из исходного кода, выполните следующие действия:

  1. Войдите на хост PgBouncer под пользователем с правами sudo.

  2. Клонируйте репозиторий Greengage DB с подмодулями:

    $ git clone --recurse-submodules https://github.com/GreengageDB/greengage.git

  3. Перейдите в каталог greengage:

    $ cd greengage

  4. Переключитесь на нужный тег, например:

    $ git checkout 6.30.1

  5. Обновите подмодули:

    $ git submodule update --init --recursive

Сборка PgBouncer из исходного кода

  1. Перейдите в каталог source PgBouncer:

    $ cd gpAux/extensions/pgbouncer/source

  2. Подготовьте систему сборки с помощью autogen.sh:

    $ ./autogen.sh

  3. Настройте сборку. Параметр --with-ldap добавляет поддержку LDAP:

    $ ./configure --prefix=/usr/local --with-ldap

  4. Скомпилируйте PgBouncer:

    $ make -j$(nproc)

  5. Установите PgBouncer:

    $ sudo make install

    Пример вывода:

    INSTALL  pgbouncer /usr/local/bin
INSTALL  README.md /usr/local/share/doc/pgbouncer
INSTALL  NEWS.md /usr/local/share/doc/pgbouncer
INSTALL  etc/pgbouncer-minimal.ini /usr/local/share/doc/pgbouncer
INSTALL  etc/pgbouncer.ini /usr/local/share/doc/pgbouncer
INSTALL  etc/pgbouncer.service /usr/local/share/doc/pgbouncer
INSTALL  etc/pgbouncer.socket /usr/local/share/doc/pgbouncer
INSTALL  etc/userlist.txt /usr/local/share/doc/pgbouncer

Информацию о дополнительных параметрах установки см. в документации PgBouncer.

Настройка PgBouncer

Создание конфигурационного файла PgBouncer

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

В данном разделе предполагается, что файл pgbouncer.ini расположен в домашнем каталоге. Перейдите в него:

$ cd

Создайте файл pgbouncer.ini:

$ vi pgbouncer.ini

Добавьте в файл следующие записи:

[databases]
postgres = host=192.168.1.10 port=5432 dbname=postgres

[pgbouncer]
pool_mode = session
listen_addr = 192.168.1.5
listen_port = 6432
auth_type = md5
auth_file = userlist.txt
admin_users = dba
logfile = pgbouncer.log
pidfile = pgbouncer.pid

где:

[databases]

Сопоставляет имена баз данных, используемые клиентом (ключи), с фактическими параметрами подключения (значения) в формате libpq-строк:

  • host — имя или IP-адрес мастер-хоста.

  • port — порт мастер-хоста.

  • dbname — имя целевой базы данных.

[pgbouncer]
pool_mode

Определяет режим работы пула подключений (см. Обзор). Допустимые значения: session, transaction и statement.

listen_addr/listen_port

IP-адрес и порт, на которых PgBouncer принимает входящие клиентские подключения.

auth_type

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

auth_file

Файл, в котором перечислены пользователи и их пароли; используется совместно с параметром auth_type.

admin_users

Список пользователей, которым разрешено выполнять административные команды; имена пользователей разделяются запятыми.

logfile/pidfile

Пути к лог-файлу и PID-файлу PgBouncer.

Создание файла аутентификации PgBouncer

PgBouncer использует файл аутентификации пользователей, указанный в параметре auth_file в pgbouncer.ini. Это текстовый файл, содержащий по одному пользователю на строку в одном из следующих форматов:

"<username1>" "<password>"
"<username2>" "md5<encoded_password>"
"<username3>" "SCRAM-SHA-256$<iterations>:<salt>$<storedkey>:<serverkey>"

Каждая строка содержит два поля, заключенных в двойные кавычки (" "):

  • Первое поле — имя роли Greengage DB.

  • Второе поле — пароль в открытом виде, в формате MD5 или в виде SCRAM-секрета.

Создайте файл userlist.txt:

$ vi userlist.txt

Добавьте следующую строку:

"dba" "md556f6af8d612ee0840a32c255091f41a8"

Хеш MD5 — это значение, которое возвращает оператор CREATE ROLE при создании роли dba (см. Создание ролей). Эта запись позволяет пользователю dba аутентифицироваться через PgBouncer с использованием указанного MD5-хеша. Обратите внимание: хеш пароля в этом примере приведен исключительно в демонстрационных целях.

Также можно настроить PgBouncer на использование аутентификации по имени хоста (Host-Based Authentication, HBA) вместо статического файла. Если в pgbouncer.ini задан параметр auth_type = hba, PgBouncer считывает правила аутентификации из файла, указанного в auth_hba_file; этот файл использует тот же формат, что и pg_hba.conf.

Разрешение подключений PgBouncer в pg_hba.conf

Чтобы разрешить PgBouncer подключаться к мастеру Greengage DB, добавьте запись для хоста PgBouncer в файл pg_hba.conf на мастер-хосте.

Откройте pg_hba.conf для редактирования:

$ vi $MASTER_DATA_DIRECTORY/pg_hba.conf

Добавьте следующую строку:

# connection-type  database  user  address         auth-method
host               postgres  all   192.168.1.5/32  trust

Эта запись разрешает подключения к базе данных postgres с хоста PgBouncer (192.168.1.5) для всех пользователей.

После обновления файла перезагрузите конфигурацию Greengage DB:

$ gpstop -u

Запуск PgBouncer

Используйте команду pgbouncer, чтобы запустить PgBouncer с созданным файлом конфигурации:

$ pgbouncer -d pgbouncer.ini

Параметр -d запускает PgBouncer как фоновый процесс. Файл pgbouncer.ini задает конфигурацию PgBouncer.

Подключение через PgBouncer

Теперь вы можете подключиться к базе данных через PgBouncer под пользователем dba. Укажите хост и порт PgBouncer при выполнении команды на клиентском хосте:

$ psql postgres -U dba -h 192.168.1.5 -p 6432

Введите пароль при появлении запроса:

Password for user dba:

psql отобразит следующее приглашение:

psql (9.4.26)
Type "help" for help.

postgres=#

Управление PgBouncer

PgBouncer предоставляет административную консоль, похожую на psql. Чтобы получить к ней доступ, подключитесь к специальной виртуальной базе данных pgbouncer на порте PgBouncer. Консоль принимает SQL-подобные команды для мониторинга, управления и изменения конфигурации PgBouncer.

Подключение к административной консоли PgBouncer

Используйте psql для подключения к виртуальной базе данных pgbouncer:

$ psql pgbouncer -U dba -p 6432

Имя пользователя должно быть указано в параметре admin_users в файле pgbouncer.ini. Также можно войти под текущим именем пользователя Unix, если процесс PgBouncer запущен с соответствующим UID.

Введите пароль. Должна появиться командная строка PgBouncer:

pgbouncer=#

Чтобы просмотреть доступные команды консоли администрирования PgBouncer, выполните следующую команду:

SHOW HELP;

Пример вывода:

NOTICE:  Console usage
DETAIL:
        SHOW HELP|CONFIG|DATABASES|POOLS|CLIENTS|SERVERS|USERS|VERSION
        SHOW PEERS|PEER_POOLS
        SHOW FDS|SOCKETS|ACTIVE_SOCKETS|LISTS|MEM|STATE
        SHOW DNS_HOSTS|DNS_ZONES
        SHOW STATS|STATS_TOTALS|STATS_AVERAGES|TOTALS
        SET key = arg
        RELOAD
        PAUSE [<db>]
        RESUME [<db>]
        DISABLE <db>
        ENABLE <db>
        RECONNECT [<db>]
        KILL <db>
        SUSPEND
        SHUTDOWN
        WAIT_CLOSE [<db>]

Просмотр текущего статуса PgBouncer

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

Команда SHOW SERVERS отображает информацию о подключениях PgBouncer к серверным процессам СУБД, включая состояние подключения, базу данных и пользователя:

SHOW SERVERS;

Пример вывода:

type | user | database | state | addr         | port | local_addr  | local_port | connect_time            | request_time            | wait | wait_us | close_needed | ptr            | link | remote_pid | tls | application_name | prepared_statements
-----+------+----------+-------+--------------+------+-------------+------------+-------------------------+-------------------------+------+---------+--------------+----------------+------+------------+-----+------------------+--------------------
S    | dba  | postgres | used  | 192.168.1.10 | 5432 | 192.168.1.5 | 56126      | 2026-03-02 12:29:16 UTC | 2026-03-02 12:29:16 UTC | 0    | 0       | 0            | 0x556149d6fd20 |      | 3846       |     |                  | 0

В этом примере 192.168.1.10 — IP-адрес мастер-хоста Greengage DB.

Команда SHOW CLIENTS отображает информацию об активных подключениях клиентов к PgBouncer, включая состояние подключения, адреса, порты и подготовленные операторы:

SHOW CLIENTS;

Пример вывода:

type | user | database  | state  | addr          | port  | local_addr  | local_port | connect_time            | request_time            | wait | wait_us | close_needed | ptr            | link | remote_pid | tls | application_name | prepared_statements
-----+------+-----------+--------+---------------+-------+-------------+------------+-------------------------+-------------------------+------+---------+--------------+----------------+------+------------+-----+------------------+--------------------
C    | dba  | pgbouncer | active | unix          | 6432  | unix        | 6432       | 2026-03-02 12:36:15 UTC | 2026-03-02 12:36:16 UTC | 0    | 0       | 0            | 0x556149d12cd0 |      | 4072       |     | psql             | 0
C    | dba  | postgres  | active | 192.168.1.155 | 14148 | 192.168.1.5 | 6432       | 2026-03-02 12:29:16 UTC | 2026-03-02 12:29:16 UTC | 0    | 0       | 0            | 0x556149d13380 |      | 0          |     | psql             | 0

В этом примере:

  • Первая строка показывает, что пользователь dba подключен через локальный сокет домена Unix (addr = unix) к виртуальной базе данных pgbouncer.

  • Вторая строка показывает, что пользователь dba подключен удаленно по TCP с IP-адреса клиента 192.168.1.155 к базе данных postgres.

Перезагрузка конфигурации PgBouncer

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

RELOAD;

Настройка LDAP-аутентификации

PgBouncer поддерживает LDAP-аутентификацию, позволяя аутентифицировать пользователей через службу каталогов вашей организации (например, Active Directory или 389 Directory Server) перед подключением к кластеру Greengage DB.

В этом разделе показано, как интегрировать PgBouncer со службой каталогов FreeIPA.

Предварительные требования для LDAP-аутентификации

См. раздел LDAP-аутентификация для получения подробной информации о предварительных требованиях и шагах настройки.

Включение аутентификации по имени хоста в PgBouncer

Для использования LDAP-аутентификации включите аутентификацию по имени хоста в PgBouncer.

Отредактируйте файл pgbouncer.ini:

$ vi pgbouncer.ini

Измените конфигурацию следующим образом:

# ...
auth_type = hba
auth_hba_file = hba_bouncer.conf
# ...

Далее создайте файл конфигурации hba_bouncer.conf в том же каталоге, что и pgbouncer.ini:

$ vi hba_bouncer.conf

Чтобы сохранить локальный доступ для пользователя dba без LDAP-аутентификации, добавьте следующую запись:

# connection-type  database  user     auth-method
local              all       dba      trust

Аутентификация LDAP без bind DN (анонимная привязка)

Чтобы включить LDAP-аутентификацию для конкретного пользователя без использования bind DN, отредактируйте hba_bouncer.conf:

$ vi hba_bouncer.conf

Добавьте следующую запись:

# connection-type  database  user   address           auth-method  auth-options
host               postgres  alice  192.168.1.155/32  ldap         ldapserver=ipa.example.com ldapprefix="uid=" ldapsuffix=",cn=users,cn=accounts,dc=example,dc=com"

Перезагрузите конфигурацию PgBouncer, как описано в разделе Перезагрузка конфигурации PgBouncer. Затем проверьте подключение с клиентского хоста:

$ psql postgres -U alice -h 192.168.1.5 -p 6432

Введите пароль пользователя LDAP:

Password for user alice:

Результат:

psql (9.4.26)
Type "help" for help.

postgres=>

Аутентификация LDAP с bind DN

Некоторые LDAP-серверы используют bind DN (привилегированную учетную запись) для поиска пользователей и аутентификации. Настройте PgBouncer на использование bind DN и пароля при подключении к LDAP-серверу.

Отредактируйте hba_bouncer.conf и добавьте следующую запись:

# connection-type  database  user   address           auth-method  auth-options
host               postgres  alice  192.168.1.155/32  ldap         ldapserver=ipa.example.com ldapbasedn="cn=users,cn=accounts,dc=example,dc=com" ldapbinddn="uid=admin,cn=users,cn=accounts,dc=example,dc=com" ldapbindpasswd="12345678"

В этом примере значение ldapbindpasswd указано в открытом виде. В production-средах используйте зашифрованные учетные данные для привязки.

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

Защита учетных данных LDAP bind

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

Генерация ключа шифрования

Сгенерируйте файл ключа ldkeyfile для шифрования пароля LDAP:

$ openssl rand -base64 256 | tr -d '\n' > ldkeyfile

Зашифруйте пароль LDAP (12345678 в этом примере) с помощью файла ключа:

$ ENCRYPTED_PASSWD=$(echo -n "12345678" | openssl enc -aes-256-cbc -base64 -md sha256 -pass file:ldkeyfile)

Сохраните зашифрованный пароль в файл .ldapbindpass в домашнем каталоге:

$ echo -n $ENCRYPTED_PASSWD > "${HOME}/.ldapbindpass"

Настройка зашифрованных учетных данных LDAP bind

Отредактируйте файл pgbouncer.ini, указав расположение файла ключа и используемый шифр:

# ...
auth_key_file = ldkeyfile
auth_cipher = aes-256-cbc
# ...

Обновите HBA-конфигурацию (hba_bouncer.conf), чтобы использовать зашифрованный пароль. Установите параметр ldapbindpasswd в значение "$bindpasswd":

# connection-type  database  user   address           auth-method  auth-options
host               postgres  alice  192.168.1.155/32  ldap         ldapserver=ipa.example.com ldapbasedn="cn=users,cn=accounts,dc=example,dc=com" ldapbinddn="uid=admin,cn=users,cn=accounts,dc=example,dc=com" ldapbindpasswd="$bindpasswd"

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

Настройка SSL-шифрования

PgBouncer поддерживает SSL-шифрование как для подключений клиент-PgBouncer, так и для подключений PgBouncer-СУБД, обеспечивая безопасную передачу учетных данных и запросов.

Включение SSL в СУБД

Перед настройкой SSL для PgBouncer включите SSL в СУБД Greengage, как описано в статье Шифрование соединений с базой данных.

Затем отредактируйте файл pg_hba.conf, чтобы разрешить SSL-подключения от PgBouncer:

# connection-type  database  user   address         auth-method
hostssl            postgres  all    192.168.1.5/32  trust

Перезапустите кластер, чтобы применить изменения.

Шифрование подключений PgBouncer ↔ СУБД

Сгенерируйте серверный сертификат для хоста PgBouncer, как описано в разделе Создание сертификатов, используя тот же корневой центр сертификации (CA).

Отредактируйте pgbouncer.ini, чтобы настроить SSL для подключений к серверу:

# ...
server_tls_sslmode = verify-full
server_tls_ca_file = certs/root.crt
server_tls_cert_file = certs/server.crt
server_tls_key_file = certs/server.key
# ...

Перезагрузите конфигурацию PgBouncer, как описано в разделе Перезагрузка конфигурации PgBouncer.

Подключитесь как alice с клиентского хоста:

$ psql postgres -U alice -h 192.168.1.5 -p 6432

На хосте PgBouncer проверьте подключения к серверу:

\x
SHOW SERVERS;

Проверьте значение поля tls в выводе:

-[ RECORD 1 ]-------+-----------------------------------------------
type                | S
user                | alice
database            | postgres
state               | active
addr                | 192.168.1.10
port                | 5432
local_addr          | 192.168.1.5
local_port          | 40084
connect_time        | 2026-03-03 07:49:09 UTC
request_time        | 2026-03-03 07:49:14 UTC
wait                | 0
wait_us             | 0
close_needed        | 0
ptr                 | 0x561630bc5830
link                | 0x561630bb0930
remote_pid          | 17464
tls                 | TLSv1.3/TLS_AES_256_GCM_SHA384/ECDH=prime256v1
application_name    | psql
prepared_statements | 0

Шифрование подключений клиент ↔ PgBouncer

Отредактируйте файл pgbouncer.ini, чтобы включить SSL для клиентских подключений:

# ...
client_tls_sslmode = require
client_tls_ca_file = certs/root.crt
client_tls_cert_file = certs/server.crt
client_tls_key_file = certs/server.key
# ...

Перезагрузите конфигурацию PgBouncer, как описано в разделе Перезагрузка конфигурации PgBouncer.

Подключитесь как пользователь alice с клиентского хоста:

$ psql postgres -U alice -h 192.168.1.5 -p 6432

Убедитесь, что используется SSL:

psql (9.4.26)
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
Type "help" for help.

postgres=>
Предыдущая
Логирование
Следующая
Запуск и остановка