27.4. Справка по расширению biha #
biha — расширение Postgres Pro для управления BiHA-кластером.
В этом разделе содержится информация о параметрах конфигурации, функциях и представлениях расширения biha.
27.4.1. Параметры конфигурации #
Расширение biha поддерживает ряд описанных ниже конфигурационных параметров, специфичных для BiHA-кластера.
27.4.1.1. Конфигурирование кластера #
Важно
При настройке параметров конфигурации кластера нужно обязательно обеспечить надёжность сети, чтобы изменения затронули все узлы кластера без возникновения ошибок.
Не рекомендуется изменять какие-либо параметры конфигурации кластера, пока один из узлов находится в состоянии
NODE_ERROR, так как на этом узле изменения могут не примениться.
biha.autorewind(boolean) #Необязательный параметр, который управляет политикой автоматической синхронизации для узла, в отношении которого должен быть выполнен
pg_rewind. Например, для старого лидера при его синхронизации с новым лидером. При значении по умолчанию —false— автоматическая синхронизация не выполняется. Если установлено значениеtrue, автоматическая синхронизация выполняется после ошибки, которая обычно приводит к переходу узла в состояниеNODE_ERROR.За подробной информацией обратитесь к Автоматическая синхронизация кластера после аварийного переключения.
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_max_lost* biha.heartbeat_send_period, для определения доступности других узлов. Например, если Узел A не получает сообщения о контроле состояния от Узла B в течение вышеупомянутого тайм-аута, состояние Узла B изменится наUNKNOWNв представлении biha.status_v Узла A, что будет означать, что Узел A считает Узел B недоступным. Лидер в состоянииLEADER_RWдополнительно использует тайм-аут, указанный в параметре biha.no_wal_on_follower.biha.heartbeat_send_period(integer) #Указывает частоту отправки сообщений о контроле состояния в миллисекундах. Этот параметр может задаваться функцией biha.set_heartbeat_send_period. Значение по умолчанию —
1000.Узлы во всех состояниях используют значение тайм-аута сообщений о контроле состояния, который рассчитывается как biha.heartbeat_max_lost *
biha.heartbeat_send_period, для определения доступности других узлов. Например, если Узел A не получает сообщения о контроле состояния от Узла B в течение вышеупомянутого тайм-аута, состояние Узла B изменится наUNKNOWNв представлении biha.status_v Узла A, что будет означать, что Узел A считает Узел B недоступным. Лидер в состоянииLEADER_RWдополнительно использует тайм-аут, указанный в параметре biha.no_wal_on_follower.biha.host(text) #Указывает адрес узла кластера. Этот параметр не рекомендуется изменять.
biha.id(integer) #Указывает идентификатор узла отказоустойчивого кластера. Этот параметр уникален для каждого узла. Этот параметр не рекомендуется изменять.
biha.minnodes(integer) #Указывает минимальное число работающих узлов, при котором лидер будет открыт для пишущих транзакций. Этот параметр может быть задан с помощью функции biha.set_minnodes. Если не задать параметр --minnodes в команде
bihactlinit, значение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.BiHA использует этот параметр конфигурации для следующих целей:
Когда вы вручную назначаете узел-последователь в качестве нового лидера с помощью функции biha.set_leader, состояние последователя изменяется на
FOLLOWER_OFFERED. В этом состоянии последователь с помощью параметраbiha.no_wal_on_followerопределяет, что пора прекратить ожидание записей WAL от текущего лидера и можно становиться новым лидером.Последователь в состоянии
FOLLOWER_OFFEREDпроверяет, обновилась ли его позиция WAL. Обновление позиции WAL подтверждает, что последователь продолжает получать данные репликации от лидера. Если последователь не получает записи WAL дольше, чем задано в параметреbiha.no_wal_on_follower, состояние последователя изменяется наLEADER_RO. В этом случае в журнале появляется следующее сообщение: «Timed out waiting for new WAL records from current leader» (Истёк тайм-аут ожидания записей WAL от текущего лидера).Лидер в состоянии
LEADER_RWиспользует параметрbiha.no_wal_on_followerв связке со значением тайм-аута сообщений о контроле состояния (который рассчитывается как biha.heartbeat_max_lost * biha.heartbeat_send_period) для определения доступности других узлов.Лидер проверяет позиции слотов репликации других узлов. Если позиция слота репликации узла обновляется, это означает, что узел получает данные репликации от лидера и доступен. Если лидер не получает от узла сообщения о контроле состояния в течение вышеупомянутого тайм-аута, а позиция слота репликации узла не меняется в течение тайм-аута, заданного в
biha.no_wal_on_follower, лидер будет считать узел недоступным, а состояние узла изменится наUNKNOWNв представлении biha.status_v лидера.
biha.node_priority(integer) #Устанавливает приоритет узла в кластере с синхронной репликацией, в секундах. Значение определяет тайм-аут, по истечении которого узел предложит себя в качестве кандидата на выборах. Нулевое значение означает самый высокий приоритет. Значение по умолчанию —
-1, означающее, что параметр игнорируется.Важно
Чтобы обеспечить корректную работу параметра, установите значение параметра --sync-standbys на единицу меньше общего количества узлов кластера.
biha.nquorum(integer) #Указывает минимальное число узлов, которые должны проголосовать за нового лидера при отказе текущего лидера. Этот параметр можно задать с помощью функции biha.set_nquorum.
Устанавливая это значение, принимайте во внимания возможный риск разделения кластера. Рекомендуется использовать следующую формулу: (
общее_число_узлов+ 1)/2. Например, если в кластере 3 узла, значениеnquorumдолжно быть 2.Если на узле для параметра biha.can_vote установлено значение
false, такой узел игнорируется.biha.port(integer) #Указывает порт, используемый для обмена служебной информацией между узлами. Этот параметр необходим, чтобы установить соединение с кластером. Этот параметр не рекомендуется изменять.
biha.use_ssl(boolean) #Указывает, будет ли использоваться защищённый режим передачи служебной информации между узлами кластера по протоколу SSL/TLS управляющего канала biha. Этот параметр не рекомендуется изменять.
biha.autowaltrim(boolean) #Управляет политикой выравнивания WAL в рамках одного узла. Если задано значение
true(по умолчанию), BiHA автоматически планирует и выполняет процедуру выравнивания WAL по возможности. Если задано значениеfalse, процедура выравнивания WAL не выполняется, а синхронизация кластера проводится с помощью pg_rewind.За подробной информацией обратитесь к Автоматическая синхронизация кластера после аварийного переключения.
27.4.1.2. Настройка аутентификации по SSL #
Перечисленные ниже параметры конфигурации относятся к SSL-аутентификации для роли biha_replication_user. За подробной информацией о настройке аутентификации по SSL обратитесь к Настройка SSL для аутентификации пользователей.
biha.user_biha_cert(text) #Указывает путь к публичному SSL-сертификату для аутентификации роли
biha_replication_user.biha.user_biha_key(text) #Указывает путь к закрытому SSL-ключу для аутентификации роли
biha_replication_user.biha.ssl_mode(text) #Указывает политику аутентификации для роли
biha_replication_user. Поддерживаются следующие режимы:verify-full(по умолчанию)requireverify-ca
За подробной информацией о режимах обратитесь к sslmode.
27.4.1.3. Уровни протоколирования 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. Функции #
Все перечисленные ниже функции необходимо вызывать из базы данных biha_db, например:
psql biha_db -c "SELECT biha.set_leader(2)"
27.4.2.1. Состав кластера #
biha.set_leader (id integer) returns boolean#Устанавливает лидера вручную. Рекомендуется вызывать эту функцию на том узле, который вы собираетесь сделать лидером.
Примечание
Не рекомендуется вызывать функцию
biha.set_leaderна текущем лидере. Если вызвать функцию на текущем лидере в состоянииLEADER_RW, в случае успешного запроса на переключение может случиться так, что результат запроса не успеет отправиться клиенту до начала перезагрузки текущего лидера для понижения.biha.remove_node (id integer) returns boolean#Удаляет узел из кластера. Перед удалением узел необходимо остановить. Данную функцию можно вызвать только на узле-лидере.
27.4.2.2. Общая конфигурация кластера #
Следующие функции используются для изменения параметров конфигурации, значения которых должны быть одинаковыми на всех узлах кластера. Эти функции необходимо вызывать только на лидере. Изменения будут применены на всех узлах.
Перезапуск узлов кластера не требуется, чтобы после вызова функции изменения вступили в силу, если в описании функции явно не указано обратное.
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.
27.4.2.3. Репликация #
Следующие функции используются для настройки репликации и управления ею.
biha.add_to_ssn (id integer) returns boolean#Примечание
Эту функцию можно вызвать, только если включена кворумная синхронная репликация.
Добавляет узел с указанным идентификатором в список синхронных резервных узлов параметра synchronous_standby_names. Необходимо указывать узел, имени которого ещё нет в списке.
biha.get_ssn() returns varchar#Отображает текущее значение параметра synchronous_standby_names.
biha.remove_from_ssn (id integer) returns boolean#Примечание
Эту функцию можно вызвать, только если включена кворумная синхронная репликация.
Удаляет узел с указанным идентификатором из списка синхронных резервных узлов параметра synchronous_standby_names. Необходимо указать узел, имя которого уже есть в списке.
biha.set_ssn (VARIADIC ids integer) returns boolean#Примечание
Эту функцию можно вызвать, только если включена кворумная синхронная репликация.
Устанавливает узлы с идентификаторами, указанными в массиве
ids, в качестве списка синхронных резервных узлов параметра synchronous_standby_names.biha.set_sync_standbys (integer) returns boolean#Включает кворумную синхронную репликацию, устанавливая параметр synchronous_standby_names и указывая число синхронных резервных узлов (кворум) с методом
ANY. Значение должно быть положительным, выше значения поляMINпараметра synchronous_standby_names (если оно задано) и не должно превышать число последователей без учёта рефери. За подробной информацией обратитесь к Настройка репликации.biha.set_sync_standbys_min (integer) returns boolean#Примечание
Эту функцию можно вызвать, только если включена кворумная синхронная репликация.
Задаёт значение поля
MINпараметра synchronous_standby_names, т.е. минимальное число синхронных резервных узлов, которые должны быть доступны, чтобы лидер продолжал работать.С помощью этой функции можно также управлять нестрогой кворумной синхронной репликацией. Чтобы отключить нестрогую кворумную синхронную репликацию, задайте значение
-1.
27.4.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,mode.biha.error_details () returns setof record#Возвращает описание причины, по которой узел перешёл в состояние
NODE_ERROR. Возвращаемая запись содержит тип ошибки, подробную информацию о ней, место возникновения с указаниемbegin_lsn,end_lsnи идентификаторов текущей и следующей линии времени, а такжеreplay_lsn.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.5. Управление функциями-обработчиками #
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.6. Прочие функции #
biha.get_magic_string () returns string#Генерирует «магическую» строку для узла кластера.
biha.reset_node_error () returns boolean#Сбрасывает состояние
NODE_ERRORна узле. Используйте эту функцию после того, как устранена причина перехода узла в состояниеNODE_ERROR. За подробной информацией обратитесь к разделу Восстановление узла из состояния NODE_ERROR.
27.4.3. Представления #
Чтобы обращаться к перечисленным ниже представлениям, необходимо подключиться к базе данных biha_db.
27.4.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.3.2. biha.status_v #
В этом представлении показывается состояние узлов в кластере.
Таблица 27.5. Представление biha.status_v
| Имя столбца | Описание |
|---|---|
id | Идентификатор узла. |
leader_id | Идентификатор узла-лидера. |
term | Поколение узла. Используется при голосовании по выбору нового узла-лидера. Тип данных — integer. |
online | Показывает, подключён ли узел в сети. Тип данных — boolean (t или f). |
state | Состояние узла. В этом столбце может отображаться одно из следующих значений:
|
last_known_state | Последнее известное состояние узла. |
since_last_hb | Время, прошедшее с момента получения последнего сообщения о контроле состояния. Тип данных — interval. |