Настройка обработчика ошибок
примечание
В целях отказоустойчивости при создании графа на все его соединения по умолчанию добавляется обработчик ошибок со следующими параметрами:
- Тип: CONNECTION_ERROR;
- Действие: RETRY;
- Попыток реконнекта: 180;
- Тайм-аут реконнекта (сек): 10.
Список обработчиков ошибок приведен в таблице ниже:
| Тип ошибки | Описание ошибки | Действия при возникновении ошибки | Ребро применения |
|---|---|---|---|
| ANY_ERROR | Реакция на любую ошибку | ABORT — прервать выполнение репликации CONTINUE — игнорировать ошибку | Все ребра |
| CONNECTION_ERROR | Ошибка соединения приводящая к недоступности репликации | ABORT — прервать выполнение репликации RETRY — повторить неудавшуюся операцию | Все ребра |
| DML_ERROR | Выполнение операций, не соответствующих структуре базы-источника | ABORT — прервать выполнение репликации | Модуль Applier → БД приемника |
| TRANSFORMATION_ERROR | Проблемы при трансформации полей или их типов | ABORT — прервать выполнение репликации CONTINUE — игнорировать ошибку | Модуль Capture → Kafka Модуль Applier → БД приемника |
| CONSTRAINT_VIOLATION | Нарушений ограничений | ABORT — прервать выполнение репликации CONTINUE — игнорировать ошибку | Модуль Applier → БД приемника |
Типы ошибок
При DML_ERROR обработчик фиксирует следующие виды ошибок:
- Применение транзакций, не совпадающей со структурой таблицы БД приемника;
- Отсутствие таблицы/колонок при применении транзакций;
- Некорректный тип данных при применении транзакций.
При CONNECTION_ERROR обработчик фиксирует следующие виды ошибок:
- Ошибки подключения к БД и Kafka. Сетевая проблема или проблема сервера БД, приводящая к недоступности соединения.
- Ошибки соединения, возникающие при отсутствии системных топиков:
- топика для хранения векторов изменений;
- топика для хранения ошибок репликации;
- Ошибки, возникающие при отсутствии слота/публикаций на БД источнике.
При TRANSFORMATION_ERROR обработчик анализирует трансформации, настраиваемые за счет применения формул при конфигурировании маппинга колонок, и фиксирует следующие виды ошибок:
- Несоответствие типов данных;
- Ошибочное применение формул к объектам.
Тип ошибки CONSTRAINT_VIOLATION позволяет сконфигурировать поведение обработки:
| Конфигурирование | Описание | Особенности конфигурирования |
|---|---|---|
| Категория ошибки (subtype) | - Нарушение первичного ключа (PK); - Нарушение внешнего ключа (FK); - Нарушение заданного логического условия (CHECK и NOT NULL) | - Такое конфигурирование возможно только для типа ошибки CONSTRAINT_VIOLATION; - Если категория ошибки (subtype) не выбрана пользователем, то обработчик вызывается для всех возможных категорий (нарушение PK, нарушение FK, нарушение CHECK); - Если есть несколько обработчиков с одинаковыми условиями (а сама структура ErrorHandler представляет собой массив), то для конкретной ошибки выбирается тот обработчик, где указаны и type, и subtype; - Если есть несколько обработчиков с одинаковыми комбинациями type+subtype, исходный код считается ошибочным и не запускается на выполнение |
| Категория выполняемой операции (opcode) | - INSERT; - UPDATE; - DELETE | - Если категория выполняемой операции (opcode) не выбрана пользователем, то обработчик вызывается для всех операций (INSERT UPDATE DELETE) |
| Максимальное количество ошибок (continue_max) | - Целые, положительные числа | - Доступно только для действия CONTINUE; - После количества ошибок, указанного в этом поле, модуль применения транзакций останавливается, как будто указана политика ABORT; - Если не заполнено, то политика при любом числе ошибок останется Continue |
| Предварительная очистка ошибок (purge_errors) | - True/False | - Если параметр True, то перед тем, как начать применять транзакции из trail’а, модуль применения считывает первый вектор изменений, читает из него идентификатор источника (source_id ) и удаляет командой DELETE все строки из таблицы ошибок, где значение колонки source_id равно этому идентификатору; - В случае, если параметр задан на модуле захвата, то он игнорируется (по умолчанию) |
При ANY_ERROR обработчик фиксирует все возможные виды ошибок:
- DML_ERROR;
- CONNECTION_ERROR;
- TRANSFORMATION_ERROR;
- CONSTRAINT_VIOLATION.
Сохранение данных некорректных транзакций
По умолчанию ошибки записываются в топик Kafka с именем: <имя топика из Соединения Queue>-error.
Для типа ошибки CONSTRAINT_VIOLATION и действия CONTINUE и ABORT для записи ошибки по умолчанию используется техническая таблица $CONFLICT_RESOLUTION_TX$, так же ошибки могу записываться в топик Kafka с именем: <имя топика из Соединения Queue>-conflict-tx/delete/1, либо оба хранилища одновременно.
Настройка сохранения ошибочных транзакций.
При применении изменений из trail-файла к реплике может произойти ошибка — например, при попытке вставить дублирующую строку, удалить строку, на которую ссылается другая таблица, или записать недопустимое значение.
- Нарушение первичного ключа (PK) — например, вставка уже существующего ключа.
- Нарушение внешнего ключа (FK) — Попытка вставить ссылку на несуществующий ключ (INSERT, UPDATE) или попытка удалить из родительской таблицы ключ, на который есть ссылка в дочерней таблице.
- Невыполнение проверок — недопустимое или отсутствующее значение, которое не проходит проверку типа CHECK (включая NOT NULL).
Ошибки обрабатываются через обработчик ошибок, привязанный к модулю.
Ошибочные транзакции сохраняются в отдельное хранилище — теневую таблицу $CONFLICT_RESOLUTION_TX$.
Для создания таблицы пропишите и выполните в редакторе СУБД SQL-скрипт:
CREATE TABLE <schema_name>."$CONFLICT_RESOLUTION_TX$" (
source_id int8 NOT NULL,
gradely_id int8 NOT NULL,
change_vector_seq int4 NOT NULL,
transaction_id int8 NOT NULL,
table_schema varchar(128) NOT NULL,
table_name varchar(128) NOT NULL,
opcode bpchar(1) NOT NULL,
error_code bpchar(1) NOT NULL,
error_message text NULL,
vector_data jsonb NOT NULL,
error_handle_action bpchar(1) NOT NULL,
process_id uuid NOT NULL,
created_at timestamp NOT NULL,
CONSTRAINT "$CONFLICT_RESOLUTION_TX$_pkey" PRIMARY KEY (source_id, gradely_id, change_vector_seq)
);
Ошибочные транзакции сохраняются в теневой таблице, если в поле options для соединения базы данных параметр save.skipped.tx.to.db: true.
По умолчанию save.skipped.tx.to.db: true.
По умолчанию таблица находится в схеме grdl.
Структура технической таблицы:
| Колонка | Тип | Описание |
|---|---|---|
| source_id | bigint | ID базы-источника |
| gradely_id | bigint | внутренний ID транзакции GraDeLy |
| change_vector_seq | int | порядковый номер вектора изменений в транзакции |
| transaction_id | bigint | ID транзакции |
| table_schema | varchar(128) | Схема таблицей-приемником |
| table_name | varchar(128) | Название таблицы-приемника |
| opcode | char(1) | Операция (I, U, D) |
| error_code | char(1) | Тип ошибки (F — нарушение внешнего ключа, P — нарушение первичного ключа, C — нарушение проверки значений) |
| error_message | varchar2(256) | Человекочитаемое описание ошибки |
| vector_data | json | JSON с содержимым вектора |
| error_handle_action | char(1) | Тип реакции на ошибку ( A — ABORT, C — CONTINUE) |
Если указаны кластер и топик, GraDeLy может также сохранять ошибочные векторы в Kafka.
Ошибочные транзакции сохраняются в Kafka topic, если в поле options для соединения базы данных параметр save.skipped.tx.to.kafka: true.
По умолчанию save.skipped.tx.to.kafka: false.
Структура сообщения об ошибке в Kafka topic:
openapi: 3.1.0
info:
title: Error message for REP020
description: Структура сообщения об ошибке
version: 0.0.1
paths:
/:
description: Фиктивный path
components:
schemas:
LogMessage:
description: JSON, который записывается в поле сообщения
type: object
properties:
gradely_id:
description: Идентификатор транзакции, в которой произошла ошибка
type: integer
format: int64
minimum: 1
maximum: 9223372036854775807
example: 83487
source_id:
description: Источник, из которого пришло изменение
type: integer
format: int64
minimum: -9223372036854775808
maximum: 9223372036854775807
example: 87238507
opcode:
description: Код операции
type: string
enum: [ I, U, D ]
exception:
description: Ошибка, полученная драйвером jdbc
type: object
properties:
sql_state:
description: SQLException.getSQLState()
type: string
maxLength: 5
example: 0A000
vendor_code:
description: SQLException.getErrorCode()
type: integer
minimum: -9223372036854775808
maximum: 9223372036854775807
example: 600
additionalProperties: false
vector:
description: Вектор изменений
type: object
additionalProperties:
description: Описание полей
type: string
maxLength: 128
example: The event description
required: [ gradely_id, source_id, opcode, exception, vector ]
additionalProperties: false
Предусловия
Настройка обработчика ошибок доступна пользователю с ролью APPADMIN.
Операции с обработчиком ошибок
- Создание стратегии поведения при ошибках ANY_ERROR
- Создание стратегии поведения при ошибках CONNECTION_ERROR
- Создание стратегии поведения при ошибках DML_ERROR
- Создание стратегии поведения при ошибках TRANSFORMATION_ERROR
- Создание стратегии поведения при ошибках CONSTRAINT_VIOLATION
- Удаление заданного поведения при ошибке
- Редактирование заданного поведения при ошибке
Сценарии работы обработчика ошибок
Сценарии работы при ошибке TRANSFORMATION_ERROR
| Описание | Действие при ошибке | Сценарий |
|---|---|---|
| Остановка репликации, в случае некорректно примененной формулы для трансформации маппинга колонок на модуле захвата | ABORT | В GUI подготавливается граф репликации: - Настраивается маппинг колонок для модуля захвата; - Применяется трансформация в окне "Маппинг колонок"; - Вводится формула трансформации и указывается колонка на потребителе. Пример формулы, вызывающей ошибку трансформации: value/0; - Настраивается обработчик ошибок с типом "TRANSFORMATION_ERROR" на ребре между модулем захвата и Kafka; - Тип действия устанавливается ABORT; - Запускается граф репликации; - Применяется INSERT в таблицу источника; - Обработчик ошибок фиксирует ошибку трансформации; - Ребро между модулем захвата и кафкой окрашивается в красный цвет; - Репликация останавливается |
| В случае некорректного применения формулы трансформации маппинга колонок на модуле применителе, репликация данных не останавливается, ошибка фиксируется в топике Kafka и таблице ошибок на БД приемнике | CONTINUE | В GUI подготавливается граф репликации: - Настраивается маппинг колонок для модуля применения; - Применяется трансформация в окне "Маппинг колонок"; - Вводится формула трансформации и указывается колонка на потребителе. Пример формулы, вызывающей ошибку трансформации: value/0; - Настраивается обработчик ошибок с типом "TRANSFORMATION_ERROR" на ребре между модулем применителя и БД приемника; - Тип действия устанавливается CONTINUE: ошибочная запись пропускается, репликация продолжается; - Запускается граф репликации; - Применяется INSERT в таблицу источника; - Обработчик ошибок фиксирует ошибку трансформации; - В топике Kafka и таблице для записей ошибок присутствует информация о не примененных транзакциях; - Репликация не прекращается |
Сценарии работы при ошибке DML_ERROR
| Описание | Действие при ошибке | Сценарий |
|---|---|---|
| Остановка репликации в случае применения транзакции на таблицу с некорректной структурой данных, ошибка фиксируется в топике Kafka | ABORT | В GUI подготавливается граф репликации: - Настраивается маппинг для модуля захвата и применителя; - Устанавливается тип ошибки "DML_ERROR" на ребре между модулем применителя и БД источника; - Тип действия устанавливается ABORT; - Запускается граф; - Удаляется колонка из таблицы на БД источнике; - Обработчик ошибок фиксирует ошибку DML_ERROR; - Модуль применителя и БД приемник окрашивается в красный цвет на графе репликации; - Ребро между модулем Applier и БД приемником окрашено и красным с крестиком; - В топике Kafka присутствует информация о непримененных транзакциях. По умолчанию записывается в топик с именем: <имя топика из Соединения Queue>-error; - Репликация останавливается |
| Модуль применения получил поле, которого нет в таблице | RETRY | Модуль применения пытается перегенерировать SQL-запрос, повторно запросив структуру таблицы в базе-реплике. Если и при повторной генерации в SQL-запросе не будет всех нужных полей, модуль останавливается (как при политике ABORT ) |
Сценарии работы при ошибке CONSTRAINT_VIOLATION
Сценарий работы обработчика ошибок при нарушении уникальности (UNIQUE):
| Описание | Действие при ошибке | Сценарий |
|---|---|---|
| Остановка репликации, в случае если поле в целевой таблице имеет ограничение UNIQUE, а реплицируемые данные уже существуют в колонке — возникнет нарушение ограничения | ABORT | В GUI подготавливается граф репликации: - Тип ошибки "CONSTRAINT_VIOLATION" на ребре между модулем применителя и БД приемника; - Сконфигурировано поведение обработки на нарушение заданного логического условия; - Тип действия устанавливается ABORT; - Запускается граф репликации; - Применяется INSERT в таблицу источника, реплицируемые данные должны уже существовать в колонке целевой таблицы; - Обработчик ошибок фиксирует ошибку нарушения уникальности; - Ребро между модулем применителя БД приемника окрашивается в красный; - Репликация останавливается |
| В случае применения транзакции, данные которой уже существует в колонке таблицы применителя, репликация данных не останавливается, ошибка фиксируется в топике Kafka и таблице ошибок на БД приемнике | CONTINUE | В GUI подготавливается граф репликации: - Тип ошибки "CONSTRAINT_VIOLATION" на ребре между модулем применителя и БД приемника; - Сконфигурировано поведение обработки на нарушение заданного логического условия; - Тип действия устанавливается CONTINUE: ошибочная запись пропускается, репликация продолжается; - Запускается граф репликации; - Применяется INSERT в таблицу источника, реплицируемые данные должны уже существовать в колонке целевой таблицы; - Обработчик ошибок фиксирует ошибку нарушения уникальности; - В топике Kafka и таблице для записей ошибок присутствует информация о не примененных транзакциях; - Репликация не прекращается |
Сценарий работы обработчика ошибок при нарушении внешнего ключа (FOREIGN KEY):
| Описание | Действие при ошибке | Сценарий |
|---|---|---|
| Остановка репликации, если реплицируемые данные содержат значения внешних ключей, отсутствующих в родительской таблице | ABORT | В GUI подготавливается граф репликации: - Тип ошибки "CONSTRAINT_VIOLATION" на ребре между модулем применителя и БД приемника; - Сконфигурировано поведение обработки на нарушение внешнего ключа (FK); - Тип действия устанавливается ABORT; - Запускается граф репликации; - Применяется INSERT в таблицу источника, при реплицируемые данные должны содержать внешний ключ, которого нет в родительской таблице БД применителя; - Обработчик ошибок фиксирует ошибку внешнего ключа; - Ребро между модулем применителя БД приемника окрашивается в красный; - Репликация останавливается |
| В случае применения транзакции, данные которой содержат значения внешних ключей, отсутствующих в родительской таблице, репликация данных не останавливается, ошибка фиксируется в топике Kafka и таблице ошибок на БД приемнике | CONTINUE | В GUI подготавливается граф репликации: - Тип ошибки "CONSTRAINT_VIOLATION" на ребре между модулем применителя и БД приемника; - Сконфигурировано поведение обработки на нарушение внешнего ключа (FK); - Тип действия устанавливается CONTINUE: ошибочная запись пропускается, репликация продолжается; - Запускается граф репликации; - Применяется INSERT в таблицу источника, при реплицируемые данные должны содержать внешний ключ, которого нет в родительской таблице БД применителя; - Обработчик ошибок фиксирует ошибку внешнего ключа; - В топике Kafka и таблице для записей ошибок присутствует информация о не примененных транзакциях; - Репликация не прекращается |
Сценарий работы обработчика ошибок при невозможности хранения пустого значения (NOT NULL):
| Описание | Действие при ошибке | Сценарий |
|---|---|---|
| Остановка репликации, если реплицируемый набор данных содержит null-значения, при этом целевое поле не допускает пустых значений | ABORT | В GUI подготавливается граф репликации: - Тип ошибки "CONSTRAINT_VIOLATION" на ребре между модулем применителя и БД приемника; - Сконфигурировано поведение обработки на нарушение заданного логического условия; - Тип действия устанавливается ABORT; - Запускается граф репликации; - Применяется INSERT в таблицу источника, реплицируемые данные должны содержать null значения,при этом целевое поле не допускает пустое значение; - Обработчик ошибок фиксирует ошибку непустого значения поля; - Ребро между модулем применителя БД приемника окрашивается в красный; - Репликация останавливается |
| В случае применения транзакции, данные которой содержат null значения, при этом целевое поле не допускает пустых значений, репликация данных не останавливается, ошибка фиксируется в топике Kafka и таблице ошибок на БД приемнике | CONTINUE | В GUI подготавливается граф репликации: - Тип ошибки "CONSTRAINT_VIOLATION" на ребре между модулем применителя и БД приемника; - Сконфигурировано поведение обработки на нарушение заданного логического условия; - Тип действия устанавливается CONTINUE: ошибочная запись пропускается, репликация продолжается; - Запускается граф репликации; - Применяется INSERT в таблицу источника, реплицируемые данные должны содержать null значения,при этом целевое поле не допускает пустое значение; - Обработчик ошибок фиксирует ошибку непустого значения поля; - В топике Kafka и таблице для записей ошибок присутствует информация о не примененных транзакциях; - Репликация не прекращается |
Сценарии работы при ошибке CONNECTION_ERROR
Сценарий работы обработчика ошибок при ошибке соединения к БД источнику:
| Описание | Действие при ошибке | Сценарий |
|---|---|---|
| Остановка и возобновление репликации после восстановления соединения к БД источнику | RETRY | В GUI подготавливается граф репликации: - Тип ошибки "CONNECTION_ERROR" на ребре между БД источника и модулем захвата; - Тип действия устанавливается RETRY (повторная попытка выполнить операцию); - Указывается число попыток и таймаут (в секундах) переподключения; - Запускается граф репликации; - С помощью администратора стенда выключается БД источника; - Происходят попытки переподключения к БД источника в течение указанного времени; - Границы модуля захвата окрашиваются в красную пунктирную линию (происходят реконнекты); - В логах отображаются попытки переподключения: счетчик реконнектов; - С помощью администратора стенда включается БД источника; - Репликация продолжается с момента остановки |
| Остановка репликации при ошибке соединения к БД источнику | ABORT | В GUI подготавливается граф репликации: - Тип ошибки "CONNECTION_ERROR" на ребре между БД источника и модулем захвата; - Тип действия устанавливается ABORT (прервать выполнение репликации); - Запускается граф репликации; - С помощью администратора стенда выключается БД источника; - Обработчик ошибок фиксирует ошибку соединения "CONNECTION_ERROR"; - БД источника и модуль Capture окрашены в красный цвет. Ребро соединения окрашено красным цветом; - Репликация остановлена |
Сценарий работы обработчика ошибок при недоступности кластера Kafka:
| Описание | Действие при ошибке | Сценарий |
|---|---|---|
| Остановка и возобновление репликации после восстановления соединения к кластеру Kafka | RETRY | В GUI подготавливается граф репликации: - Тип ошибки "CONNECTION_ERROR" на ребре между модулем захвата и Kafka; - Тип действия устанавливается RETRY (повторная попытка выполнить операцию); - Указывается число попыток и таймаут (в секундах) переподключения; - Запускается граф репликации; - С помощью администратора стенда выключается кластер Kafka; - Происходят попытки переподключения к кластеру Kafka в течение указанного времени; - Граф полностью зеленого цвета (происходят реконнекты); - В логах отображаются попытки переподключения: счетчик реконнектов; - С помощью администратора стенда включается кластер Kafka; - Репликация продолжается с момента остановки |
| Остановка репликации при ошибке соединения к кластеру Kafka | ABORT | В GUI подготавливается граф репликации: - Тип ошибки "CONNECTION_ERROR" на ребре между БД модулем захвата и Kafka ; - Тип действия устанавливается ABORT (прервать выполнение репликации); - Запускается граф репликации; - С помощью администратора стенда выключается кластер Kafka; - Обработчик ошибок фиксирует ошибку соединения "CONNECTION_ERROR"; - Kafka окрасилась в красный цвет, ребро от capture до Kafka окрасилось в красный цвет; - Репликация остановлена |
Сценарий работы обработчика ошибок при недоступности системных топиков:
| Описание | Действие при ошибке | Сценарий |
|---|---|---|
| Остановка репликации при удалении системных топиков в Kafka, с последующем восстановлении работы при создании топиков | RETRY | В Kafka изменяется параметр автосоздания топиков на False. В GUI подготавливается граф репликации: - Тип ошибки "CONNECTION_ERROR" на ребре между модулем захвата и Kafka; - Тип действия устанавливается RETRY (повторная попытка выполнить операцию); - Указывается число попыток и таймаут (в секундах) переподключения; - Запускается граф репликации; - Удаляются системные топики в Kafka; - В логах отображаются попытки переподключения: счетчик реконнектов; - Граф полностью зеленого цвета (происходят реконнекты); - Восстанавливаются системные топики в Kafka; - Репликация продолжает работу без потери данных |
| Остановка репликации при отсутствии системных топиков в Kafka | ABORT | В GUI подготавливается граф репликации; - Тип ошибки "CONNECTION_ERROR" на ребре между модулем захвата и Kafka; - Тип действия устанавливается ABORT (прервать выполнение репликации); - Запускается граф репликации; - Удаляются системные топики в Kafka; - Обработчик ошибок фиксирует ошибку соединения "CONNECTION_ERROR"; - Ошибка у в событиях процесса: отсутствии системных топиков; - Kafka окрасилась в красный цвет, ребро от capture до Kafka окрасилось в красный цвет; - Репликация останавливается |
Сценарий работы обработчика ошибок при удалении слота БД-источника:
| Описание | Действие при ошибке | Сценарий |
|---|---|---|
| Остановка репликации при удалении слота БД-источника, с последующем восстановлении работы при восстановлении слота | RETRY | В GUI подготавливается граф репликации: - Тип ошибки "CONNECTION_ERROR" на ребре между модулем БД источника и модулем захвата; - Тип действия устанавливается RETRY (повторная попытка выполнить операцию); - Указывается число попыток и таймаут (в секундах) переподключения; - Запускается граф репликации; - Удаляется задействованный слот на БД источнике; - Применяется INSERT в таблицу источника; - Границы модуля захвата окрашиваются в красную пунктирную линию (происходят реконнекты); - Происходят попытки реконекта; - Восстанавливается слот репликации на БД источника; - Репликация продолжает работу без потери данных |
| Остановка репликации при отсутствии слота БД-источника | ABORT | В GUI подготавливается граф репликации: - Тип ошибки "CONNECTION_ERROR" на ребре между модулем БД источника и модулем захвата; - Тип действия устанавливается ABORT (прервать выполнение репликации); - Запускается граф репликации; - Удаляется задействованный слот на БД источника; - Применяется INSERT в таблицу источника; - Модуль БД источника окрасился в красный цвет, ребро от БД источника до модуля захвата окрасилось красный цвет; - Репликация остановлена |
Сценарий работы обработчика ошибок при удалении публикации БД-источника:
| Описание | Действие при ошибке | Сценарий |
|---|---|---|
| Остановка репликации при удалении публикации БД-источника | RETRY | В GUI подготавливается граф репликации: - Тип ошибки "CONNECTION_ERROR" на ребре между модулем БД источника и модулем захвата; - Тип действия устанавливается RETRY (повторная попытка выполнить операцию); - Указывается число попыток и таймаут (в секундах) переподключения; - Запускается граф репликации; - Удаляется задействованная публикация на БД источнике; - Применяется INSERT в таблицу источника; - Границы модуля захвата окрашиваются в красную пунктирную линию (происходят реконнекты); - Происходят попытки реконекта |
Сценарии работы при ошибке ANY_ERROR
Тип ANY_ERROR реагирует на любую ошибку, появившуюся в процессе репликации. При этом в топике Kafka и таблице для записей ошибок присутствует информация о не примененных транзакциях.