bihactl

bihactl — создать BiHA-кластер в Postgres Pro

Синтаксис

bihactl add --biha-node-id=id_узла --host=адрес_узла [параметры]

bihactl init --biha-node-id=id_узла --nquorum=значение_кворума --host=адрес_узла [параметры]

bihactl status [параметры]

bihactl -V | --version

bihactl -? | --help

Описание

bihactl — это утилита командной строки, которая позволяет создать BiHA-кластер, изменять его состав, а также отслеживать статус и версию кластера. За подробной информацией о решении BiHA обратитесь к главе Встроенная отказоустойчивость (BiHA).

В этом разделе содержится информация о командах утилиты bihactl:

Узел-последователь можно добавить с использованием «‎‎магической» строки, сохранённой после выполнения команды bihactl init, передав в команде bihactl add параметр -s.

Важно

Не рекомендуется выполнять команды bihactl в каталоге PGDATA. Утилита bihactl может создавать файлы biha_init.log и biha_add.log в том каталоге, откуда запускается. Однако для корректного выполнения команд bihactl целевой каталог PGDATA должен быть пустым.

Справка по командной строке #

add #

Синтаксис:

bihactl add --biha-node-id=id_узла
            --host=адрес_узла
            {--use-leader=параметры_подключения | --magic-string=магическая_строка | --magic-file=файл_с_магической_строкой}
            [--convert-standby]
            [--pgdata=каталог_данных]
            [--port=порт]
            [--biha-port=порт_biha]
            [--backup-method=метод_резервирования]
            [--backup-options=параметры_резервирования]
            [--mode=режим_узла] [--referee-with-postgres-db]]

Добавляет последователя в инициализированный кластер. При выполнении этой команды создаётся резервная копия лидера с помощью pg_basebackup или pg_probackup. При добавлении узла утилита bihactl удерживает слот репликации, вызывая pg_probackup с параметрами --slot=ИМЯ_СЛОТА, --wal-method=stream, --checkpoint=fast или pg_probackup с параметрами --stream --slot=ИМЯ_СЛОТА, что предотвращает удаление WAL на лидере во время создания резервной копии.

Примечание

Узлы необходимо добавлять по очереди. Не добавляйте новый узел, если создание ранее добавленного узла ещё не завершено и узел находится в состоянии CSTATE_FORMING. В противном случае может возникнуть следующая ошибка:

            WARNING:  aborting backup due to backend exiting before pg_backup_stop was
            called
        

Для выбора утилиты резервного копирования используется параметр -m, а параметры выбранной утилиты можно задать при помощи параметра -O.

Эта команда может принимать следующие параметры:

-c
--convert-standby #

Преобразовывает существующий узел в узел-последователь отказоустойчивого кластера. Узел должен быть репликой узла-лидера до преобразования.

-D каталог_данных
--pgdata=каталог_данных #

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

-f файл_с_магической_строкой
--magic-file=файл_с_магической_строкой #

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

-h адрес_узла
--host=адрес_узла #

Указывает адрес узла для входящих соединений.

-I id_узла
--biha-node-id=id_узла #

Указывает уникальный идентификатор узла.

-l параметры_подключения
--use-leader=параметры_подключения #

Указывает параметры подключения к узлу-лидеру в следующем формате:

host=адрес_узла_лидера port=порт_лидера biha-port=порт_biha_лидера
-m метод_резервирования
--backup-method=метод_резервирования #

Указывает утилиту резервного копирования. Допускаются значения pg_basebackup и pg_probackup. Значение по умолчанию — pg_basebackup. Если не указывать параметр --backup-method, будет использован метод резервного копирования по умолчанию. Утилита pg_basebackup — единственное допустимое значение при добавлении узла-рефери.

-O параметры_резервирования
--backup-options=параметры_резервирования #

Дополнительно указывает параметры pg_basebackup или pg_probackup в зависимости от утилиты резервного копирования, заданной в параметре --backup-method.

-p порт
--port=порт #

Указывает порт узла для входящих соединений.

Если не указан:

  • При преобразовании существующего кластера с помощью --convert-standby bihactl использует значение переменной окружения PGPORT.

  • При создании BiHA-кластера с нуля bihactl использует значение по умолчанию — 5432.

-P порт_biha
--biha-port=порт_biha #

Указывает порт для обмена служебной информацией между узлами. Если порт не указан, устанавливается значение port + 1.

-r режим_работы_узла
--mode=режим_работы_узла #

Указывает режим работы узла. Допустимы следующие значения:

  • regular — узел может быть как лидером, так и последователем. Это значение по умолчанию.

  • referee — узел только участвует в выборах лидера и не содержит пользовательских баз данных.

  • referee_with_wal — узел участвует в выборах лидера так же, как в режиме referee, и получает все файлы WAL от узла-лидера.

По умолчанию база данных postgres не копируется на узел в режиме referee или referee_with_wal. Чтобы скопировать базу данных postgres на рефери, воспользуйтесь параметром --referee-with-postgres-db.

-R
--referee-with-postgres-db #

Копирует базу данных postgres со всеми объектами на узел-рефери. Этот параметр можно использовать только при добавлении узла в режиме referee или referee_with_wal.

-s магическая_строка
--magic-string=магическая_строка #

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

init #

Синтаксис:

bihactl init --biha-node-id=id_узла
             --nquorum=значение_кворума
             --host=адрес_узла
             [--convert [--root-cert=/путь/к/сертификату_цс --server-cert=/путь/к/сертификату_сервера \
             --server-key=/путь/к/ключу_сервера --user-postgres-cert=/путь/к/сертификату_клиента \
             --user-postgres-key=/путь/к/ключу_клиента [--postgres-ssl-mode=режим_ssl]]]
             [--pgdata=каталог_данных]
             [--port=порт]
             [--biha-port=порт_biha]
             [--use-ssl]
             [--minnodes=минимальное_число_узлов]
             [--magic-file=файл_с_магической_строкой]
             [--options=параметры_initdb]
             [--sync-standbys=число_синхронных_резервных_узлов [--sync-standbys-min=минимальное_число_синхронных_резервных_узлов]]
             [--root-cert=/путь/к/сертификату_цс --user-biha-cert=/путь/к/сертификату_клиента \
             --user-biha-key=/путь/к/ключу_клиента [--biha-ssl-mode=режим_ssl]]

Инициализирует кластер и задаёт узел-лидер. При выполнении этой команды bihactl запускает утилиту initdb. На этом этапе также можно указать необходимые параметры этой утилиты при помощи флага -o.

Эта команда может принимать следующие параметры:

-C
--convert #

Преобразовывает существующий узел в узел-лидер отказоустойчивого кластера.

-D каталог_данных
--pgdata=каталог_данных #

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

-f файл_с_магической_строкой
--magic-file=файл_с_магической_строкой #

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

-h адрес_узла
--host=адрес_узла #

Указывает адрес узла для входящих соединений.

-I id_узла
--biha-node-id=id_узла #

Указывает уникальный идентификатор узла.

-M мин_число_узлов
--minnodes=мин_число_узлов #

Указывает минимальное число работающих узлов, при котором узел-лидер будет доступен для пишущих транзакций. Если параметр не задан, его значение будет равно значению параметра nquorum.

-N значение_кворума
--nquorum=значение_кворума #

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

Устанавливая это значение, принимайте во внимания возможный риск разделения кластера. Рекомендуется использовать следующую формулу: (общее_число_узлов + 1)/2. Например, если в кластере 3 узла, значение nquorum должно быть 2.

-o параметры_initdb
--options=параметры_initdb #

Дополнительно указывает параметры утилиты initdb.

-p порт
--port=порт #

Указывает порт узла для входящих соединений.

Если не указан:

  • При преобразовании существующего кластера с помощью --convert bihactl использует значение переменной окружения PGPORT.

  • При создании BiHA-кластера с нуля bihactl использует значение по умолчанию — 5432.

-P порт_biha
--biha-port=порт_biha #

Указывает порт для обмена служебной информацией между узлами. Если порт не указан, устанавливается значение port + 1.

-S
--use-ssl #

Включает защищённый режим передачи служебной информации между узлами кластера по протоколу SSL/TLS управляющего канала biha.

-Y число_синхронных_ведомых_серверов
--sync-standbys=число_синхронных_ведомых_серверов #

Включает кворумную синхронную репликацию, устанавливая параметр synchronous_standby_names и указывая число синхронных резервных узлов (кворум) с методом ANY. Рекомендуется указывать значение число_синхронных_резервных_узлов меньше, чем значение параметра --minnodes.

-y мин_число_синхронных_ведомых_серверов
--sync-standbys-min=мин_число_синхронных_ведомых_серверов #

Включает нестрогую кворумную синхронную репликацию, указывая значение поля MIN параметра synchronous_standby_names, что задаёт минимальное число синхронных резервных узлов, которые должны быть доступны, чтобы лидер продолжал работать. Значение минимальное_число_синхронных_резервных_узлов должно быть меньше, чем --sync-standbys, и не может быть отрицательным. Если параметр не задан, BiHA-кластер будет работать в соответствии с ограничениями синхронной репликации по умолчанию, т.е. лидер будет недоступен для пишущих транзакций, пока все последователи не нагонят его текущее состояние.

--biha-ssl-mode=режим_ssl #

Определяет политику аутентификации по SSL для роли biha_replication_user. Поддерживаются следующие режимы:

  • verify-full (по умолчанию)

  • require

  • verify-ca

За подробной информацией о режимах обратитесь к sslmode.

--postgres-ssl-mode=режим_ssl #

Определяет политику аутентификации по SSL для суперпользователя. Поддерживаются следующие режимы:

  • verify-full (по умолчанию)

  • require

  • verify-ca

За подробной информацией о режимах обратитесь к sslmode.

--root-cert=/путь/к/сертификату_цс #

Указывает путь к сертификату доверенного ЦС в формате PEM.

--server-cert=/путь/к/сертификату_сервера #

Указывает путь к SSL-сертификату для узла BiHA в формате PEM.

--server-key=/путь/к/ключу_сервера #

Указывает путь к закрытому ключу сертификата --server-cert в формате PEM.

--user-biha-cert=/путь/к/сертификату_клиента #

Указывает путь к SSL-сертификату для аутентификации роли biha_replication_user в формате PEM.

--user-biha-key=/путь/к/ключу_клиента #

Указывает путь к закрытому ключу для сертификата --user-biha-cert в формате PEM.

--user-postgres-cert=/путь/к/сертификату_клиента #

Указывает путь к SSL-сертификату для аутентификации суперпользователя в формате PEM.

--user-postgres-key=/путь/к/ключу_клиента #

Указывает путь к закрытому ключу сертификата --user-postgres-cert в формате PEM.

status #

Синтаксис:

bihactl status {--host=адрес_узла [--port=порт] | --magic-string=магическая_строка | --magic-file=файл_с_магической_строкой}

Проверяет статус узла и отображает его в представлении biha.status_v. Эта команда может принимать следующие параметры:

-f файл_с_магической_строкой
--magic-file=файл_с_магической_строкой

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

-h адрес_узла
--host=адрес_узла

Указывает адрес узла для входящих соединений.

-p порт
--port=порт

Указывает порт узла для входящих соединений. Если параметр не задан, bihactl будет использовать значение PGPORT. Значение по умолчанию — 5432.

-s магическая_строка
--magic-string=магическая_строка

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

-V | --version #

Синтаксис:

bihactl -V
bihactl --version

Выводит текущую версию отказоустойчивого кластера.

-? | --help #

Синтаксис:

bihactl -?
bihactl --help

Выводит справку по параметрам командной строки.