27.4. Справка #

27.4.1. bihactl #

bihactl — это утилита командной строки, которая позволяет создать BiHA-кластер, изменять его состав, а также отслеживать статус и версию кластера.

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

27.4.2. biha #

biha — расширение Postgres Pro для управления BiHA-кластером.

В этом разделе содержится информация о параметрах конфигурации, функциях и представлениях расширения biha.

27.4.2.1. Параметры конфигурации #

Расширение biha поддерживает несколько конфигурационных параметров, специфичных для BiHA-кластера. Помимо этого, biha использует следующие параметры Postgres Pro:

27.4.2.1.1. Конфигурирование кластера #

Важно

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

biha.autorewind (boolean) #

Необязательный параметр, который управляет политикой автоматической синхронизации для узла, в отношении которого должен быть выполнен pg_rewind. Например, для старого лидера при его синхронизации с новым лидером. При значении по умолчанию — false — автоматическая синхронизация не выполняется. Если установлено значение true, автоматическая синхронизация выполняется после ошибки, которая обычно приводит к переходу узла в состояние NODE_ERROR. Автоматическая синхронизация выполняется, если она может успешно завершиться, то есть предварительный запуск pg_rewind с параметром --dry-run прошёл успешно. При неудачной автоматической синхронизации узел переходит в состояние NODE_ERROR. В этом случае фактическое состояние синхронизации узла можно найти в файле biha.state, как описано в Подразделе 27.3.6. Обратите внимание, что синхронизация может привести к потере некоторых записей WAL узла.

biha.callbacks_timeout (integer) #

Задаёт время исполнения всех функций-обработчиков для одного события в миллисекундах. Значение по умолчанию — 10000 (10 секунд). Минимальное значение — 1000 (1 секунда).

Значение параметра biha.callbacks_timeout может различаться для разных узлов. Изменение параметра на лидере не изменяет его на последователях.

biha.can_be_leader (boolean) #

Определяет возможность узла стать лидером. Значение по умолчанию — true. Если задано значение false, узел не может предлагать себя в качестве кандидата на выборах лидера.

Самый большой объём WAL может быть на том узле, который не может стать лидером. В этой ситуации при необходимости выборов другие узлы, которые могут предлагать себя в качестве кандидатов в лидеры, попытаются получить недостающие данные с этого узла. В случае успеха один из этих узлов станет лидером. Если данные получить не удалось, на узле, который не может стать лидером, запустится процесс автоматической синхронизации. Если параметр biha.autorewind не включён, состояние этого узла изменится на NODE_ERROR.

biha.can_vote (boolean) #

Определяет возможность узла голосовать. Значение по умолчанию — true. Если задать значение false, узел не сможет принимать участие в голосовании, а также не сможет предлагать себя в качестве кандидата в лидеры.

biha.flw_ro (boolean) #

Определяет доступность последователя для операций на чтение. Если задано значение off, чтение с этого последователя запрещено. Значение по умолчанию — on.

biha.heartbeat_max_lost (integer) #

Указывает максимальное число сообщений о контроле состояния, которые можно не получить до того, как узел будет считаться недоступным. Этот параметр может задаваться функцией biha.set_heartbeat_max_lost. Значение по умолчанию — 10.

biha.heartbeat_send_period (integer) #

Указывает частоту отправки сообщений о контроле состояния в миллисекундах. Этот параметр может задаваться функцией biha.set_heartbeat_send_period. Значение по умолчанию — 1000.

biha.host (text) #

Указывает адрес узла кластера. Этот параметр уникален для каждого узла. Для первого узла он задаётся при инициализации кластера, для остальных узлов — при добавлении к кластеру. Этот параметр не рекомендуется изменять.

biha.id (integer) #

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

biha.minnodes (integer) #

Указывает минимальное число работающих узлов, при котором лидер будет открыт для пишущих транзакций. Этот параметр может быть задан с помощью функции biha.set_minnodes. Если не задать параметр --minnodes в команде bihactl init, значение biha.minnodes будет равно значению biha.nquorum.

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

Если на узле для параметра biha.can_vote установлено значение false, такой узел игнорируется.

biha.no_wal_on_follower (integer) #

Указывает тайм-аут продвижения слота репликации в миллисекундах. Этот параметр может задаваться функцией biha.set_no_wal_on_follower. Значение по умолчанию — 20000.

При достижении тайм-аута на последователе лидер замечает, что последователь не получает WAL. Если при этом превышается значение biha.heartbeat_max_lost *biha.heartbeat_send_period, лидер станет считать последователя недоступным.

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

biha.node_priority (integer) #

Устанавливает приоритет узла в синхронном кластере в секундах. Значение определяет тайм-аут, по достижении которого узел предложит себя в качестве кандидата на выборах. Нулевое значение означает самый высокий приоритет. Значение по умолчанию — -1, что означает, что параметр игнорируется.

Кластер считается синхронным, если все его узлы синхронны, то есть все узлы кластера перечислены в параметре synchronous_standby_names. В асинхронных кластерах параметр игнорируется.

biha.nquorum (integer) #

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

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

Если на узле для параметра biha.can_vote установлено значение false, такой узел игнорируется.

biha.port (integer) #

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

biha.sync_standbys_min (integer) #

Задаёт минимальное количество синхронных последователей, которые должны быть доступны, чтобы лидер продолжал работу. Параметр можно задать с помощью функции biha.set_sync_standbys_min. Значение должно быть ниже, чем --sync-standbys, и не может быть отрицательным. Значение по умолчанию — -1, что означает, что параметр игнорируется. Если параметр не задан, BiHA-кластер работает в соответствии с ограничениями синхронной репликации по умолчанию, то есть лидер будет оставаться недоступным для операций на запись, пока все последователи не догонят его текущее состояние.

Примечание

И параметр biha.sync_standbys_min, и функция biha.set_sync_standbys_min будут работать, только если при инициализации BiHA-кластера командой bihactl init был задан параметр --sync-standbys-min.

27.4.2.1.2. Уровни протоколирования biha #
biha.BihaLog_log_level (enum) #

Задаёт уровень протоколирования для предоставления общей информации о работе компонентов biha. Значение по умолчанию — LOG.

biha.BcpTransportDebug_log_level (enum) #

Задаёт уровень протоколирования для предоставления отладочной информации о работе канала управления. Значение по умолчанию — DEBUG4.

biha.BcpTransportDetails_log_level (enum) #

Задаёт уровень протоколирования для предоставления подробной информации о работе канала управления. Значение по умолчанию — DEBUG4.

biha.BcpTransportLog_log_level (enum) #

Задаёт уровень протоколирования для предоставления общей информации о работе канала управления. Значение по умолчанию — DEBUG4.

biha.BcpTransportWarn_log_level (enum) #

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

biha.NodeControllerDebug_log_level (enum) #

Задаёт уровень протоколирования для предоставления отладочной информации о работе контроллера узла. Значение по умолчанию — DEBUG4.

biha.NodeControllerDetails_log_level (enum) #

Задаёт уровень протоколирования для предоставления подробной информации о работе контроллера узла. Значение по умолчанию — DEBUG4.

biha.NodeControllerLog_log_level (enum) #

Задаёт уровень протоколирования для предоставления общей информации о работе контроллера узла. Значение по умолчанию — DEBUG4.

biha.NodeControllerWarn_log_level (enum) #

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

27.4.2.2. Функции #

Все перечисленные ниже функции следует вызывать из базы данных biha_db, например:

psql biha_db -c "select biha.set_leader(2)"
27.4.2.2.1. Генерирование «‎‎магической» строки #
biha.get_magic_string () returns string #

Генерирует «‎‎магическую» строку для узла кластера.

27.4.2.2.2. Удаление узла кластера #
biha.remove_node (id integer) returns boolean #

Удаляет узел из кластера. Перед удалением узел необходимо остановить. Данную функцию можно вызвать только на узле-лидере.

27.4.2.2.3. Установка лидера вручную #
biha.set_leader (id integer) returns boolean #

Устанавливает лидера вручную. Рекомендуется вызывать эту функцию на том узле, который вы собираетесь сделать лидером.

Примечание

Не рекомендуется вызывать функцию biha.set_leader на текущем лидере. Если вызвать функцию на текущем лидере в состоянии LEADER_RW, в случае успешного запроса на переключение может случиться так, что результат запроса не успеет отправиться клиенту до начала перезагрузки текущего лидера для понижения.

27.4.2.2.4. Конфигурирование кластера #
biha.config () returns setof record #

Возвращает значения конфигурации кластера: id, term, nquorum, minnodes, heartbeat_send_period, heartbeat_max_lost, no_wal_on_follower, sync_standbys_min, priority, can_be_leader, can_vote.

biha.set_heartbeat_max_lost (integer) returns boolean #

Задаёт значение параметра biha.heartbeat_max_lost. Эту функцию можно вызвать только с лидера, при этом она изменяет параметр на всех узлах. Чтобы изменения вступили в силу, перезапуск кластера не требуется.

biha.set_heartbeat_send_period (integer) returns boolean #

Задаёт значение параметра biha.heartbeat_send_period в миллисекундах. Эту функцию можно вызвать только с лидера, при этом она изменяет параметр на всех узлах. Чтобы изменения вступили в силу, перезапуск кластера не требуется.

biha.set_no_wal_on_follower (integer) returns boolean #

Задаёт значение параметра biha.no_wal_on_follower в миллисекундах. Эту функцию можно вызвать только с лидера, при этом она изменяет параметр на всех узлах. Чтобы изменения вступили в силу, перезапуск кластера не требуется.

biha.set_minnodes (integer) returns boolean #

Задаёт значение параметра biha.minnodes. Эту функцию можно вызвать только с лидера, при этом она изменяет параметр на всех узлах. Чтобы изменения вступили в силу, перезапуск кластера не требуется.

biha.set_nquorum (integer) returns boolean #

Задаёт значение параметра biha.nquorum. Эту функцию можно вызвать только с лидера, при этом она изменяет параметр на всех узлах. Чтобы изменения вступили в силу, перезапуск кластера не требуется.

biha.set_nquorum_and_minnodes (integer, integer) returns boolean #

Задаёт значения параметров biha.nquorum и biha.minnodes. Эту функцию можно вызвать только с лидера, при этом она изменяет параметры на всех узлах. Чтобы изменения вступили в силу, перезапуск кластера не требуется.

biha.set_sync_standbys_min (integer) returns boolean #

Задаёт значение параметра biha.sync_standbys_min и, если необходимо, соответствующим образом изменяет поле MIN параметра synchronous_standby_names. Эту функцию можно вызвать только с лидера, при этом она изменяет параметр на всех узлах. Чтобы изменения вступили в силу, перезапуск кластера не требуется.

Примечание

И параметр biha.sync_standbys_min, и функция biha.set_sync_standbys_min будут работать, если при инициализации BiHA-кластера командой bihactl init был задан параметр --sync-standbys-min.

27.4.2.2.5. Мониторинг кластера #
biha.nodes () returns setof record #

Определяет представление biha.nodes_v, подробно описанное в biha.nodes_v.

biha.status () returns setof record #

Определяет представление biha.status_v, подробно описанное в biha.status_v. Если узел не отвечает при попытке показать представление, попробуйте выполнить тот же запрос на любом другом узле, чтобы узнать фактическое состояние узлов кластера.

27.4.2.2.6. Состояние NODE_ERROR #
biha.error_details () returns setof record #

Возвращает описание причины, по которой узел перешёл в состояние NODE_ERROR. Возвращаемая запись содержит тип ошибки, подробную информацию о ней, место возникновения с указанием begin_lsn, end_lsn и идентификаторов текущей и следующей линии времени, а также replay_lsn.

27.4.2.2.7. Управление функциями-обработчиками #
biha.register_callback (event text, func text, database text, executor text, priority integer) returns integer #

Добавляет новый обработчик и возвращает его уникальный идентификатор. Функцию можно вызвать только на лидере в состоянии LEADER_RW. Новый обработчик будет реплицирован на последователей.

Примечание

Со стороны biha нет проверки наличия функции func в базе данных database. Если указанная функция не существует, исполнение обработчика завершится ошибкой.

Пример использования biha.register_callback см. в Регистрация функций-обработчиков.

Таблица 27.3. Определения переменных

ИмяТипОписание
eventtextСобытие в BiHA-кластере, которое запускает функцию-обработчик. Подробнее о событиях и соответствующих типах функций-обработчиков читайте в Типы обработчиков.
functextНазвание SQL-функции, которую расширение biha исполняет при наступлении события event. Функция должна находиться в базе данных database, иначе она не будет исполнена.
databasetextБаза данных, в которой исполняется функция func.
executortext

Пользователь, от имени которого исполняется функция func. Это необязательный параметр. Значение по умолчанию — biha_callbacks_user.

priorityintegerЧем ниже значение, тем раньше исполнится обработчик. Это необязательный параметр. Значение по умолчанию — 0.

biha.unregister_callback(callback_id) #

Удаляет обработчик. Функцию можно вызвать только на лидере в состоянии LEADER_RW. Пример использования функции biha.unregister_callback см. в разделе Отмена регистрации функции-обработчика.

27.4.2.3. Представления #

27.4.2.3.1. biha.nodes_v #

В этом представлении показывается состояние подключения узлов в кластере. Для узла, на котором выполняется запрос для представления, следующие столбцы содержат NULL: state, since_conn_start, conn_count.

Таблица 27.4. Представление biha.nodes_v

Имя столбцаОписание
idИдентификатор узла.
hostАдрес узла.
portПорт узла.
stateСостояние подключения узла. В этом столбце может отображаться одно из следующих значений: ACTIVE, CONNECTING, IDLE или INIT.
since_conn_startВремя, прошедшее с момента подключения узла к сети.
conn_countСколько раз узел подключался к сети с момента запуска кластера.

27.4.2.3.2. biha.status_v #

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

Таблица 27.5. Представление biha.status_v

Имя столбцаОписание
idИдентификатор узла.
leader_idИдентификатор узла-лидера.
termПоколение узла. Используется при голосовании по выбору нового узла-лидера.
onlineПоказывает подключён ли узел к сети.
state

Состояние узла. В этом столбце может отображаться одно из следующих значений:

  • PRESTARTUP — начальное состояние узла при запуске BiHA-кластера. Узел отправляет сообщения о контроле состояния и запускает pg_rewind, если это было запланировано. В других случаях узел переходит в состояние STARTUP.

  • STARTUP — узел ожидает, пока процесс запуска Postgres Pro достигнет точки согласованности.

  • CSTATE_FORMING — узел получает и отправляет сообщения о контроле состояния, чтобы определить, в какое состояние он должен перейти.

  • LEADER_RO — узел является лидером, доступным только для операций чтения.

  • LEADER_RW — узел является лидером, доступным для операций на чтение и запись.

  • FOLLOWER — узел является последователем, т.е. репликой лидера. Если biha.can_be_leader и biha.can_vote имеют значение true, последователь может быть избран новым лидером.

  • FOLLOWER_OFFERED — узел был вручную назначен новым лидером с помощью функции biha.set_leader.

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

  • REFEREE — узел является рефери кластера. Это единое состояние для режимов referee и referee_with_wal.

  • NODE_ERROR — узел в нерабочем состоянии из-за ошибки. Когда узел в состоянии NODE_ERROR, чтение с этого узла запрещено. Чтобы получить больше информации об ошибке, используйте функцию biha.error_details. Чтобы восстановить дефектный узел, см. Подраздел 27.3.5.

  • UNKNOWN — узел недоступен для текущего узла.

last_known_stateПоследнее известное состояние узла.
since_last_hbВремя, прошедшее с момента получения последнего сообщения о контроле состояния.