
### PgBouncer "K"
###
### Copyright (C) ООО Кейсистемс 2025
###
### Версия 1.25.1


  Описание           : PgBouncer "K" - платформа для развертывания пуллера соединений pgbouncer,
                       реализованного в виде контейнера для работы в средах с поддержкой контейнеризации
                       Docker или Podman.

  Цель использования : Минимизировать издержки, связанные с разворачиванием и настройкой.

  Требует для работы : Docker-CE (Docker, Inc. лицензия Apache 2.0) или Podman (лицензия Apache 2.0), платформа linux/amd64.

  Характеристики     : Позволяет устанавливать до 10 экземляров контейнеров c пуллером pgbouncer,
                       внутри которого (контейнера) возможен запуск до 16 экземпляров пуллера,
                       использующих один порт. Используемый диапазон портов: 5432-6442.

                       В поставляемом образе контейнера используются компоненты:
                        - pgbouncer 1.25.1 (лицензия ISC)
                        - psql 15.13       (лицензия PostgreSQL)

                       Для более подробного ознакомления с лицензированием Docker-CE, Podman, pgbouncer, psql
                       и информации об авторских правах смотрите соответствующие сайты программ:
                       https://www.docker.com/
                       https://podman.io/
                       https://www.pgbouncer.org/
                       https://www.postgresql.org/



I. Создание пользователя пуллера и функции аутентификации в базе данных сервера СУБД.

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

  1) Используя программу "Центр обновления баз данных".
     Для этого:
     - подключиться к серверу СУБД;
     - выбрать базу данных и нажать кнопку "Дополнения";
     - выбрать пункт "Модули пуллера - PgBouncer,*(0991)" и запустить установку;

     В результате выполнения будет создан пользователь с именем - pgbouncer c паролем, который сгенерирует система.
     Пароль нужно будет запомнить, чтобы указать его при разворачивании пуллера.


  2) Выполнением измененного "под себя" sql скрипта /opt/dks-pgbouncer-1.25.1/pgb_files/sql/auth_query.sql
     в базе данных сервера СУБД. Под изменениями "под себя" подразумевается возможность указания своего имени пользователя
     (вместо пользователя по умолчанию - pgbouncer) и указанием своего пароля.



II. Основные команды создания, удаления и изменения настроек экземпляра контейнера с пуллером.

  Внимание! Для выполнения операций необходимы права суперпользователя.

 1) Создание экземпляра контейнера с пуллером.

    Например, необходимо создать экземпляр контейнера с пуллером с портом 6434.
    Считаем, что пользователь пуллера (pgbouncer с паролем '~!@#$%^&*()_+') и функция уже созданы в базе данных сервера СУБД.

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

    $ /opt/dks-pgbouncer-1.25.1/install.sh -h "10.38.46.57" -p "5434" -U "pgbouncer" -pwd '~!@#$%^&*()_+' -bp "6434"
     где,
       - "10.38.46.57"                    # ip адрес сервера СУБД
       - "5434"                           # номер порта сервера СУБД
       - "pgbouncer"                      # пользователь пуллера на сервере СУБД
       - '~!@#$%^&*()_+'                  # пароль пользователя на сервере СУБД
       - "6434"                           # номер порта пуллера

     Для работы в составе отказоустойчивого кластера (ОУК) необходимо дополнительно
     указать ключ -ssh, для включении поддержки ssh сервера в контейнере.

     Важно! Настоятельно рекомендуется значание параметра пароля (-pwd) заключать в одинарные кавычки.
            Это позволит использовать в пароле спецсимволы.


    В результате, при успешном выполнении будет выведено примерно такое сообщение:

    === Лог выполнения ============================================================================================================================================

               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
               ~   Установка пуллера PgBouncer 1.25.1 (docker)
               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    [   OK   ] Проверка доступности порта 6434  ПО "пуллер pgBouncer".
    [   OK   ] Проверка работы сервиса ПО "Docker" (docker.service).
    [   OK   ] Удаление контейнера pgbouncer-1.25.1.
    [   OK   ] Удаление образа pgbouncer-1.25.1.
    [   OK   ] Загрузка эталонного локального образа pgbouncer-1.25.1 из архива ksdeb12_pgbouncer-1.25.1_image.tar.
    [   OK   ] Построение конечного образа pgbouncer-1.25.1_6434 на базе эталонного.
               Структура каталогов /opt/pgbouncer-1.25.1_6434 для запуска контейнера pgbouncer-1.25.1_6434 не существует, создаем...
    [   OK   ] Создание структуры каталогов для запуска контейнера pgbouncer-1.25.1_6434.
    [   OK   ] Проверка\Создание пользователя postgres.
               useradd: пользователь «postgres» уже существует
    [   OK   ] Создание контейнера pgbouncer-1.25.1_6434 и запуск в docker (идентификатор 6434).
    [   OK   ] Запуск сервиса pgbouncer-1.25.1_6434.service.

    ===============================================================================================================================================================

 2) Просмотр информации запущенных процессов пуллера.
    Для просмотра запущенных процессов необходимо запустить команду в каталоге развернутого приложения:
    $ /opt/pgbouncer-1.25.1_6434/ctl/info.sh


 3) Изменение параметров для развернутого приложения:

   a) Изменение количества одновременно запущенных процессов pgbouncer (после разворачивания значение по умолчанию равно 1), например:

    $ /opt/dks-pgbouncer-1.25.1/configure.sh -pb "6434" -m "count" -rc "8"
     где,
          "6434"      - порт по которому развернут пуллер
          "count"     - параметр режима (что меняем)
          "8"         - количество запускаемых процессов, диапазон значений от 1 до 16.

   б) Изменение адреса и порта сервера СУБД, например:

    $ /opt/dks-pgbouncer-1.25.1/sh/configure.sh -pb "6434" -m "database" -h "192.168.1.200" -p "5434" -u "pgbouncer"
     где,
          "6434"           - порт по которому развернут пуллер
          "database"       - параметр режима (что меняем)
          "192.168.1.101"  - ip адрес сервера СУБД
          "5434"           - порт сервера СУБД
          "pgbouncer"      - имя пользователя


   d) Изменение пользователя и его пароля для запроса аутентификации, например:

    $ /opt/dks-pgbouncer-1.25.1/sh/configure.sh -pb "6434" -m "user" -u "pgbouncer" -pwd '12345'
     где,
          "6434"      - порт, по которому развернут пуллер
          "user"      - параметр режима (что меняем)
          "pgbouncer" - имя пользователя
          '12345'     - пароль пользователя


   ВАЖНО!!! Для вступления изменений в силу необходимо выполнить перезагрузку пуллера,
            через перезагрузку сервиса в системе systemd.


 4) Удаление экземпляра контейнера

    Например, необходимо удалить экземпляр контейнера с пуллером, развернутым по порту 6434.
    Для этого в командной строке выполняем следующую команду:

    $ /opt/dks-pgbouncer-1.25.1/uninstall.sh -bp 6434

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

    $ /opt/dks-pgbouncer-1.25.1/uninstall.sh -bp 6434 -all

