26.3. Администрирование #
- 26.3.1. Изменение состава кластера
- 26.3.2. Управление параметрами конфигурации
- 26.3.3. Ручное переключение узлов
- 26.3.4. Управление SSL для служебных подключений
- 26.3.5. Роли
- 26.3.6. Использование сервисного режима
- 26.3.7. Автоматическая синхронизация кластера после аварийного переключения
- 26.3.8. Восстановление узла из состояния
NODE_ERROR- 26.3.9. Механизм защиты от зависания
- 26.3.10. Настройка репликации
- 26.3.11. Протоколирование
- 26.3.12. Функции-обработчики
- 26.3.13. Восстановление из резервной копии
- 26.3.14. Выполнение пользовательских скриптов с помощью команды
bihactl run- 26.3.15. Обновление и миграция
- 26.3.16. Выключение расширения biha
- 26.3.17. Удаление расширения biha
- 26.3.2. Управление параметрами конфигурации
26.3.1. Изменение состава кластера #
Состав кластера можно изменить следующим образом:
Чтобы добавить узел, используйте команду bihactl node add с соответствующими параметрами.
Примечание
Процесс
walreceiverперезапускается каждый раз при добавлении узла в кластер с кворумной синхронной репликацией.Чтобы добавить сегмент, используйте функцию biha.add_node.
Чтобы удалить узел или сегмент, используйте функцию biha.remove_node.
Чтобы изменить лидера вручную, используйте функцию biha.set_leader. За подробной информацией обратитесь к разделу Ручное переключение узлов.
26.3.2. Управление параметрами конфигурации #
Управлять параметрами конфигурации кластера можно следующим образом:
Большинство параметров конфигурации BiHA хранятся в
pg_biha/biha_conf_, а задать их можно с помощью специальных функций. Все доступные параметры конфигурации перечислены в Подразделе 26.4.1, и в их описаниях указаны функции, которые ими управляют. За полным списком функций обратитесь к Подразделу 26.4.2.версия_конфигурации.jsonВсе функции необходимо вызывать из базы данных
biha_db. Если в описании функции не указано иное, функцию необходимо вызывать на лидере.Например, используйте функцию biha.set_heartbeat_max_lost, чтобы задать значение параметра heartbeat_max_lost:
biha_db=# SELECT biha.set_heartbeat_max_lost(7);
Несколько необязательных параметров конфигурации BiHA можно задать с помощью команды
ALTER SYSTEMSET. Эти параметры конфигурации перечислены в Подразделе 26.4.1.5.Например:
ALTER SYSTEM SET biha.autorewind = true;
Для просмотра текущих значений параметров конфигурации BiHA используйте функцию biha.config.
Для корректной работы BiHA устанавливает некоторые параметры конфигурации Postgres Pro. Чтобы безопасно уменьшить их значения, используйте процедуру, описанную в Подразделе 26.1.1.1.
26.3.3. Ручное переключение узлов #
Помимо встроенных возможностей автоматического аварийного переключения узлов, решение BiHA поддерживает ручное переключение как для стандартных BiHA-кластеров, так и для GDBiHA-кластеров. Значение параметра nquorum игнорируется при выполнении ручного переключения.
Переключить узлы вручную можно с помощью функции biha.set_leader или специальных команд bihactl.
Учитывайте следующие рекомендации:
Важно
Для успешной смены лидера выполните команду CHECKPOINT перед переключением вручную.
Вызывайте функцию
biha.set_leaderи выполняйте специальные команды bihactl на узле, который хотите назначить новым лидером или главным последователем. Не вызывайте функциюbiha.set_leaderна текущем лидере. Если вызвать функцию на текущем лидере в состоянииLEADER_RW, при подтверждении переключения может не хватить времени на отправку результата запроса клиенту до того, как начнётся перезагрузка текущего лидера для понижения.Не вызывайте функцию
biha.set_leaderи не выполняйте специальные команды bihactl повторно до завершения процесса переключения. Если необходимо выполнить переключение сразу после первого переключения, дождитесь, пока назначенный узел изменит своё состояние наLEADER_RO/LEADER_RWили, если повышение по какой-то причине не удалось, обратно наFOLLOWER.
При назначении нового лидера или главного последователя происходит следующее:
Состояние назначенного узла меняется на
FOLLOWER_OFFERED.Все попытки начать выборы блокируются.
Текущий лидер меняет своё состояние на
LEADER_RO. При переключении главного последователя его состояние остаётся неизменным (FRONT_FOLLOWER).FOLLOWER_OFFEREDищет наиболее актуальный источник репликации в своём сегменте и настраивает репликацию с этого источника.Когда узел в состоянии
FOLLOWER_OFFEREDобнаруживает, что в кластере отсутствует лидер в состоянииLEADER_RW, и при этом обладает наибольшим количеством данных в рамках сегмента, он становится новым лидером или главным последователем.Если процесс переключения не завершается в течение установленного параметром no_wal_on_follower тайм-аута, назначенный узел возвращается в роль последователя, а текущий лидер или главный последователь сохраняет свою роль. Однако при отсутствии лидера или главного последователя происходят автоматические выборы нового лидера или главного последователя.
26.3.3.1. Переключение с помощью функции biha.set_leader #
Переключение можно выполнить с помощью функции biha.set_leader следующим образом:
Чтобы назначить нового лидера или главного последователя, вызовите функцию
biha.set_leaderс указанием идентификатора узла, который необходимо повысить. В зависимости от сегмента, в котором расположен назначенный узел (сегмент-лидер или сегмент-последователь), узел становится либо лидером, либо главным последователем этого сегмента.Для переключения между сегментами вызовите функцию
biha.set_leaderс указанием идентификатора сегмента, который необходимо повысить до сегмента-лидера. После переключения главный последователь повышенного сегмента становится новым лидером, а бывший лидер становится главным последователем своего сегмента.
26.3.3.2. Переключение с помощью команд bihactl #
Переключение можно выполнить с помощью специальных команд bihactl. Команды необходимо выполнять на узле или сегменте, который хотите повысить.
Чтобы повысить узел до лидера, на этом узле выполните команду bihactl node set leader. Узел должен быть расположен в сегменте-лидере.
Чтобы повысить узел до главного последователя, на этом узле выполните команду bihactl node set front-follower. Узел должен располагаться в сегменте-последователе.
Чтобы повысить сегмент до лидера, на этом сегменте выполните команду bihactl segment set leader.
Чтобы повысить или сегмент, или узел до лидера, на этом сегменте или узле выполните команду bihactl unit set leader. В зависимости от указанного идентификатора команда сработает либо как bihactl segment set leader, либо как bihactl node set leader.
26.3.4. Управление SSL для служебных подключений #
Можно включать или отключать SSL для защиты служебных подключений в инициализированном BiHA-кластере, а также менять пути к публичному сертификату и закрытому ключу.
Важно
Чтобы использовать SSL для служебных подключений, установленная версия OpenSSL должна быть 1.1.1 или выше. В противном случае SSL не включится, и в журнале будет записано соответствующее сообщение.
Изменить настройки SSL можно следующим образом:
Чтобы включить SSL, на лидере для параметра use_ssl установите значение
true:biha_db=# select biha.set_use_ssl(true); set_use_ssl ---------------- t (1 row)
Чтобы отключить SSL, для параметра
use_sslустановите значениеfalse.Чтобы изменить пути к публичному сертификату и закрытому ключу, используйте параметры ssl_certificate и ssl_private_key соответственно.
По умолчанию путь к публичному сертификату —
/PGDATA/pg_biha/biha_pub_cert.pem, а к закрытому ключу —/PGDATA/pg_biha/biha_priv_key.pem.
Остановите и запустите узлы с помощью pg_ctl.
Важно
Лидер необходимо останавливать последним, а запускать первым. Так как включение SSL в BiHA-кластере подразумевает использование стандартного процесса начального согласования TLS, рекомендуется минимизировать временной промежуток между остановкой и запуском узлов кластера.
26.3.5. Роли #
При инициализации отказоустойчивого кластера создаётся база данных biha_db, также в схеме biha базы данных biha_db создаётся расширение biha. Кроме того, создаются и используются следующие роли:
BIHA_CLUSTER_MANAGEMENT_ROLE— отвечает за выполнение всех функций расширения biha.BIHA_REPLICATION_ROLE— используется при работе pg_rewind и pg_probackup.biha_replication_user— является членом ролейBIHA_REPLICATION_ROLEиBIHA_CLUSTER_MANAGEMENT_ROLEи может совершать как клиентские подключения, так и подключения по протоколу репликации. Эта роль используется утилитой bihactl, а также при подключении узла-последователя к узлу-лидеру. Является владельцем базы данныхbiha_db. Пароль для ролиbiha_replication_userв файле паролей должен быть одинаковым на всех узлах BiHA-кластера. Пароль предлагается задать во время создания BiHA-кластера.biha_callbacks_user— по умолчанию исполняет функции-обработчики. Этот пользователь может подключаться к базе данных, но не имеет никаких прав.biha_monitor_user— по умолчанию выполняет пользовательские скрипты с bihactl run. Этот пользователь может подключаться к базе данных, но не имеет никаких прав.pg_monitor— предопределённая роль, которая используется для мониторинга состояния BiHA-кластера.
26.3.6. Использование сервисного режима #
BiHA предоставляет функциональность сервисного режима, чтобы временно приостановить работу BiHA. Это может потребоваться, если вы изменили параметры конфигурации и хотите убедиться, что изменения применились на всех узлах кластера, например при уменьшении значений параметров конфигурации Postgres Pro.
Когда BiHA находится в сервисном режиме:
последователи продолжают получать WAL
выборы отменяются и ни один узел не может выставить себя кандидатом
лидера можно переключить вручную
Сервисным режимом можно управлять, вызвав функцию biha.service_mode на лидере.
С помощью функции biha.service_mode можно выполнить следующие действия:
Включить сервисный режим, установив для параметра
enableфункцииbiha.service_modeзначениеtrue:biha_db=# SELECT biha.service_mode(true);
Отключить сервисный режим, установив для параметра
enableфункцииbiha.service_modeзначениеfalse:biha_db=# SELECT biha.service_mode(false);
При отключении сервисного режима BiHA проверяет, были ли параметры, изменённые в сервисном режиме, применены на всех узлах кластера. Если найдены неприменённые параметры, сервисный режим не отключается, а функция возвращает ошибки с перечислением всех неприменённых параметров. Например:
biha _db=# SELECT biha.service_mode (false); ERROR: [BiHA] Config changes HINT: Some parameters have been changed but not applied: Node 3: max_connections To force exit service mode, use: "select * from biha.service_mode(false, true)"
При необходимости можно отключить сервисный режим, игнорируя ошибки, установив для параметра
forceфункцииbiha.service_modeзначениеtrue:biha_db=# SELECT biha.service_mode(false, true);
26.3.7. Автоматическая синхронизация кластера после аварийного переключения #
BiHA обеспечивает автоматическую синхронизацию кластера в случае расхождения линий времени узлов. Например, чтобы вернуть бывшего лидера в кластер после аварийного переключения.
Управлять автоматической синхронизацией в BiHA-кластере можно следующим образом:
Включите автоматическую синхронизацию (automatic rewind), установив для параметра конфигурации biha.autorewind значение
true. Автоматическая синхронизация выполняется, если она может успешно завершиться, то есть если предварительный запуск инструмента pg_rewind с параметром--dry-runпрошёл успешно.При неудачной автоматической синхронизации узел переходит в состояние
NODE_ERROR. В этом случае фактическое состояние синхронизации узла можно найти в файлеbiha.state, как описано в Подразделе 26.3.7.1.Важно
В результате синхронизации могут быть утеряны некоторые записи WAL узла.
Чтобы избежать запуска pg_rewind в тех случаях, когда расхождение WAL вызвано только лишними записями сообщений о контроле состояния, можно воспользоваться возможностью выравнивания WAL, которая управляется с помощью параметра конфигурации biha.autowaltrim. Когда алгоритм выравнивания WAL включён, он находит последнюю общую точку в журналах WAL отклонившегося узла и нового лидера, проверяет, что все последующие записи содержат только сообщения о контроле состояния, и автоматически удаляет эти лишние записи с отклонившегося узла, чтобы он мог продолжить репликацию. Это удобно в случае, когда произошло разделение кластера (split-brain) и бывший лидер возвращается в кластер в качестве последователя, но не может начать репликацию из-за того, что в его WAL содержатся записи сообщений о контроле состояния, сгенерированные, когда он ещё был лидером.
Если процедура выравнивания WAL завершается неудачно, состояние узла изменяется на
NODE_ERROR.Параметры выравнивания WAL можно посмотреть в файле
biha.state. За подробной информацией обратитесь к Подразделу 26.3.7.2.Важно
Если в процессе выравнивания WAL происходит отказ кластера и WAL изменяется некорректно, это может привести к потере записей WAL.
26.3.7.1. Мониторинг результатов синхронизации #
Результаты выполнения операции pg_rewind, т.е. состояние синхронизации узлов кластера, можно проверить в поле rewind_state файла biha.state. Оно содержит значения типа enum, которые интерпретируются следующим образом:
Таблица 26.1. Состояние синхронизации
| Значение | Интерпретация |
|---|---|
0 | Синхронизация не требуется. |
1 | Экземпляр СУБД остановлен, параметр конфигурации biha.autorewind включён, синхронизация будет выполнена после перезапуска экземпляра СУБД. |
2 | Синхронизация завершилась ошибкой. |
3 | Синхронизация выполнена. |
4 | Параметр конфигурации biha.autorewind не был включён, синхронизацию необходимо выполнить вручную, как описано в Восстановление узла из состояния NODE_ERROR. |
26.3.7.2. Мониторинг параметров выравнивания WAL #
Параметры выравнивания WAL узлов кластера можно проверить в следующих полях файла biha.state:
waltrim_state: текущее состояние выполнения процедуры выравнивания WALwaltrim_common_tli: линия времени последней общей точкиwaltrim_start_lsn: начало диапазона рассинхронизации WAL, вызванной лишними сообщениями о контроле состоянияwaltrim_end_lsn: конец диапазона рассинхронизации WAL, вызванной лишними сообщениями о контроле состояния
26.3.8. Восстановление узла из состояния NODE_ERROR #
Описанные ниже ошибки, возникающие в процессах biha или экземпляра Postgres Pro Standard, могут привести к отказу узла, то есть он не сможет перезагрузиться и WAL будет повреждён:
Синхронизация, автоматически выполняемая расширением biha с использованием pg_rewind при расхождении линий времени узла.
Процесс walreceiver в случае расхождения линий времени. WAL узла-последователя может быть частично перезаписан WAL, полученным от узла-лидера.
Примечание
Если узел перешел в состояние NODE_ERROR из-за других проблем, например, по причине переполнения слота репликации, после устранения первопричины можно вызвать функцию biha.reset_node_error для сброса состояния NODE_ERROR.
Когда узел переходит в состояние NODE_ERROR, восстановление WAL приостанавливается и процесс walreceiver завершается. Узлы в состоянии NODE_ERROR не могут голосовать на выборах. Чтение с таких узлов запрещено. Кроме того, сведения об ошибке сохраняются в файле biha.state и проверяются при перезапуске узла, поэтому узел перейдёт в то же состояние при запуске процесса biha-background-worker.
Чтобы восстановить узел из состояния NODE_ERROR, выполните следующие шаги:
Сохраните последние файлы из каталога
pg_wal, так как некоторые уникальные для этого узла файлы будут перезаписаны утилитой pg_rewind.Чтобы сохранить файлы конфигурации biha, запустите pg_rewind с параметром
--biha, например:pg_rewind --biha --target-pgdata=
путь_к_каталогу_PGDATA_узла_в_NODE_ERROR--source-server='user=biha_replication_user host=адрес_лидераport=порт_лидераdbname=postgres'Важно
Параметр
--bihaнеобходим для сохранения файлов конфигурации расширения biha. Использование pg_rewind в BiHA-кластере без указания параметра--bihaможет вызвать несогласованность конфигурации кластера.При успешной синхронизации информация о состоянии
NODE_ERRORудаляется из файлаbiha.state. Кроме того, строка подключения, указанная в параметре--source-serverутилиты pg_rewind, автоматически сохраняется для параметра конфигурации primary_conninfo в файле postgresql.auto.conf. Это важно для того, чтобы узел продолжил восстанавливаться после перезапуска и достиг точки согласованности, которая представляет собой номер последней записи WAL исходного сервера на момент синхронизации.(Необязательно) Если узел был недоступен долгое время, на восстановленном узле установите для параметра flw_ro значение
off, чтобы предотвратить повреждение данных и чтение неактуальных данных.
26.3.9. Механизм защиты от зависания #
BiHA предоставляет специальный защитный механизм, который помогает предотвратить зависание узлов и проблему разделения кластера (split-brain). Механизм работает следующим образом:
Если процесс biha не отвечает, когда достигнуто значение watchdog_timeout, узел прекращает принимать запросы и его состояние временно изменяется на
NODE_ERROR.Примечание
Запросы от ролей
pg_monitorи$BIHA_USERне блокируются.Следующее сообщение в журнале информирует о проблеме: «The request cannot be processed because the BiHA extension is not responding» (Невозможно обработать запрос, так как расширение BiHA не отвечает).
В зависимости от того, как быстро восстановится процесс biha, происходит следующее:
Если процесс biha восстановится быстро, узел возвращается к нормальной работе, т.е. продолжает принимать запросы и меняет своё состояние на изначальное.
Если процесс biha не восстанавливается в течение значения
watchdog_timeout * 5, во время следующего запроса выполняется попытка отправить сигнал SIGKILL процессу biha. Все обслуживающие процессы перезапускаются, и функциональность узла восстанавливается.
Важно
Если лидер зависает, а другие узлы избирают нового лидера, необходимо восстановить бывшего лидера из состояния NODE_ERROR.
26.3.10. Настройка репликации #
По умолчанию BiHA-кластеры асинхронны. Однако BiHA позволяет создать кластер с кворумной синхронной репликацией.
Кворумная синхронная репликация включается с помощью параметра synchronous_standby_names, где задаётся список имён синхронных резервных узлов и количество синхронных узлов (кворум), ответа от которых должны ожидать транзакции, с методом ANY. За подробной информацией обратитесь к разделу Несколько синхронных резервных серверов. Параметр synchronous_commit используется со значением по умолчанию on.
За подробной информацией обратитесь к следующим разделам:
26.3.10.1. Синхронная репликация и рефери #
Есть несколько особенностей, которые необходимо учитывать при использовании синхронной репликации и узла-рефери. Если для параметра --mode установлено значение referee, рефери не участвует в синхронной репликации. Если установлено значение referee_with_wal, узел может синхронно получать данные. Этот режим позволяет кластеру оставаться доступным в конфигурации 2+1 с --sync-standbys=1, когда узел-последователь вышел из строя и узел-рефери начинает подтверждать транзакции для лидера. Поведение рефери зависит от значения параметра synchronous_commit. Обратите внимание, что если для этого параметра установлено значение remote_apply, рефери не подтверждает транзакции.
26.3.10.2. Включение кворумной синхронной репликации #
Включить кворумную синхронную репликацию можно как при инициализации BiHA-кластера, так и позднее в уже существующем BiHA-кластере.
Важно
Включение кворумной синхронной репликации в BiHA-кластере необратимо. После включения кворумной синхронной репликации сделать BiHA-кластер вновь асинхронным невозможно. Однако можно исключить определённые узлы из списка синхронных резервных узлов с помощью функции biha.remove_from_ssn. Исключённый узел будет работать асинхронно.
Включить кворумную синхронную репликацию можно следующим образом:
При создании BiHA-кластера с нуля или преобразовании существующего кластера включите кворумную синхронную репликацию с помощью параметра --sync-standbys команды bihactl cluster init.
Например, если для кластера из трёх узлов в качестве значения параметра --sync-standbys указать
1, synchronous_standby_names будет выглядеть следующим образом:ANY 1 (biha_node_1,biha_node_2,biha_node_3)
Чтобы включить кворумную синхронную репликацию в существующем BiHA-кластере, используйте функцию biha.set_sync_standbys.
26.3.10.3. Управление репликацией #
Важно
Чтобы настроить синхронную репликацию в сегменте, убедитесь, что в параметре synchronous_standby_names перечислены только физические узлы.
Управлять репликацией в BiHA-кластере можно следующим образом:
Для просмотра текущего значения параметра synchronous_standby_names используйте функцию biha.get_ssn.
Чтобы изменить кворум синхронных резервных узлов, т.е. значение, заданное для метода
ANYв параметре synchronous_standby_names, используйте функцию biha.set_sync_standbys. Как правило, это требуется сделать после того, как вы изменили состав BiHA-кластера, добавив узлы с помощью команды bihactl node add или удалив узлы с помощью функции biha.remove_node.Чтобы добавить определённый узел в список синхронных резервных узлов, используйте функцию biha.add_to_ssn.
Чтобы добавить несколько узлов в качестве списка синхронных резервных узлов, используйте функцию biha.set_ssn.
Чтобы исключить определённый узел из списка синхронных резервных узлов, используйте функцию biha.remove_from_ssn. Исключённый узел будет работать асинхронно.
26.3.10.4. Смягчение ограничений кворумной синхронной репликации #
Ограничения кворумной синхронной репликации можно смягчить, чтобы лидер мог продолжать работу, пока часть синхронных резервных узлов временно недоступна. Чтобы включить нестрогую кворумную синхронную репликацию, укажите значение в поле MIN параметра synchronous_standby_names, задающее минимальное количество синхронных резервных узлов, которые должны быть доступны, чтобы лидер продолжил работу. Параметр synchronous_standby_gap остаётся неизменным и сохраняет своё значение по умолчанию, равное 0.
Управлять нестрогой кворумной синхронной репликацией в BiHA-кластере с кворумной синхронной репликацией можно следующим образом:
Чтобы включить нестрогую кворумную синхронную репликацию при инициализации кластера с помощью команды bihactl cluster init, укажите параметр --sync-standbys-min.
Например, если для кластера из трёх узлов в качестве значения параметра--sync-standbys-min указать
0, synchronous_standby_names будет выглядеть следующим образом:ANY 1 MIN 0 (biha_node_1,biha_node_2,biha_node_3)
Чтобы включить нестрогую кворумную синхронную репликацию в существующем кластере или изменить минимальное число кворумных синхронных резервных узлов, используйте функцию biha.set_sync_standbys_min.
Чтобы отключить нестрогую кворумную синхронную репликацию, с помощью функции biha.set_sync_standbys_min установите значение
-1в качестве минимального числа синхронных резервных узлов.
26.3.10.5. Настройка каскадной репликации #
Каскадную репликацию можно настроить при инициализации кластера BiHA или GDBiHA с нуля с помощью утилиты bihactl. Затем можно изменить параметры каскадной репликации следующим образом:
Чтобы ограничить максимальное число подключений репликации к определённому узлу с других узлов в кластере BiHA или GDBiHA, укажите значение параметра конфигурации max_replicas с помощью функции biha.set_max_replicas.
Например, в трёхузловом кластере, состоящем из двух последователей (
F1иF2) и лидера, для параметраmax_replicasлидера укажите значение1. В этом случае, если последовательF1первым начнёт репликацию, он будет реплицировать данные с лидера. ПоследовательF2установит каскадную репликацию с последователяF1(при условии, что значение параметра repl_pref_roles последователяF2содержитF), так как лимит подключений лидера исчерпан.Чтобы установить приоритетность узла при выборе источника репликации, укажите значение параметра конфигурации priority с помощью функции biha.set_priority.
Например, в трёхузловом кластере, состоящем из двух последователей (
F1иF2) и лидера, установите для параметраpriorityпоследователяF1значение10секунд, а для последователяF2—20секунд. Если оба последователя одновременно начнут поиск источника репликации, последовательF1первым подключится к лидеру.Чтобы установить предпочтительные роли узла для репликации, укажите значение параметра конфигурации repl_pref_roles с помощью функции biha.set_pref_roles.
Например, если для параметра
repl_pref_rolesпоследователяF1установлено значениеFL, этот последователь сначала выберет в качестве источника репликации другого последователя. Если попытка подключения окажется неуспешной, последовательF1подключится к лидеру.Примечание
Параметр конфигурации no_wal_on_follower влияет на репликацию в каскадном BiHA-кластере. Если узел не получает WAL в течение времени, заданного в
no_wal_on_follower, он начинает искать новый источник репликации в соответствии с конфигурацией repl_pref_roles.Чтобы запретить узлу реплицировать с определённых узлов, настройте перечень запрещённых источников репликации в параметре deny_wal_sources с помощью функции biha.set_deny_wal_sources. Эту функциональность можно использовать, чтобы запретить репликацию с узлов, размещённых в определённых ЦОДах, или настроить источники репликации в каскадном кластере. Каждый узел может иметь свой собственный перечень запрещённых источников репликации.
26.3.11. Протоколирование #
BiHA записывает в журнал сообщения от своих компонентов:
Управляющий канал BiHA: управляющий канал используется для обмена служебной информацией между узлами. Управляющий канал управляется
BiHA Control Protocolи отмечен в журнале какBCP.Node Controller: основной компонент расширения biha, ответственный за логику работы узла, в журнале отмечен какNC.Postgres Controller: компонент biha, необходимый для управления и мониторинга компонентов Postgres Pro, таких как настройка репликации, параметры конфигурации, процессыwalsenderиwalreceiverи т.д.Postgres Controllerдоводит Postgres Pro до состояния, необходимого для работы BiHA. В журналеPostgres Controllerпомечен какPGC.Config Controller: конфигурационный модуль, который управляет конфигурацией узла (параметры GUC иbiha.conf) и синхронизирует её на узлах кластера. В журналеConfig Controllerпомечен какBC.
Можно определить типы сообщений, которые будут вноситься в журнал, установив соответствующий уровень протоколирования. BiHA поддерживает как стандартные уровни важности сообщений Postgres Pro, так и уровни протоколирования самого расширения.
Уровни важности сообщений Postgres Pro используются расширением biha в следующих случаях:
Когда один из процессов biha завершается ошибкой (уровни
ERRORиFATAL).Когда вызывается функция ядра, которая принимает уровень протоколирования в качестве своего аргумента.
Уровни протоколирования biha соответствуют уровням важности сообщений Postgres Pro. Если в журнале должны появляться сообщения необходимого уровня, установленное для этого уровня значение должно соответствовать значению в log_min_messages. Уровни протоколирования расширения можно настроить, указав соответствующие параметры конфигурации в файле postgresql.biha.conf.
Рекомендуемая конфигурация уровней протоколирования выглядит следующим образом:
biha.BcpTransportWarn_log_level = WARNING biha.BcpTransportLog_log_level = LOG biha.BcpTransportDetails_log_level = DEBUG1 biha.BcpTransportDebug_log_level = DEBUG1 biha.NodeControllerLog_log_level = LOG biha.NodeControllerWarn_log_level = WARNING biha.NodeControllerDetails_log_level = DEBUG1 biha.NodeControllerDebug_log_level = DEBUG1
Примечание
Такая конфигурация отображает сообщения только для уровней протоколирования biha.BcpTransportLog_log_level, biha.BcpTransportWarn_log_level, biha.NodeControllerLog_log_level и biha.NodeControllerWarn_log_level. Чтобы просматривать подробные и отладочные сообщения журнала, для параметра log_min_messages задайте значение DEBUG1.
26.3.12. Функции-обработчики #
Обработчик — это SQL-функция, которая уведомляет пользователей или внешние сервисы о событиях в BiHA-кластере, например о выборах нового лидера или изменении конфигурации кластера. Как пользователь, вы создаёте SQL-функцию и регистрируете её в качестве обработчика. При определённых условиях biha вызовет эту функцию.
Своевременное оповещение помогает внешним службам правильно реагировать на события в BiHA-кластере. Например, при получении информации об изменении лидера прокси-сервер перенаправит трафик на нового лидера.
Доступны следующие типы обработчиков:
Таблица 26.2. Типы обработчиков
| Имя | Описание |
|---|---|
CANDIDATE_TO_LEADER | Вызывается на узле, выбранном в качестве нового лидера. Сигнатура: my_callback() RETURNS void |
LEADER_CHANGE_STARTED | Вызывается на всех узлах, когда старый лидер недоступен, а новый лидер ещё не избран. Эту функцию-обработчик можно использовать, чтобы изолировать старого лидера. Функция-обработчик активируется, когда число узлов достигает значения nquorum и становится возможным провести выборы. Функция-обработчик также вызывается на всех узлах кластера, когда новый лидер устанавливается вручную с помощью функции biha.set_leader. ВажноКогда вы устанавливаете нового лидера с помощью функции biha.set_leader, старый лидер немедленно перезапускается, и функция-обработчик Сигнатура: my_callback(id integer, host text, port integer) RETURNS void В этой сигнатуре biha передаёт информацию о потерянном лидере: идентификатор, имя хоста и номер порта узла. |
LEADER_CHANGED | Вызывается на каждом узле при смене лидера BiHA-кластера. Сигнатура: my_callback(id integer, host text, port integer) RETURNS void В этой сигнатуре biha передаёт информацию о новом лидере: идентификатор, имя хоста и номер порта узла. |
LEADER_STATE_IS_RW | Вызывается на лидере и других узлах, когда состояние лидера изменяется на Сигнатура: my_callback(id integer, host text, port integer) RETURNS void В этой сигнатуре biha передаёт в функцию-обработчик информацию о лидере: идентификатор, имя хоста и номер порта узла. |
LEADER_TO_FOLLOWER | Вызывается на старом лидере, который вернулся в кластер после понижения. Сигнатура: my_callback() RETURNS void |
NODE_ADDED | Вызывается на каждом узле при добавлении нового узла в BiHA-кластер. Сигнатура: my_callback(id integer, host text, port integer, mode integer) RETURNS void В этой сигнатуре biha передаёт в функцию-обработчик информацию о новом узле, такую как имя хоста, номер порта узла и режим работы: |
NODE_REMOVED | Вызывается на каждом узле при удалении узла из BiHA-кластера. Сигнатура: my_callback(id integer) RETURNS void В этой сигнатуре biha передаёт в функцию-обработчик ID удалённого узла. |
OFFERED_TO_LEADER | Вызывается на узле, который был назначен лидером вручную, перед непосредственным переходом в статус лидера. Сигнатура: my_callback() RETURNS void |
STATUS_CHANGED | Вызывается на каждом узле при изменении значений в полях представления biha.status_v (кроме ПримечаниеНе рекомендуется выполнять другие обработчики во время использования Сигнатура: my_callback() RETURNS void |
TERM_CHANGED | Вызывается на узле, когда значение его параметра Сигнатура: my_callback(old_term integer, new_term integer) RETURNS void В этой сигнатуре biha передаёт старое и новое значение параметра |
26.3.12.1. Особенности и ограничения #
При наступлении события функции-обработчики исполняются последовательно. В это время biha не может изменить своё состояние, например инициировать выборы.
Если исполнение функции-обработчика длится дольше, чем указано в callbacks_timeout, biha останавливает исполнение и продолжает работать в обычном режиме.
В кластерах с асинхронной репликацией функция biha.register_callback не дожидается, пока обработчики появятся на всех узлах. Это может привести к ситуации, когда обработчики на лидере есть, а на последователе — нет, так как он отстаёт.
В норме функции-обработчики не исполняются на рефери в режиме
referee. Однако, если вы зарегистрировали функции-обработчики на лидере до добавления рефери, они могут исполняться на рефери и их также нельзя с него удалить.Не рекомендуется вызывать функции BiHA во время выполнения обработчика, так как другие обработчики в очереди могут не выполниться.
Примечание
Не вызывайте функции biha внутри обработчика, так как это может вызвать непредвиденное поведение.
26.3.12.2. Управление функциями-обработчиками #
Для управления функциями-обработчиками вы можете выполнять следующие действия:
зарегистрировать один или несколько обработчиков на одно событие
просмотреть список зарегистрированных обработчиков
отменить регистрацию обработчика
Регистрация функций-обработчиков
Напишите SQL-функцию и зарегистрируйте её в качестве обработчика с помощью функции biha.register_callback.
В этом примере вы создадите несколько SQL-функций на языке PL/pgSQL и зарегистрируете их в качестве обработчиков разных типов.
Убедитесь, что лидер BiHA-кластера находится в состоянии
LEADER_RW.На лидере используйте
psqlдля подключения к базе данныхbiha_db:postgres=# \c biha_db
Создайте следующие функции-обработчики:
-- запись при смене значения term CREATE FUNCTION log_term_changed(old_term integer, new_term integer) RETURNS void AS $$ BEGIN RAISE LOG 'Callback: Term changed from % to %', old_term, new_term; END; $$ LANGUAGE plpgsql; -- запись при смене лидера CREATE FUNCTION log_leader_changed(id integer, host text, port integer) RETURNS void AS $$ BEGIN RAISE LOG 'Callback: New leader is % %:%', id, host, port; END; $$ LANGUAGE plpgsql; -- запись при понижении лидера CREATE FUNCTION log_leader_to_follower() RETURNS void AS $$ BEGIN RAISE LOG 'Callback: demote'; END; $$ LANGUAGE plpgsql;Зарегистрируйте созданные функции:
biha_db=# SELECT biha.register_callback('TERM_CHANGED', 'log_term_changed', 'biha_db'); biha_db=# SELECT biha.register_callback('LEADER_CHANGED', 'log_leader_changed', 'biha_db'); biha_db=# SELECT biha.register_callback('LEADER_TO_FOLLOWER', 'log_leader_to_follower', 'biha_db');Вы также можете указать пользователя, от имени которого будут исполняться функции-обработчики или определить порядок их исполнения. Подробнее читайте в описании функции biha.register_callback.
Просмотр функций-обработчиков
Зарегистрированные обработчики добавляются в таблицу biha.callbacks, которая находится в базе данных biha_db.
Для просмотра всех зарегистрированных обработчиков выполните следующую команду:
На лидере используйте
psqlдля подключения к базе данныхbiha_db:postgres=# \c biha_db
Отобразите содержимое таблицы
biha.callbacks:biha_db=# SELECT * FROM biha.callbacks; 1 | log_term_changed 2 | log_leader_changed 3 | log_leader_to_follower (3 rows)
Отмена регистрации функции-обработчика
Отменённый обработчик удаляется из таблицы biha.callbacks.
Убедитесь, что лидер BiHA-кластера находится в состоянии
LEADER_RW.На лидере используйте
psqlдля подключения к базе данныхbiha_db:postgres=# \c biha_db
Получите идентификатор обработчика, который вы хотите отменить, например
log_leader_changed:biha_db=# SELECT id FROM biha.callbacks WHERE func = 'log_leader_changed';
Возвращается идентификатор обработчика, например
2.Отменить регистрацию обработчиков:
biha_db=# SELECT biha.unregister_callback(2);
Регистрация обработчика отменена.
26.3.13. Восстановление из резервной копии #
Если экземпляр Postgres Pro Standard был восстановлен из одного из узлов кластера BiHA в отдельный узел и/или на момент времени (Point-in-Time Recovery, PITR), между восстановленным узлом и работающими узлами кластера BiHA не должно быть соединения. Чтобы предотвратить соединение, выполните следующие действия на восстановленном узле перед его запуском:
Удалите директиву включения
include 'postgresql.biha.conf'из файла конфигурации postgresql.conf.Убедитесь, что расширение biha отсутствует в shared_preload_libraries в файле postgresql.conf и, если применимо, в файле postgresql.auto.conf.
Если вы хотите добавить восстановленный узел в кластер, выполните следующие действия:
На восстановленном узле вручную настройте потоковую репликацию от лидера.
Синхронизируйте восстановленный узел с лидером.
Остановите восстановленный узел с помощью pg_ctl:
pg_ctl stop -D
каталог_PGDATA_восстановленного узлаДобавьте восстановленный узел в кластер с помощью команды bihactl node add с параметром --convert-standby.
Запустите восстановленный узел с помощью pg_ctl:
pg_ctl start -D
каталог_PGDATA_восстановленного узла
26.3.14. Выполнение пользовательских скриптов с помощью команды bihactl run #
BiHA поддерживает выполнение пользовательских скриптов с помощью команды bihactl run. Скрипты представляют собой YAML-файлы с SQL-запросами к BiHA-кластеру. Например, можно создать скрипт для отслеживания состояния кластера, а затем выполнить его с помощью bihactl run:
bihactl run scripts/monitoring.yaml
Скрипты можно запускать через интерфейс командной строки (CLI) или как самоисполняемые файлы с шебангом.
Примечание
Перед выполнением скриптов с помощью команды bihactl run, настройте аутентификацию для biha_monitor_user.
За подробной информацией обратитесь к подразделам ниже.
26.3.14.1. Структура скрипта #
Скрипт состоит из трёх основных разделов: meta, settings и scripts. Например:
meta:
description: "описание"
versions:
biha: "1.7" # Минимальная версия BiHA, с которой совместим скрипт
format: "1.0" # Версия формата файла
settings:
sql:
users:
- name: user1
pgpassfile: ~/.pgpass
scripts:
- sql:
host: host1
port: 5433
user: user1
database: db1
query: "SELECT * FROM biha.status_v"26.3.14.1.1. Раздел settings #
На данный момент раздел settings можно использовать для описания методов аутентификации нескольких пользователей.
Поддерживаются два типа аутентификации: файл паролей и SSL-сертификат. По умолчанию используется файл паролей. Метод аутентификации конкретного пользователя указывается в разделе settings / sql / users.
Пароль для пользователя задаётся через путь к файлу .pgpass. Если ключ passfile не указан, поиск файла осуществляется по стандартному пути ~/.pgpass. Например:
settings:
sql:
users:
- name: user1
pgpassfile: /tmp/.pgpassДля аутентификации по SSL-сертификату укажите следующие параметры:
settings:
sql:
users:
- name: user1
ssl:
cert_file: /путь/к/сертификату_в_формате_.pem
key_file: /путь/к/ключу_в_формате_.pem
root_cert_file: /путь/к/сертификату_цс_в_формате_.pem
ssl_mode: verify-full26.3.14.1.2. Спецификация SQL-запросов #
Спецификация SQL-запросов содержит следующие поля:
| Поле | Описание |
|---|---|
query | SQL-запрос |
host | Хост узла (по умолчанию: localhost) |
port | Порт подключения (по умолчанию: 5432) |
user | Имя пользователя Postgres Pro Standard (по умолчанию: biha_monitor_user) |
database | Имя базы данных (по умолчанию: biha_db) |
26.3.14.1.3. Примеры скрипта #
Ниже привидён пример максимально короткого скрипта. Этот скрипт подключается к базе данных biha_db через localhost:5432 от имени biha_monitor_user и ищет пароль пользователя в ~/.pgpass:
meta:
description: "description"
versions:
biha: "1.7"
format: "1.0"
scripts:
- sql:
query: select 1В следующем примере показаны все возможные параметры. Обратите внимание, что ssl и pgpassfile являются взаимоисключающими, поэтому используйте один из них.
meta:
description: "description"
versions:
biha: "1.7"
format: "1.0"
settings:
sql:
users:
- name: biha_replication_user
ssl:
cert_file: $HOME/ssl/biha.crt
key_file: $HOME/ssl/biha.key
root_ca_file: $HOME/ssl/rootCA.crt
ssl_mode: require
- name: user1
pgpassfile: ~/.pgpass
scripts:
- sql:
host: biha-db-1
port: 5431
database: db1
user: user2
query: select 1
- sql:
host: biha-db-2
port: 5432
database: db2
user: user1
query: select 226.3.14.2. Запуск скриптов с шебангом #
Чтобы скрипт запускался напрямую, укажите команду bihactl run в первой строке. Например:
#! bihactl run
meta:
description: "biha.config()"
scripts:
- sql:
query: SELECT id, name, mode FROM biha.config()В шебанге можно указать либо короткую форму (bihactl run), либо полный путь к исполняемому файлу:
#! /путь/к/bihactl_runЧтобы сделать файл скрипта исполняемым, используйте следующую команду:
chmod +xпуть/к/скрипту_в_формате.yaml./путь/к/скрипту_в_формате.yaml
26.3.15. Обновление и миграция #
В зависимости от вашей текущей версии Postgres Pro Standard обратитесь к одному из следующих разделов:
Для перехода с Postgres Pro Standard версии 17.X на версию 18.X обратитесь к разделу Миграция на версию 18.X.
Для обновления с Postgres Pro Standard версии 18.X на последнюю корректирующую версию Postgres Pro Standard 18 обратитесь к разделу Обновление BiHA-кластера с версии 18.X на версию 18.6.
26.3.15.1. Миграция на версию 18.X #
BiHA поддерживает следующие варианты миграции BiHA-кластера на основную версию:
Если в вашей организации допустимо временное прекращение работы базы данных, рекомендуется использовать процедуру Миграция BiHA-кластера на версию 18.X с помощью pg_upgrade. Эта процедура подходит для миграций с Postgres Pro Standard версии 17.X на версию 18.X.
Если простой в работе базы данных необходимо минимизировать, используйте процедуру Миграция BiHA-кластера на версию 18.X с минимальным простоем, где применяется специальная функциональность утилиты bihactl. Эта процедура подходит только для миграции с Postgres Pro Standard версии 17.X на версию 18.X.
26.3.15.1.1. Миграция BiHA-кластера на версию 18.X с помощью pg_upgrade #
Чтобы обновить BiHA-кластер с версии Postgres Pro Standard 17.X до версии 18.X, выполните следующие шаги:
(Необязательно) Удалите роль
biha_replication_userс помощью командыDROP ROLE:DROP ROLE biha_replication_user;
Удалить роль
biha_replication_userнеобходимо, если вы хотите задать новый пароль для этой роли в ходе миграции, так как bihactl не поддерживает изменение пароля для существующей роли. При конвертации ведущего узла в лидера в последующих шагах этой инструкции рольbiha_replication_userбудет создана заново, и вы сможете задать новый пароль через переменные окружения или файл паролей.Если оставить существующую роль
biha_replication_user, пароль можно изменить вручную с помощью командыALTER ROLE.Остановите все узлы кластера с помощью команды
pg_ctl.Обновите узлы с помощью инструкции из документации pg_upgrade.
Добавьте последователей одним из следующих способов:
Если вы использовали rsync для обновления ведомых узлов, преобразуйте ведущие узлы в последователей.
Если вы не использовали rsync, добавьте последователей с нуля.
(Необязательно) Чтобы добавить рефери:
На бывшем узле-рефери удалите каталог
PGDATA.
26.3.15.1.2. Миграция BiHA-кластера на версию 18.X с минимальным простоем #
Используйте эту инструкцию для миграции BiHA-кластера с Postgres Pro Standard версии 17.X на версию 18.X, если временную остановку работы базы данных необходимо свести к минимуму.
Для ясности в этой инструкции текущий BiHA-кластер, миграцию которого вы выполняете, называется «старый кластер», а обновлённый BiHA-кластер — «новый кластер».
Этот метод миграции обеспечивается специальными командами утилиты bihactl, разработанными для автоматизации шагов по миграции. Во время миграции вы создадите лидера нового кластера на дополнительном сервере или преобразуете существующего последователя в нового лидера и затем переместите последователей из старого кластера в новый. Это позволит старому кластеру продолжить работу и оставаться отказоустойчивым на протяжении всего процесса миграции, в то время как новый кластер с версией Postgres Pro Standard 18.X получит все обновления по логической репликации и возьмёт на себя нагрузку только после завершения миграции и настройки отказоустойчивости.
Важно
Перед началом миграции внимательно прочитайте Предварительные требования и следуйте им во время процесса миграции.
Настоятельно рекомендуется испытать процедуру миграции в тестовой среде, прежде чем выполнять её для производственного кластера.
Все операции по миграции необходимо выполнять от имени пользователя
postgres.
Процедура миграции состоит из следующих шагов:
Шаг 0: Изучите раздел Предварительные требования и выполните необходимые подготовительные действия.
Шаг 1: Подготовьте лидера нового кластера с помощью дополнительного сервера или путём преобразования существующего последователя.
Шаг 2: Переместите последователя из старого кластера в новый.
Шаг 3: Завершите процедуру миграции и включите нагрузку на новом кластере.
Предварительные требования
Убедитесь, что выполнены все условия, перечисленные в разделе Предварительные требования и особенности.
На старом лидере создайте пользователя с правами на создание подписок и использование
pg_replication_origin_advance().Позднее вы установите этого пользователя в качестве значения параметра --subscriber-username.
Для лидера старого кластера выполните следующие действия:
Для параметра wal_level задайте значение
logical.Для параметра nquorum задайте значение выше, чем количество узлов в кластере, чтобы исключить переключение во время миграции.
Учитывайте все ограничения логической репликации на протяжении всего процесса миграции.
Ограничьте операции DCL и DDL на время всего процесса миграции. На старом лидере во время миграции разрешены только операции DML, т.е. непосредственно изменение данных.
Убедитесь, что во всех обновляемых таблицах присутствуют первичные ключи.
Обеспечьте минимальную нагрузку на лидера старого кластера.
Подготовка нового лидера на дополнительном сервере
В этой процедуре лидер нового кластера создаётся на дополнительном сервере, который вы подготавливаете заранее. Другой подход предусматривает подготовку лидера нового кластера путём преобразования существующего последователя.
При создании нового лидера команда bihactl upgrade start выполняет следующие действия:
Создаёт последователя с Postgres Pro Standard версии 17.X.
Удаляет последователя из старого кластера, оставляя его в качестве физической реплики с Postgres Pro Standard версии 17.X.
Конвертирует физическую реплику в логическую с помощью pg_createsubscriber.
Обновляет логическую реплику до Postgres Pro Standard версии 18.X.
Преобразовывает логическую реплику с Postgres Pro Standard версии 18.X в лидера нового кластера.
Примечание
После выполнения команды bihactl upgrade start новый лидер будет недоступен для любых подключений, кроме внутренних подключений через сокет Unix, до завершения миграции с помощью команды bihactl upgrade finish.
Чтобы подготовить нового лидера:
Подготовьте дополнительный сервер, который будет использован для развёртывания лидера нового кластера с версией Postgres Pro Standard 18.X.
Операционная система и исполняемые файлы Postgres Pro Standard, установленные на дополнительном сервере, должны быть такими же, как и на узлах старого кластера.
Убедитесь, что базы данных старого кластера доступны с подготовленного дополнительного сервера.
Если они не доступны, настройте доступ в файле
pg_hba.biha.confстарого лидера.На всех узлах старого кластера и дополнительном сервере установите Postgres Pro Standard версии 18.X.
На лидере старого кластера получите «магическую» строку:
SELECT biha.get_magic_string();
На подготовленном дополнительном сервере выполните команду bihactl upgrade start:
bihactl upgrade start \ --magic-string=магическая_строка_старого_лидера\ --new-leader-biha-port=порт_biha_нового_лидера\ --new-leader-host=хост_нового_лидера\ --new-leader-port=порт_нового_лидера\ --old-bin=/путь/к/исполняемым/файлам/версии_17\ --old-pgdata=каталог_PGDATA_версии_17\ --new-pgdata=каталог_PGDATA_версии_18\ --subscriber-username=имя_пользователяКаталоги
PGDATA_версии_17иPGDATA_версии_18должны быть пусты.В результате выполнения команды создаётся новый лидер с включённым сервисным режимом, а также с логической репликацией, настроенной для всех пользовательских баз данных старого кластера.
Подсказка
В выводе команды также присутствует «магическая» строка. Можно скопировать её и сохранить для использования на следующих этапах миграции.
Запустите нового лидера с помощью pg_ctl:
pg_ctl start -D
каталог_PGDATA_нового_лидера-lфайл_журнала_нового_лидераПроверьте, что новый лидер находится в состоянии
LEADER_RW, с помощью представления biha.status_v:SELECT * FROM biha.status_v;
На новом лидере проверьте подписки с помощью каталога pg_subscription:
SELECT subname, subpublications FROM pg_subscription;
На старом лидере выполните следующие действия:
Проверьте слоты репликации с помощью представления pg_replication_slots:
SELECT slot_name, slot_type FROM pg_replication_slots;
Проверьте публикации с помощью каталога pg_publication:
SELECT * FROM pg_publication;
Убедитесь, что нет отставания репликации:
/путь/к/исполняемым/файлам/версии_17/psql biha_db -qtAXc "SELECT sum(pg_wal_lsn_diff(pg_current_wal_lsn(), confirmed_flush_lsn)) AS lag_bytes FROM pg_replication_slots where slot_type = 'logical';"
Подготовка нового лидера путём преобразования последователя
В этой процедуре существующий последователь преобразовывается в лидера нового кластера. Если вы не хотите использовать последователя для миграции, подготовьте лидера нового кластера с помощью дополнительного сервера.
При создании нового лидера команда bihactl upgrade start выполняет следующие действия:
Удаляет последователя из старого кластера, оставляя его в качестве физической реплики с Postgres Pro Standard версии 17.X.
Конвертирует физическую реплику в логическую с помощью pg_createsubscriber.
Обновляет логическую реплику до Postgres Pro Standard версии 18.X.
Преобразовывает логическую реплику с Postgres Pro Standard версии 18.X в лидера нового кластера.
Примечание
После выполнения команды bihactl upgrade start новый лидер будет недоступен для любых подключений, кроме внутренних подключений через сокет Unix, до завершения миграции с помощью команды bihactl upgrade finish.
Чтобы подготовить нового лидера:
На всех узлах старого кластера, включая последователя, которого вы хотите преобразовать, установите Postgres Pro Standard версии 18.X.
На лидере старого кластера получите «магическую» строку:
SELECT biha.get_magic_string();
На последователе, который вы хотите преобразовать в лидера нового кластера, выполните команду bihactl upgrade start:
bihactl upgrade start \ --new-magic-string=магическая_строка_нового_лидера\ --old-bin=/путь/к/исполняемым/файлами/версии_17_существующего_последователя\ --old-pgdata=каталог_PGDATA_версии_17_существующего_последователя\ --new-pgdata=каталог_PGDATA_версии_18\ --subscriber-username=имя_пользователя\ --convertКаталог
PGDATA_верссии_18должен быть пустым.В результате выполнения команды создаётся новый лидер с включённым сервисным режимом, а также с логической репликацией, настроенной для всех пользовательских баз данных старого кластера.
Подсказка
В выводе команды также присутствует «магическая» строка. Можно скопировать её и сохранить для использования на следующих этапах миграции.
Запустите нового лидера с помощью pg_ctl:
pg_ctl start -D
каталог_PGDATA_нового_лидера-lфайл_журнала_нового_лидераПроверьте, что новый лидер находится в состоянии
LEADER_RW, с помощью представления biha.status_v:SELECT * FROM biha.status_v;
На новом лидере проверьте подписки с помощью каталога pg_subscription:
SELECT subname, subpublications FROM pg_subscription;
На старом лидере выполните следующие действия:
Проверьте слоты репликации с помощью представления pg_replication_slots:
SELECT slot_name, slot_type FROM pg_replication_slots;
Проверьте публикации с помощью каталога pg_publication:
SELECT * FROM pg_publication;
Убедитесь, что нет отставания репликации:
/путь/к/исполняемым/файлам/версии_17/psql biha_db -qtAXc "SELECT sum(pg_wal_lsn_diff(pg_current_wal_lsn(), confirmed_flush_lsn)) AS lag_bytes FROM pg_replication_slots where slot_type = 'logical';"
Перемещение последователя
Извлеките одного из последователей из старого кластера и добавьте его в новый кластер. Повторите эту процедуру для перемещения нескольких последователей из старого кластера в новый, чтобы обеспечить отказоустойчивость нового кластера после миграции.
Важно
В целях сохранности данных не рекомендуется извлекать всех последователей из работающего старого кластера. Можно оставить одного последователя в работающем старом кластере до конца миграции, а затем добавить нового последователя в новый кластер вручную.
При перемещении последователя его параметры конфигурации Postgres Pro копируются с нового лидера. Поэтому, если на последователе были заданы какие-либо специфичные для него параметры конфигурации Postgres Pro, необходимо вновь задать их вручную после перемещения.
Чтобы переместить последователя:
Чтобы обеспечить работоспособность старого кластера после удаления последователя, уменьшите значения параметров
minnodes,sync_standbysиsync_standbys_minс помощью функций biha.set_minnodes, biha.set_sync_standbys и biha.set_sync_standbys_min соответственно.Значения параметров конфигурации
minnodes,sync_standbysиsync_standbys_minвсегда должны быть ниже, чем общее количества узлов кластера. Текущие значения можно проверить с помощью функции biha.config.(Необязательно) Если вы не сохранили «магическую» строку на предыдущем шаге, получите её на лидере нового кластера:
SELECT biha.get_magic_string();
На последователе, который вы хотите переместить, выполните команду bihactl upgrade move:
bihactl upgrade move \ --new-magic-string=
магическая_строка_нового_лидера\ --old-bin=/путь/к/исполняемым/файлами/версии_17\ --new-pgdata=каталог_PGDATA_версии_18\ --old-pgdata=каталог_PGDATA_версии_17Переменная
каталог_PGDATA_версии_17— это каталогPGDATAработающего старого последователя.каталог_PGDATA_версии_18предназначен для обновлённого нового последователя и должен быть пустым.Запустите перемещённого последователя с помощью pg_ctl:
pg_ctl start -D
каталог_PGDATA_перемещённого_последователя-lфайл_журнала_перемещённого_последователяПроверьте статус нового кластера с помощью команды bihactl cluster status.
Завершение миграции
Важно
На этом шаге потребуется минимальный простой для перенастройки подключений приложений и клиентов на новый кластер и включения на нём нагрузки.
Отключите нагрузку на старом лидере и дождитесь, когда новый лидер завершит получение данных по логической репликации.
Чтобы убедиться, что данные получены в полном объёме, на старом лидере выполните следующую команду:
/путь/к/исполняемым/файлам/версии_17/psql biha_db -qtAXc "SELECT sum(pg_wal_lsn_diff(pg_current_wal_lsn(), confirmed_flush_lsn)) AS lag_bytes FROM pg_replication_slots where slot_type = 'logical';"В выводе должно отображаться значение
0дляlag_bytes.Но новом лидере выполните команду bihactl upgrade finish:
bihactl upgrade finish \ --new-magic-string=
магическая_строка_нового_лидера\ --subscriber-username=имя_пользователяВыполнение команды приводит к следующим результатам:
Состояние старого лидера изменяется на
LEADER_RO.Новый лидер выходит из сервисного режима и становится доступным для транзакций на запись.
Подписки логической репликации удаляются с нового лидера.
Параметры
minnodes,sync_standbysиsync_standbys_minвозвращаются к изначальным значениям, заданным на старом лидере до начала миграции.
На старом лидере обновите значения последовательностей для всех баз данных с помощью следующей команды:
/путь/к/исполняемым/файлам/версии_17/psql biha_db -qtAXc "SELECT 'SELECT setval(' || quote_literal(sequencename) || ', ' || last_value || ', true);' FROM pg_sequences;"Скопируйте вывод команды, выполненной на предыдущем шаге, и выполните его на новом лидере.
Перенастройте подключения приложений и клиентов на новый кластер.
На новом кластере возобновите нагрузку, которая была отключена на старом лидере в начале этой процедуры.
26.3.15.2. Обновление BiHA-кластера с версии 18.X на версию 18.6 #
Используйте эту инструкцию для обновления с Postgres Pro Standard версии 18.X на версию 18.6.
Остановите одного из последователей с помощью команды pg_ctl.
Обновите последователя.
Запустите последователя с помощью команды pg_ctl.
Повысьте обновлённого последователя до лидера с помощью функции biha.set_leader.
Остановите, обновите и запустите остальных последователей и старого лидера.
Повысьте старого лидера с помощью функции biha.set_leader.
На лидере обновите расширение с помощью следующей команды:
ALTER EXTENSION biha UPDATE;
Важно
Не поддерживается обновление версии расширения biha на рефери в режиме
referee. Удалите рефери с помощью функции biha.remove_node, удалите его каталогPGDATA, а затем создайте новый узел-рефери с нуля.За подробной информацией об изменениях версий расширений обратитесь к замечаниям к выпускам.
26.3.16. Выключение расширения biha #
Можно временно выключить расширение biha в кластере. Процедуры выключения различаются в зависимости от роли узла.
Выключение biha на последователе
Важно
При выключении расширения biha на последователе физическая репликация прекращается.
Остановите последователя с помощью команды pg_ctl.
На лидере в состоянии
LEADER_RWвызовите функцию biha.remove_node, чтобы исключить из кластера узел, на котором необходимо выключить biha:biha_db=# SELECT biha.remove_node(
идентификатор);На последователе выполните следующие действия:
Удалите директиву включения
include 'postgresql.biha.conf'из файла конфигурации postgresql.conf.Удалите расширение biha из shared_preload_libraries в файле postgresql.conf и, если применимо, в файле postgresql.auto.conf.
Запустите последователя с помощью команды pg_ctl.
Выключение biha на лидере
Удалите директиву включения
include 'postgresql.biha.conf'из файла конфигурации postgresql.conf.Удалите расширение biha из shared_preload_libraries в файле postgresql.conf и, если применимо, в файле postgresql.auto.conf.
Остановите и запустите узел-лидер с помощью pg_ctl.
26.3.17. Удаление расширения biha #
Вы можете полностью удалить расширение biha и навсегда отключить функциональность BiHA в кластере. При этом можно сохранить кластер стандартной конструкции ведущий-ведомый или разделить кластер на отдельные узлы.
Удаление расширения biha и сохранение кластера стандартной конструкции ведущий-ведомый
Вы можете удалить функциональность BiHA, сохранив кластер в стандартной конструкции ведущий-ведомый с настроенной репликацией.
На каждом последователе получите и сохраните текущие значения параметров конфигурации primary_conninfo и primary_slot_name:
SHOW primary_conninfo; SHOW primary_slot_name;
На лидере выполните команду
DROP EXTENSION. Её необходимо выполнить на лидере в состоянииLEADER_RWи из базы данныхbiha_db:biha_db=# DROP EXTENSION biha;
Остановите все узлы кластера с помощью pg_ctl.
На всех узлах кластера выполните следующие действия:
Удалите директиву включения
include 'postgresql.biha.conf'из файла конфигурации postgresql.conf.Удалите расширение biha из shared_preload_libraries в файле postgresql.conf и, если применимо, в файле postgresql.auto.conf.
Удалите все файлы из каталога
pg_biha.
На каждом последователе добавьте параметры конфигурации primary_conninfo и primary_slot_name в файл postgresql.conf с указанием значений, которые вы сохранили в начале этой процедуры.
Запустите все узлы кластера с помощью pg_ctl.
Удаление расширения biha и разделение кластера на отдельные узлы
Вы можете удалить функциональность BiHA и разделить кластер на отдельные узлы.
Остановите все узлы кластера с помощью pg_ctl.
На всех узлах кластера выполните следующие действия:
Удалите директиву включения
include 'postgresql.biha.conf'из файла конфигурации postgresql.conf.Удалите расширение biha из shared_preload_libraries в файле postgresql.conf и, если применимо, в файле postgresql.auto.conf.
Удалите все файлы из каталога
pg_biha.
На каждом последователе выполните команду
pg_ctl promote:pg_ctl promote -D
/путь/к/каталогу/pgdata/последователяЗапустите все узлы с помощью pg_ctl.
26.3. Administration #
- 26.3.1. Changing Cluster Composition
- 26.3.2. Managing Configuration Parameters
- 26.3.3. Manual Switchover
- 26.3.4. Managing SSL for Service Connections
- 26.3.5. Roles
- 26.3.6. Using the Service Mode
- 26.3.7. Automatic Cluster Synchronization after Failover
- 26.3.8. Restoring the Node from the
NODE_ERRORState- 26.3.9. Hanging Prevention Mechanism
- 26.3.10. Replication Configuration
- 26.3.11. Logging
- 26.3.12. Callbacks
- 26.3.13. Recovering from a Backup
- 26.3.14. Executing Custom Scripts with
bihactl run- 26.3.15. Upgrade and Migration
- 26.3.16. Disabling biha
- 26.3.17. Removing biha
- 26.3.2. Managing Configuration Parameters
26.3.1. Changing Cluster Composition #
You can change the cluster composition as follows:
To add a node, use the bihactl node add command with the relevant options.
Note
The
walreceiverprocess restarts every time you add a node to a cluster with quorum-based synchronous replication.To add a segment, use the biha.add_node function.
To remove a node or a segment, use the biha.remove_node function.
To change the leader manually, use the biha.set_leader function. For more information, see Manual Switchover.
26.3.2. Managing Configuration Parameters #
You can manage BiHA configuration parameters as follows:
The majority of BiHA configuration parameters are stored in
pg_biha/biha_conf_and can be set with special functions. All available configuration parameters are listed in Section 26.4.1, and each description also references the functions used to manage it. For the list of all functions, refer to Section 26.4.2.config_version.jsonAll functions must be called from the
biha_dbdatabase. If otherwise is not specified in the function description, a function must be called on the leader node.For example, use the biha.set_heartbeat_max_lost function to set the heartbeat_max_lost parameter value:
biha_db=# SELECT biha.set_heartbeat_max_lost(7);
A few optional BiHA configuration parameters can be set with the
ALTER SYSTEMSETcommand. These configuration parameters are listed in Section 26.4.1.5.For example:
ALTER SYSTEM SET biha.autorewind = true;
To view the current values of BiHA configuration parameters, use the biha.config.
For proper operation, BiHA sets some Postgres Pro configuration parameters. To safely decrease them, use the procedure described in Section 26.1.1.1.
26.3.3. Manual Switchover #
In addition to the built-in automatic failover capabilities, the BiHA solution supports manual switchover both for standard BiHA clusters and for GDBiHA clusters. The nquorum value is ignored when you perform manual switchover.
You can perform manual switchover either with the biha.set_leader function or with special bihactl commands.
Consider the following recommendations:
Important
To ensure successful leader change, execute the CHECKPOINT command before performing manual switchover.
Call the
biha.set_leaderfunction or execute special bihactl commands on the node that you want to set as the new leader or front follower. Avoid calling thebiha.set_leaderfunction on the current leader. If you call the function on the current leader in theLEADER_RWstate, in case of a successful switchover request, there may not be enough time for the request result to be sent to the client before the current leader reboots for demotion.Avoid re-calling the
biha.set_leaderfunction or re-executing special bihactl commands until the end of the switchover process. If you need to switch over again shortly after the first switchover, wait for the nominated node to change its state toLEADER_RO/LEADER_RWor, if promotion failed by some reason, back toFOLLOWER.
When you set the new leader or front follower, the following happens:
The state of the nominated node changes to
FOLLOWER_OFFERED.All attempts to perform elections are blocked.
The current leader changes its state to
LEADER_RO. If you switch over the front follower, its state remains unchanged (FRONT_FOLLOWER).FOLLOWER_OFFEREDsearches for the latest replication source in its segment and configures replication from that source.When the node in the
FOLLOWER_OFFEREDstate detects there is no leader in theLEADER_RWstate and has the largest number of data within a segment, it becomes the new leader or front follower.If the switchover process does not end within the established no_wal_on_follower timeout, the nominated node returns to the follower role and the current leader or front follower keeps its role. However, if there is no leader or front follower, automatic elections are performed to choose the new leader or front follower.
26.3.3.1. Switchover Using biha.set_leader #
You can perform switchover using the biha.set_leader function as follows:
To nominate the new leader or front follower, call the
biha.set_leaderfunction specifying the ID of the node that you want to promote. Depending on the segment where the nominated node belongs to (leader segment or follower segment), the node becomes either the new leader or front follower of that segment.To switch over between segments, call the
biha.set_leaderfunction specifying the ID of the segment that you want to promote to the leader segment. After switchover, the front follower of the promoted segment becomes the new leader, and the former leader becomes the front follower of the segment it belongs to.
26.3.3.2. Switchover Using bihactl Commands #
You can perform switchover using special bihactl commands. The commands must be executed on a node or segment you want to promote.
To promote a node to the leader, on this node, execute the bihactl node set leader command. The node must be located in the leader segment.
To promote a node to the front follower, on this node, execute the bihactl node set front-follower command. The node must be located in the follower segment.
To promote a segment to the leader, on this segment, execute the bihactl segment set leader command.
To promote either a segment or a node to the leader, on this segment or node, execute the bihactl unit set leader command. Depending on the identifier specified, this command operates either as bihactl segment set leader or bihactl node set leader.
26.3.4. Managing SSL for Service Connections #
You can enable or disable SSL to secure service connections in the initialized BiHA cluster, as well as change paths to the public certificate and private key.
Important
To use SSL for service connections, your installed OpenSSL version must be 1.1.1 or higher. Otherwise, SSL is not enabled and a corresponding message is recorded in the log.
You can modify the SSL configuration as follows:
To enable SSL, on the leader node, set use_ssl to
true:biha_db=# select biha.set_use_ssl(true); set_use_ssl ---------------- t (1 row)
To disable SSL, set the value of
use_ssltofalse.To change paths to the public certificate and private key, use ssl_certificate and ssl_private_key respectively.
By default, the path to the public certificate is
/PGDATA/pg_biha/biha_pub_cert.pemand the path to the private key is/PGDATA/pg_biha/biha_priv_key.pem.
Stop and start the nodes using pg_ctl.
Important
The leader node must be the last to stop and first to start. Since enabling SSL in a BiHA cluster involves using the standard TLS handshake process, it is recommended to minimize the time lag between stopping and starting nodes.
26.3.5. Roles #
When you initialize the high-availability cluster, the biha_db database is created as well as the biha extension is created in the biha scheme of the biha_db database. Besides, the following roles are created and used:
BIHA_CLUSTER_MANAGEMENT_ROLEallows execution of all biha extension functions.BIHA_REPLICATION_ROLEis used when running pg_rewind and pg_probackup.biha_replication_useris a member of theBIHA_REPLICATION_ROLEandBIHA_CLUSTER_MANAGEMENT_ROLEroles and can request both client and replication connections. It is used by the bihactl utility as well as when the follower node is connected to the leader node. This role owns thebiha_dbdatabase. The password for thebiha_replication_userrole in the password file must be the same on all nodes of the BiHA cluster. The password for the role is prompted upon the BiHA cluster creation.biha_callbacks_useris the default user for callback execution. This user can connect to a database but has no privileges.biha_monitor_useris the default user for executing custom scripts with bihactl run. This user can connect to a database but has no privileges.The predefined
pg_monitoris used to monitor the state of the BiHA cluster.
26.3.6. Using the Service Mode #
BiHA provides the service mode feature to temporarily pause BiHA operation. This may be required when you modify configuration parameters and want to ensure changes are applied on all cluster nodes, for example, when decreasing Postgres Pro configuration parameter values.
When BiHA is in the service mode:
followers continue receiving WAL
elections are cancelled and no node can stand as a candidate
the leader can be switched over manually
You can manage the service mode by calling the biha.service_mode function on the leader node.
Using biha.service_mode, you can do the following:
Enable the service mode by setting the
enableparameter of thebiha.service_modefunction totrue:biha_db=# SELECT biha.service_mode(true);
Disable the service mode by setting the
enableparameter of thebiha.service_modefunction tofalse:biha_db=# SELECT biha.service_mode(false);
When you disable the service mode, BiHA verifies whether parameters modified during service mode are applied on all nodes of the cluster. If any unapplied parameters are found, the service mode is not disabled, and the function returns errors listing all unapplied parameters. For example:
biha _db=# SELECT biha.service_mode (false); ERROR: [BiHA] Config changes HINT: Some parameters have been changed but not applied: Node 3: max_connections To force exit service mode, use: "select * from biha.service_mode(false, true)"
If required, you can disable the service mode ignoring those errors by setting the
forceparameter of thebiha.service_modefunction totrue:biha_db=# SELECT biha.service_mode(false, true);
26.3.7. Automatic Cluster Synchronization after Failover #
BiHA provides capabilities for automatic cluster synchronization after timelines of nodes have diverged. For example, to bring the old leader back to the cluster after failover.
You can manage automatic synchronization in your BiHA cluster as follows:
Enable automatic rewind by setting the biha.autorewind configuration parameter to
true. The automatic rewind is performed if it may complete successfully, meaning that preliminary launching of the pg_rewind tool with the--dry-runoption was a success.If the automatic rewind fails, the node state changes to
NODE_ERROR. In this case, you can find the actual rewind state of the node in thebiha.statefile as described in Section 26.3.7.1.Important
The rewind may cause the loss of some node WAL records.
To avoid running pg_rewind when WAL divergence is caused only by redundant heartbeat records, you can use the WAL trimming functionality managed by the biha.autowaltrim configuration parameter. When enabled, the WAL trimming algorithm finds the last common point in WALs of the diverged node and the new leader, verifies that all subsequent records are only heartbeats, and automatically deletes redundant heartbeat records from the diverged node so it can resume replication. It is useful after a split-brain, when the former leader reconnects to the cluster as a follower, but cannot start replication because its WAL contains heartbeat records generated when it was the leader.
If the WAL trimming procedure fails, the node state changes to
NODE_ERROR.You can view the WAL trimming parameters in the
biha.statefile. For more information, see Section 26.3.7.2.Important
If the cluster fails during WAL trimming and WAL is changed incorrectly, it may lead to the loss of WAL records.
26.3.7.1. Monitoring the Rewind Results #
You can check the results of the pg_rewind operation, i.e. the rewind state of cluster nodes, in the rewind_state field of the biha.state file. The field contains the enum values, which are interpreted as follows:
Table 26.1. The Rewind State
| Value | Interpretation |
|---|---|
0 | The rewind is not required. |
1 | The instance is stopped, the biha.autorewind configuration parameter was enabled, the rewind will be performed after the instance restart. |
2 | The rewind failed. |
3 | The rewind was performed successfully. |
4 | The biha.autorewind configuration parameter was not enabled, and the rewind must be performed manually as described in Restoring the Node from the NODE_ERROR State. |
26.3.7.2. Monitoring WAL Trimming Parameters #
You can check the WAL trimming parameters of cluster nodes in the following fields of the biha.state file:
waltrim_state: current state of WAL trimming executionwaltrim_common_tli: timeline of the last common pointwaltrim_start_lsn: start of the WAL desynchronization range caused by redundant heartbeatswaltrim_end_lsn: end of the WAL desynchronization range caused by redundant heartbeats
26.3.8. Restoring the Node from the NODE_ERROR State #
Errors occurred in biha or Postgres Pro Standard instance processes listed below may cause the node failure, i.e. it will not be able to restart and will damage the WAL:
A rewind automatically performed by biha using pg_rewind if node timelines diverge.
The walreceiver process in case of timeline divergence. The follower node WAL may be partially rewritten by the WAL received from the leader node.
Note
If the NODE_ERROR state is caused by other issues, for example, replication slot overflow, you can fix the error root cause and call the biha.reset_node_error function to reset the NODE_ERROR state.
When the node goes into the NODE_ERROR state, the WAL recovery is paused and the walreceiver process is stopped. Nodes in the NODE_ERROR state are unable to vote during elections. Reading from such nodes is prohibited. Besides, the error details are saved to the biha.state file and checked upon the node restart, so the node will go into the same state when the biha-background-worker process is launched.
To restore the node from the NODE_ERROR state, take the following steps:
Save the most recent files from the
pg_waldirectory, since some of the files unique to this node will be rewritten by pg_rewind.To save biha configuration files, run pg_rewind with the
--bihaoption, for example:pg_rewind --biha --target-pgdata=
path_to_PGDATA_of_the_NODE_ERROR_node--source-server='user=biha_replication_user host=leader_hostport=leader_portdbname=postgres'Important
The
--bihaoption is essential for saving biha configuration files. Using pg_rewind in a BiHA cluster without--bihaoption may cause cluster configuration inconsistency.If the rewind has been successful, information about the
NODE_ERRORstate is deleted from thebiha.statefile. Besides, when you specify the connection string in the--source-serveroption of pg_rewind, it also automatically saves this string for the primary_conninfo configuration parameter in the postgresql.auto.conf file. This is important for the node to continue restoring after the restart and reach the consistency point, which is the number of the last record in the source server WAL at the time of the rewind.(Optional) If the node was offline for a long time, to prevent the risk of data corruption and obsolete data reads, set the flw_ro parameter of the restored node to
off.
26.3.9. Hanging Prevention Mechanism #
BiHA provides a special protection mechanism that helps to prevent node hanging and split-brain issues. The mechanism operates as follows:
If the biha process does not respond, when the watchdog_timeout value is reached, the node stops accepting queries and its state temporarily changes to
NODE_ERROR.Note
Queries from
pg_monitorand$BIHA_USERroles are not blocked.The following message in the log file informs about the problem: “The request cannot be processed because the BiHA extension is not responding”.
Depending on how soon the biha process recovers, the following happens:
If the biha process recovers quickly, the node returns to normal operation, i.e. continues accepting queries and changes its state back to the initial one.
If the biha process does not recover within the
watchdog_timeout * 5value, an attempt to send SIGKILL to the biha process is made during the next query. All backends are restarted and the node functionality is recovered.
26.3.10. Replication Configuration #
By default, BiHA clusters are asynchronous. However, BiHA allows you to create a cluster with quorum-based synchronous replication.
Quorum-based synchronous replication is enabled by setting the synchronous_standby_names parameter that specifies the list of synchronous standby names and the number of synchronous standbys (quorum) that transactions must wait for replies from with the ANY method. For more information, see Multiple Synchronous Standbys. The synchronous_commit parameter is used with the default value on.
For more information, see the following sections:
26.3.10.1. Synchronous Replication and the Referee #
There are a few points that need to be taken into account with regard to synchronous replication and the referee node. If the --mode option is set to referee, the referee does not participate in synchronous replication. When set to referee_with_wal, the node can synchronously receive data. This mode allows the cluster to continue to be available in the 2+1 configuration with --sync-standbys=1 if the follower node is down and the referee node starts confirming transactions for the leader node. The referee behavior depends on the synchronous_commit parameter value. Note that with this parameter set to remote_apply the referee does not confirm transactions.
26.3.10.2. Enabling Quorum-Based Synchronous Replication #
You can enable quorum-based synchronous replication either when initializing a BiHA cluster or later in the existing BiHA cluster.
Important
Enabling quorum-based synchronous replication in your BiHA cluster is irreversible. Once you enable quorum-based synchronous replication, you cannot make your BiHA cluster asynchronous again. However, you can exclude specific nodes from the list of synchronous standbys using the biha.remove_from_ssn function. The excluded node will run asynchronously.
You can enable quorum-based synchronous replication as follows:
When you create a BiHA cluster from scratch or convert the existing cluster, enable quorum-based synchronous replication using the --sync-standbys option of bihactl cluster init.
For example, when setting the --sync-standbys value to
1for a three-node cluster, synchronous_standby_names looks as follows:ANY 1 (biha_node_1,biha_node_2,biha_node_3)
To enable quorum-based synchronous replication in your existing asynchronous BiHA cluster, use the biha.set_sync_standbys function.
26.3.10.3. Managing Replication #
Important
To configure synchronous replication within a segment, ensure that you list only physical nodes in synchronous_standby_names.
You can manage replication in a BiHA cluster as follows:
To view the current value of the synchronous_standby_names parameter, use the biha.get_ssn function.
To modify the quorum of synchronous standbys, i.e. the value set for the
ANYmethod in the synchronous_standby_names parameter, use the biha.set_sync_standbys function. This is usually required after you change BiHA cluster composition by adding nodes with the bihactl node add command or removing nodes with the biha.remove_node function.To add a specific node to the list of synchronous standbys, use the biha.add_to_ssn function.
To add multiple nodes as the list of synchronous standbys, use the biha.set_ssn function.
To exclude a specific node from the list of synchronous standbys, use the biha.remove_from_ssn function. The excluded node will run asynchronously.
26.3.10.4. Relaxing Restrictions of Quorum-Based Synchronous Replication #
You can relax restrictions of quorum-based synchronous replication to allow the leader node to continue operation while some of the synchronous standbys are temporary unavailable. Enabling relaxed quorum-based synchronous replication means specifying the MIN field value of the synchronous_standby_names parameter, which is the minimum number of synchronous standbys that must be available for the leader node to continue operation. The synchronous_standby_gap parameter remains unchanged and keeps its default value of 0.
You can manage relaxed quorum-based synchronous replication in a BiHA cluster with quorum-based synchronous replication as follows:
To enable relaxed quorum-based synchronous replication when initializing a cluster with the bihactl cluster init command, specify the --sync-standbys-min option.
For example, when setting the --sync-standbys-min value to
0for a three-node cluster, synchronous_standby_names looks as follows:ANY 1 MIN 0 (biha_node_1,biha_node_2,biha_node_3)
To enable relaxed quorum-based synchronous replication in the existing cluster or modify the minimum number of quorum-based synchronous standbys, use the biha.set_sync_standbys_min function.
To disable relaxed quorum-based synchronous replication, set the minimum number of synchronous standbys to
-1using the biha.set_sync_standbys_min function.
26.3.10.5. Configuring Cascading Replication #
You can configure cascading replication when initializing a new BiHA cluster or GDBiHA cluster by means of bihactl and then modify cascading replication parameters as follows:
To limit the maximum number of replication connections to a particular node from any node within the BiHA or GDBiHA cluster, specify the value of the max_replicas configuration parameter using the biha.set_max_replicas function.
For example, in a three-node cluster consisting of two followers (
F1andF2) and the leader, setmax_replicasof the leader to1. In this case, if followerF1starts replication first, it will replicate from the leader. FollowerF2will establish cascading replication fromF1(assuming that the repl_pref_roles value ofF2containsF), because the connection limit of the leader is over.To set the node priority when selecting a replication source, specify the value of the priority configuration parameter using the biha.set_priority function.
For example, in a three-node cluster consisting of two followers (
F1andF2) and the leader, setpriorityof followerF1to10seconds and followerF2to20seconds. If both followers start searching for replication source simultaneously, followerF1connects to the leader first.To set preferred roles of a node for replication, specify the value of the repl_pref_roles configuration parameter using the biha.set_pref_roles function.
For example, if
repl_pref_rolesof followerF1is set toFL, the follower will first choose another follower as the replication source. If it fails, followerF1connects to the leader.Note
The no_wal_on_follower configuration parameter impacts replication in a cascading BiHA cluster. If a node does not receive WAL within the time set in
no_wal_on_follower, it starts searching for a new replication source as configured in repl_pref_roles.To prevent a node from replicating from specific nodes, set a list of prohibited replication sources in the deny_wal_sources using the biha.set_deny_wal_sources function. You can use this functionality to prohibit replication from nodes located in a specific data center or configure replication sources in a cascading cluster. Each node can have its own list of prohibited replication sources.
26.3.11. Logging #
BiHA logs messages sent by its components:
BiHA control channel: The control channel used to exchange service information between nodes. The control channel is managed by
BiHA Control Protocoland marked asBCPin the log.Node Controller: The biha core component responsible for the node operation logic and marked asNCin the log.Postgres Controller: The biha component required to manage and monitor Postgres Pro components, such as replication configuration, configuration parameters,walsenderandwalreceiverprocesses, etc.Postgres Controllerbrings Postgres Pro to the state required for BiHA.Postgres Controlleris marked asPGCin the log.Config Controller: The configuration module that manages node configuration (GUC andbiha.conf) and synchronizes it across cluster nodes.Config Controlleris marked asBCin the log.
You can determine the types of messages to be logged by setting the appropriate logging level. BiHA supports both standard Postgres Pro message severity levels and the extension logging levels.
Postgres Pro message severity levels are used by biha in the following cases:
When the biha process ends with an error (
ERRORandFATALlevels).When you call a core function that accepts a logging level as its argument.
biha logging levels are mapped to the Postgres Pro message severity levels. If you want messages of the required level to appear in the log, the value set for this level should correspond to the value in log_min_messages. You can configure biha logging levels by specifying the corresponding configuration parameters in the postgresql.biha.conf file.
The recommended configuration of logging levels looks as follows:
biha.BcpTransportWarn_log_level = WARNING biha.BcpTransportLog_log_level = LOG biha.BcpTransportDetails_log_level = DEBUG1 biha.BcpTransportDebug_log_level = DEBUG1 biha.NodeControllerLog_log_level = LOG biha.NodeControllerWarn_log_level = WARNING biha.NodeControllerDetails_log_level = DEBUG1 biha.NodeControllerDebug_log_level = DEBUG1
Note
This configuration displays only messages for biha.BcpTransportLog_log_level, biha.BcpTransportWarn_log_level, biha.NodeControllerLog_log_level, and biha.NodeControllerWarn_log_level logging levels. To view detailed and debug log messages, set the log_min_messages parameter to DEBUG1.
26.3.12. Callbacks #
A callback is an SQL function that notifies users or external services about events in the BiHA cluster, for example, about election of a new leader or change of cluster configuration. As a user, you create an SQL function and register it as a callback. Under certain conditions, the biha extension calls this function.
Timely alerting helps external services to provide proper reaction to events in the BiHA cluster. For example, after receiving information about the leader change, the proxy server redirects traffic to the new leader.
The following callback types are available:
Table 26.2. Callback Types
| Name | Description |
|---|---|
CANDIDATE_TO_LEADER | Called on the node elected as the new leader. Signature: my_callback() RETURNS void |
LEADER_CHANGE_STARTED | Called on all nodes when the old leader is not available, but the new leader is not yet elected. You can use this callback to fence the old leader. The callback is activated when the number of nodes reaches the nquorum value, and it becomes possible to hold elections. This callback is also called on all cluster nodes when the new leader is set manually using the biha.set_leader function. Important When you set the new leader by biha.set_leader, the old leader immediately restarts and the Signature: my_callback(id integer, host text, port integer) RETURNS void In this signature, biha passes the lost leader details: ID, host name, and node port number. |
LEADER_CHANGED | Called on every node when the BiHA cluster leader changes. Signature: my_callback(id integer, host text, port integer) RETURNS void In this signature, biha passes the new leader details: ID, host name, and node port number. |
LEADER_STATE_IS_RW | Called on the leader and other nodes when the leader changes its state to Signature: my_callback(id integer, host text, port integer) RETURNS void In this signature, biha passes to the callback the leader details: ID, host name, and node port number. |
LEADER_TO_FOLLOWER | Called on the old leader returned to the cluster after demotion. Signature: my_callback() RETURNS void |
NODE_ADDED | Called on every node when a new node is added to the BiHA cluster. Signature: my_callback(id integer, host text, port integer, mode integer) RETURNS void In this signature, biha passes to the callback the new node details, such as its host name, node port number, and operation mode: |
NODE_REMOVED | Called on every node when a node is removed from the BiHA cluster. Signature: my_callback(id integer) RETURNS void In this signature, biha passes to the callback the ID of the removed node. |
OFFERED_TO_LEADER | Called on the node manually set to leader when it is about to become the leader. Signature: my_callback() RETURNS void |
STATUS_CHANGED | Called on every node whenever values in the fields of the biha.status_v view change (except Note It is not recommended to execute other callbacks when using Signature: my_callback() RETURNS void |
TERM_CHANGED | Called on the node when its Signature: my_callback(old_term integer, new_term integer) RETURNS void In this signature, biha passes the old and the new |
26.3.12.1. Considerations and Limitations #
When an event happens, callbacks are executed in sequence. At this time, biha cannot change its state, for example, initiate elections.
If callback execution takes longer than the callbacks_timeout value, biha stops callback execution and continues normal operation.
In clusters with asynchronous replication, the biha.register_callback function does not wait for all nodes to receive callbacks. This may lead to a situation where callbacks are present on the leader, but not present on the follower as it lags behind.
Normally, callbacks are not executed on the referee in the
refereemode. However, if you have registered callbacks on the leader before adding the referee, callbacks may be executed on the referee and cannot be removed from it.It is not recommended to call BiHA functions during callback execution as other callbacks in the queue may fail.
Note
Do not call biha functions inside of a callback as this can cause unexpected behavior.
26.3.12.2. Managing Callbacks #
To manage callbacks, you can perform the following actions:
register one or several callbacks for a single event
view the list of registered callbacks
unregister callbacks
Registering Callbacks
Write an SQL function and then register it as a callback using biha.register_callback.
In this example, you create several SQL functions in PL/pgSQL and register them as different callback types.
Ensure that the leader node of your BiHA cluster is in the
LEADER_RWstate.On the leader node, use
psqland connect to thebiha_dbdatabase:postgres=# \c biha_db
Create the following callback functions:
-- log the node term change CREATE FUNCTION log_term_changed(old_term integer, new_term integer) RETURNS void AS $$ BEGIN RAISE LOG 'Callback: Term changed from % to %', old_term, new_term; END; $$ LANGUAGE plpgsql; -- log the election of the new leader CREATE FUNCTION log_leader_changed(id integer, host text, port integer) RETURNS void AS $$ BEGIN RAISE LOG 'Callback: New leader is % %:%', id, host, port; END; $$ LANGUAGE plpgsql; -- log that the leader was demoted CREATE FUNCTION log_leader_to_follower() RETURNS void AS $$ BEGIN RAISE LOG 'Callback: demote'; END; $$ LANGUAGE plpgsql;Register the created functions:
biha_db=# SELECT biha.register_callback('TERM_CHANGED', 'log_term_changed', 'biha_db'); biha_db=# SELECT biha.register_callback('LEADER_CHANGED', 'log_leader_changed', 'biha_db'); biha_db=# SELECT biha.register_callback('LEADER_TO_FOLLOWER', 'log_leader_to_follower', 'biha_db');You can also specify the user on which behalf the callbacks are executed or determine the order of callbacks execution. For more information, see the description of the biha.register_callback function.
Viewing Callbacks
Registered callbacks are added to the biha.callbacks table located in the biha_db database.
To view all registered callbacks:
On the leader node, use
psqland connect to thebiha_dbdatabase:postgres=# \c biha_db
Display the content of the
biha.callbackstable:biha_db=# SELECT * FROM biha.callbacks; 1 | log_term_changed 2 | log_leader_changed 3 | log_leader_to_follower (3 rows)
Unregistering Callbacks
An unregistered callback is deleted from the biha.callbacks table.
Ensure that the leader node of your BiHA cluster is in the
LEADER_RWstate.On the leader node, use
psqland connect to thebiha_dbdatabase:postgres=# \c biha_db
Get an ID of the callback that you want to unregister, for example,
log_leader_changed:biha_db=# SELECT id FROM biha.callbacks WHERE func = 'log_leader_changed';
The callback ID is returned, for example,
2.Unregister the callback:
biha_db=# SELECT biha.unregister_callback(2);
The callback is now unregistered.
26.3.13. Recovering from a Backup #
If your Postgres Pro Standard instance was restored from one of the nodes of the BiHA cluster to a separate node and/or using Point-in-Time Recovery (PITR), there must be no connection between the restored node and the operating BiHA cluster nodes. To prevent the connection, take the following steps on the restored node before you start it:
Remove the
include 'postgresql.biha.conf'include directive from the postgresql.conf configuration file.Ensure that biha is not present in the shared_preload_libraries of the postgresql.conf file and, if applicable, of the postgresql.auto.conf file.
If you want to add the restored node to the cluster, take the following steps:
On the restored node, manually configure streaming replication from the leader.
Synchronize the restored node with the leader.
Stop the restored node using pg_ctl:
pg_ctl stop -D
restored_node_PGDATA_directoryAdd the restored node to the cluster using the bihactl node add command with the --convert-standby option.
Start the restored node using pg_ctl:
pg_ctl start -D
restored_node_PGDATA_directory
26.3.14. Executing Custom Scripts with bihactl run #
BiHA supports executing custom scripts with the bihactl run command. Scripts are YAML files with SQL queries to a BiHA cluster. For example, you can create a script to monitor the cluster state and then execute it with bihactl run:
bihactl run scripts/monitoring.yaml
Scripts can be run either via CLI or as self-executable files with a shebang.
Note
Before executing scripts with bihactl run, configure authentication for biha_monitor_user.
For more information, refer to the subsections below.
26.3.14.1. Script Structure #
A script consists of three main sections: meta, settings, and scripts. For example:
meta:
description: "description"
versions:
biha: "1.7" # Minimum biha version the script operates with
format: "1.0" # File format version
settings:
sql:
users:
- name: user1
pgpassfile: ~/.pgpass
scripts:
- sql:
host: host1
port: 5433
user: user1
database: db1
query: "SELECT * FROM biha.status_v"
26.3.14.1.1. The settings Section #
Currently, you can use the settings section to describe authentication methods for multiple users.
Two authentication types are supported: password file and SSL certificate. The default method is the password file. The authentication method for a specific user is specified in the settings / sql / users section.
The password for a user is provided by specifying the path to the .pgpass file. If the passfile key is not specified, the file is searched for in the standard ~/.pgpass path. For example:
settings:
sql:
users:
- name: user1
pgpassfile: /tmp/.pgpass
For SSL certificate authentication, the following parameters are specified:
settings:
sql:
users:
- name: user1
ssl:
cert_file: /path/to/certificate.pem
key_file: /path/to/key.pem
root_cert_file: /path/to/ca_certificate.pem
ssl_mode: verify-full
26.3.14.1.2. SQL Query Specification #
The SQL query specification includes the following fields:
| Field | Description |
|---|---|
query | SQL query |
host | Node host (default: localhost) |
port | Connection port (default: 5432) |
user | Postgres Pro Standard user name (default: biha_monitor_user) |
database | Database name (default: biha_db) |
26.3.14.1.3. Script Examples #
This is a minimum script example. This script connects to biha_db via localhost:5432 as biha_monitor_user and searches for a user password in ~/.pgpass:
meta:
description: "description"
versions:
biha: "1.7"
format: "1.0"
scripts:
- sql:
query: select 1
The following example demonstrates all possible parameters. Note that ssl and pgpassfile are mutually exclusive, you must use only on of them.
meta:
description: "description"
versions:
biha: "1.7"
format: "1.0"
settings:
sql:
users:
- name: biha_replication_user
ssl:
cert_file: $HOME/ssl/biha.crt
key_file: $HOME/ssl/biha.key
root_ca_file: $HOME/ssl/rootCA.crt
ssl_mode: require
- name: user1
pgpassfile: ~/.pgpass
scripts:
- sql:
host: biha-db-1
port: 5431
database: db1
user: user2
query: select 1
- sql:
host: biha-db-2
port: 5432
database: db2
user: user1
query: select 2
26.3.14.2. Running Scripts Using a Shebang #
You can make the script executable directly by specifying the bihactl run command in the first line, for example:
#! bihactl run
meta:
description: "biha.config()"
scripts:
- sql:
query: SELECT id, name, mode FROM biha.config()
The shebang line can specify either the short form (bihactl run) or the full path to the executable:
#! /path/to/bihactl_run
To make the script file executable, use the following command:
chmod +xpath/to/script.yaml./path/to/script.yaml
26.3.15. Upgrade and Migration #
Depending on your current Postgres Pro Standard version, refer to one of the following sections:
To migrate from Postgres Pro Standard version 17.X to version 18.X, refer to Migration to Version 18.X.
To upgrade from Postgres Pro Standard version 18.X to the latest minor version of Postgres Pro Standard 18, refer to Upgrading the BiHA Cluster from Version 18.X to Version 18.6.
26.3.15.1. Migration to Version 18.X #
BiHA supports the following options for major migration of a BiHA cluster:
If interruption of your database operation is allowable in your organization, it is recommended to use the Migrating the BiHA Cluster to Version 18.X Using pg_upgrade procedure. This procedure is supported for migrations from Postgres Pro Standard version 17.X to version 18.X.
If you need to minimize downtime of your database operation, use the Migrating the BiHA Cluster to Version 18.X with Minimal Downtime procedure where special features of the bihactl utility are applied. This procedure is supported only for migrations from Postgres Pro Standard version 17.X to version 18.X.
26.3.15.1.1. Migrating the BiHA Cluster to Version 18.X Using pg_upgrade #
To upgrade your BiHA cluster from Postgres Pro Standard version 17.X to version 18.X, perform the following steps:
(Optional) Delete the
biha_replication_userrole using theDROP ROLEcommand:DROP ROLE biha_replication_user;
Deleting the
biha_replication_userrole is required if you want to set a new password for this role during the migration procedure, as bihactl does not support changing password for the existing role. When you convert the primary node into the leader in the following steps of this instruction, thebiha_replication_useris recreated, and you can set a new password using environment variables or the password file.If you keep your current
biha_replication_userrole, you can change the password manually using theALTER ROLEcommand.Stop all nodes of the cluster using the
pg_ctlcommand.Upgrade the nodes using the instructions described in the pg_upgrade utility documentation.
Add followers using one of the following ways:
If you have used rsync to upgrade your standby nodes, convert standbys into followers.
If you have not used rsync, add followers from scratch.
(Optional) To add the referee:
On the former referee node, remove the
PGDATAdirectory.
26.3.15.1.2. Migrating the BiHA Cluster to Version 18.X with Minimal Downtime #
Use this procedure to migrate your BiHA cluster from Postgres Pro Standard version 17.X to version 18.X if interruption of your database operation must be reduced to a minimum.
For clarity, this procedure refers to the current BiHA cluster you are migrating as “the old cluster” and the upgraded BiHA cluster as “the new cluster”.
This migration method is provided by special commands of the bihactl utility developed to automate migration steps. During migration, you create the new cluster leader on an additional server or convert an existing follower to the new cluster leader and then move followers from the old cluster to the new one. It allows your old cluster to continue operation and support high availability during the whole migration process, while the new cluster running Postgres Pro Standard 18.X receives all updates via logical replication and finally takes over workloads only when migration is complete and high availability is configured.
Important
Before you begin the migration, carefully read Prerequisites and follow them during the migration process.
It is highly recommended to perform this migration procedure in a test environment before using it for your production cluster.
All migration operations must be executed under the
postgresuser.
The migration procedure consists of the following steps:
Step 0: Examine the Prerequisites section and make all required preparations.
Step 1: Set up the new cluster leader on an additional server or by converting an existing follower.
Step 2: Move a follower from the old cluster to the new one.
Step 3: Finish the migration procedure and enable workloads on the new cluster.
Prerequisites
Ensure that all conditions listed in Prerequisites and Considerations are met.
On the old leader, create a user with privileges for creating subscriptions and using
pg_replication_origin_advance().You will later set this user as --subscriber-username.
For the old leader, fulfill the following:
Set the wal_level value to
logical.Set the nquorum value higher than the number of cluster nodes to ensure there is no switchover during migration.
Consider all logical replication restrictions during the whole migration process.
Restrict DCL and DDL operations during the whole migration process. Only DML operations, i.e. data change, are allowed on the old leader during migration process.
Ensure that primary keys are present in all tables being updated.
Ensure minimal workloads on the old leader.
Setting up the New Leader on the Additional Server
In this procedure, the new cluster leader is created on the additional server that you prepare in advance. Alternatively, you can set the new cluster leader by converting an existing follower.
When creating the new leader, the bihactl upgrade start command does the following:
Creates a follower running Postgres Pro Standard version 17.X.
Removes the follower from the old cluster leaving it as a physical replica running Postgres Pro Standard 17.X.
Converts the physical replica into a logical replica by means of pg_createsubscriber.
Upgrades the logical replica to Postgres Pro Standard 18.X.
Converts the logical replica running Postgres Pro Standard 18.X into the new cluster leader.
Note
After you execute bihactl upgrade start, the new leader does not accept any connections, except internal connections via Unix socket, until you finish migration using bihactl upgrade finish.
To set up the new leader:
Prepare an additional server that will be used to deploy the leader of the new cluster running Postgres Pro Standard 18.X.
The operating system and Postgres Pro Standard binaries installed on the additional server must be the same as those installed on the nodes of the old cluster.
Ensure that databases of your old cluster are accessible from the additional server you prepared.
If they are not accessible, configure access in the
pg_hba.biha.conffile of the old leader.On all old cluster nodes and the additional server, install Postgres Pro Standard 18.X.
On the old cluster leader, get the magic string:
SELECT biha.get_magic_string();
On the prepared additional server, execute the bihactl upgrade start command:
bihactl upgrade start \ --magic-string=magic_string_of_old_leader\ --new-leader-biha-port=new_leader_biha_port\ --new-leader-host=new_leader_host\ --new-leader-port=new_leader_port\ --old-bin=/path/to/binaries/of/version17\ --old-pgdata=PGDATA_version17\ --new-pgdata=PGDATA_version18\ --subscriber-username=usernameBoth
PGDATA_version17andPGDATA_version18directories must be empty.As a result of the command execution, the new leader is created with the service mode enabled, as well as with logical replication configured for all user databases of the old cluster.
Tip
The command output also includes the magic string. You can copy and save it now for the next migration steps.
Start the new leader using pg_ctl:
pg_ctl start -D
new_leader_PGDATA_directory-lnew_leader_log_fileVerify that the new leader is in the
LEADER_RWstate using the biha.status_v view:SELECT * FROM biha.status_v;
On the new leader, check the subscriptions using the pg_subscription catalog:
SELECT subname, subpublications FROM pg_subscription;
On the old leader, do the following:
Check the replication slots using the pg_replication_slots view:
SELECT slot_name, slot_type FROM pg_replication_slots;
Check the publications using the pg_publication catalog:
SELECT * FROM pg_publication;
Ensure there is no replication lag:
/path/to/binaries/of/version17/psql biha_db -qtAXc "SELECT sum(pg_wal_lsn_diff(pg_current_wal_lsn(), confirmed_flush_lsn)) AS lag_bytes FROM pg_replication_slots where slot_type = 'logical';"
Setting up the New Leader by Converting a Follower
In this procedure, an existing follower is converted to the new cluster leader. If you do not want to use a follower for migration, set up the new cluster leader on the additional server.
When creating the new leader, the bihactl upgrade start command does the following:
Removes the follower from the old cluster, leaving it as a physical replica running Postgres Pro Standard 17.X.
Converts the physical replica into a logical replica by means of pg_createsubscriber.
Upgrades the logical replica to Postgres Pro Standard 18.X.
Converts the logical replica running Postgres Pro Standard 18.X into the new cluster leader.
Note
After you execute bihactl upgrade start, the new leader does not accept any connections, except internal connections via Unix socket, until you finish migration using bihactl upgrade finish.
To set up the new leader:
On all old cluster nodes, including the follower you want to convert, install Postgres Pro Standard 18.X.
On the old cluster leader, get the magic string:
SELECT biha.get_magic_string();
On the follower that you want to convert to the new cluster leader, execute the bihactl upgrade start command:
bihactl upgrade start --magic-string=magic_string_of_old_leader\ --old-bin=/path/to/binaries/of/version17_of_existing_follower\ --old-pgdata=PGDATA_version17_of_existing_follower\ --new-pgdata=PGDATA_version18\ --subscriber-username=username\ --convertThe
PGDATA_version18directory must be empty.As a result of the command execution, the new leader is created with the service mode enabled, as well as with logical replication configured for all user databases of the old cluster.
Tip
The command output also includes the magic string. You can copy and save it now for the next migration steps.
Start the new leader using pg_ctl:
pg_ctl start -D
new_leader_PGDATA_directory-lnew_leader_log_fileVerify that the new leader is in the
LEADER_RWstate using the biha.status_v view:SELECT * FROM biha.status_v;
On the new leader, check the subscriptions using the pg_subscription catalog:
SELECT subname, subpublications FROM pg_subscription;
On the old leader, do the following:
Check the replication slots using the pg_replication_slots view:
SELECT slot_name, slot_type FROM pg_replication_slots;
Check the publications using the pg_publication catalog:
SELECT * FROM pg_publication;
Ensure there is no replication lag:
/path/to/binaries/of/version17/psql biha_db -qtAXc "SELECT sum(pg_wal_lsn_diff(pg_current_wal_lsn(), confirmed_flush_lsn)) AS lag_bytes FROM pg_replication_slots where slot_type = 'logical';"
Moving a Follower
Remove one of the followers from the old cluster and add it to the new cluster. Repeat this procedure to move several followers from the old cluster to the new one, to ensure the new cluster supports high availability after migration.
Important
For data safety reasons, it is not recommended to remove all followers from the old running cluster. You can keep one follower in the old running cluster until the end of migration, and then add a new follower to the new cluster manually.
When you move a follower, its Postgres Pro configuration parameters are copied from the new leader. Therefore, if there are any follower-specific Postgres Pro configuration parameters set on the follower, you must reconfigure them manually after moving.
To move a follower:
To ensure that the old cluster is operational after you remove a follower, decrease the
minnodes,sync_standbys, andsync_standbys_minvalues using the biha.set_minnodes, biha.set_sync_standbys, and biha.set_sync_standbys_min functions correspondingly.The values of
minnodes,sync_standbys, andsync_standbys_minmust always be lower than the total number of cluster nodes. You can check the current values using the biha.config function.(Optional) If you did not save it on the previous step, on the new cluster leader, get the magic string:
SELECT biha.get_magic_string();
On the follower that you want to move, execute the bihactl upgrade move command:
bihactl upgrade move \ --new-magic-string=
magic_string_of_new_leader\ --old-bin=/path/to/binaries/of/version17\ --new-pgdata=PGDATA_version18\ --old-pgdata=PGDATA_version17PGDATA_version17is thePGDATAdirectory of the old running follower.PGDATA_version18is designated for the new upgraded follower and must be empty.Start the moved follower using pg_ctl:
pg_ctl start -D
moved_follower_PGDATA_directory-lmoved_follower_log_fileCheck the new cluster status using the bihactl cluster status command.
Finishing Migration
Important
This step requires minimal downtime to reconfigure your application and client connections to target the new cluster and enable workloads on it.
Disable workloads on the old leader and wait for the new leader to complete data receipt via logical replication.
To ensure that the data is fully received, on the old leader, execute the following command:
/path/to/binaries/of/version17/psql biha_db -qtAXc "SELECT sum(pg_wal_lsn_diff(pg_current_wal_lsn(), confirmed_flush_lsn)) AS lag_bytes FROM pg_replication_slots where slot_type = 'logical';"The output must display the
0value forlag_bytes.On the new leader, execute the bihactl upgrade finish command:
bihactl upgrade finish \ --new-magic-string=
magic_string_of_new_leader\ --subscriber-username=usernameExecuting the command results in the following:
The state of the old leader changes to
LEADER_RO.The new leader exits the service mode and becomes available for write transactions.
Logical replication subscriptions are deleted from the new leader.
minnodes,sync_standbys, andsync_standbys_minreturn to their initial values set on the old leader before the migration.
On the old leader, update sequence values for all databases using the following command:
/path/to/binaries/of/version17/psql biha_db -qtAXc "SELECT 'SELECT setval(' || quote_literal(sequencename) || ', ' || last_value || ', true);' FROM pg_sequences;"Copy the command output from the previous step and execute it on the new leader.
Reconfigure your application and client connections to target the new cluster.
On the new cluster, resume workloads that you disabled on the old leader at the beginning of this procedure.
26.3.15.2. Upgrading the BiHA Cluster from Version 18.X to Version 18.6 #
Use this procedure to upgrade from Postgres Pro Standard version 18.X to version 18.6.
Stop one of the followers using the pg_ctl command.
Upgrade the follower.
Start the follower using the pg_ctl command.
Promote the upgraded follower using the biha.set_leader function.
Stop, upgrade, and start the remaining followers and the old leader.
Promote the old leader node using the biha.set_leader function.
On the leader, update the extension using the following command:
ALTER EXTENSION biha UPDATE;
Important
There is no support for updating the version of the biha extension on the referee in the
refereemode. Delete the referee using the biha.remove_node function, delete itsPGDATAdirectory, and then create the new referee from scratch.For more information about changes of extension versions, refer to release notes.
26.3.16. Disabling biha #
You can temporarily disable the biha extension in your cluster. The disabling procedure differs depending of the node role.
Disabling biha on the Follower
Important
When you disable biha on the follower, physical replication stops.
Stop the follower using pg_ctl.
On the leader in the
LEADER_RWstate, call the biha.remove_node function to exclude the node where you want to disable biha from the cluster:biha_db=# SELECT biha.remove_node(
id);On the follower node, do the following:
Remove the
include 'postgresql.biha.conf'include directive from the postgresql.conf configuration file.Remove biha from the shared_preload_libraries of the postgresql.conf file and, if applicable, of the postgresql.auto.conf file.
Start the follower using pg_ctl.
Disabling biha on the Leader
Remove the
include 'postgresql.biha.conf'include directive from the postgresql.conf configuration file.Remove biha from the shared_preload_libraries of the postgresql.conf file and, if applicable, of the postgresql.auto.conf file.
Stop and start the leader using pg_ctl.
26.3.17. Removing biha #
You can completely remove the biha extension and permanently disable BiHA functionality in your cluster. You can either keep your cluster with a standard primary-standby configuration or separate your cluster into standalone nodes.
Removing biha and Keeping a Standard Primary-Standby Cluster
You can remove the BiHA functionality and keep your cluster with a standard primary-standby configuration and configured replication.
On every follower, get and save the current values of the primary_conninfo and primary_slot_name configuration parameters:
SHOW primary_conninfo; SHOW primary_slot_name;
On the leader, execute the
DROP EXTENSIONcommand. It must be executed on the leader in theLEADER_RWstate and from thebiha_dbdatabase:biha_db=# DROP EXTENSION biha;
Stop all cluster nodes using pg_ctl.
On all cluster nodes, do the following:
Remove the
include 'postgresql.biha.conf'include directive from the postgresql.conf configuration file.Remove biha from shared_preload_libraries of the postgresql.conf file and, if applicable, of the postgresql.auto.conf file.
Remove all files from the
pg_bihadirectory.
On every follower, add primary_conninfo and primary_slot_name configuration parameters to the postgresql.conf file with the values you saved at the beginning of this procedure.
Start all cluster nodes using pg_ctl.
Removing biha and Separating the Cluster into Standalone Nodes
You can remove the BiHA functionality and separate your cluster into standalone nodes.
Stop all cluster nodes using pg_ctl.
On all cluster nodes, do the following:
Remove the
include 'postgresql.biha.conf'include directive from the postgresql.conf configuration file.Remove biha from the shared_preload_libraries of the postgresql.conf file and, if applicable, of the postgresql.auto.conf file.
Remove all files from the
pg_bihadirectory.
On every follower, execute the
pg_ctl promotecommand:pg_ctl promote -D
/path/to/follower/pgdataStart all nodes using pg_ctl.