Настройка обработчика ошибок#

В целях отказоустойчивости при создании графа на все его соединения по умолчанию добавляется обработчик ошибок со следующими параметрами:

CONNECTION_ERROR

Действие: RETRY

Попыток реконнекта: 180

Таймаут реконнекта: 10.

Тип ошибки	Описание ошибки	Действия при возникновении ошибки	Ребро применения
ANY_ERROR	Реакция на любую ошибку	ABORT — прервать выполнение репликации CONTINUE — игнорировать ошибку	Все ребра
CONNECTION_ERROR	Ошибка соединения приводящая к недоступности репликации	ABORT — прервать выполнение репликации RETRY — повторить неудавшуюся операцию	Все ребра
DML_ERROR	Выполнение операций, не соответствующих структуре базы-источника	ABORT — прервать выполнение репликации CONTINUE — игнорировать ошибку	Модуль 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, либо оба хранилища одновременно.

Настройка сохранения ошибочных транзакций.

Обработка ошибок CONSTRAINT VIOLATION

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

Нарушение первичного ключа (PK) — например, вставка уже существующего ключа.
Нарушение внешнего ключа (FK) — Попытка вставить ссылку на несуществующий ключ (INSERT, UPDATE) или попытка удалить из родительской таблицы ключ, на который есть ссылка в дочерней таблице.
Невыполнение проверок — недопустимое или отсутствующее значение, которое не проходит проверку типа CHECK (включая NOT NULL).

Ошибки обрабатываются через обработчик ошибок, привязанный к модулю.

Ошибочные транзакции сохраняются в отдельное хранилище — теневую таблицу $CONFLICT_RESOLUTION_TX$ .

Для создания таблицы пропишите и выполните в редакторе СУБД SQL-скрипт:

   CREATE TABLE public."$CONFLICT_RESOLUTION_TX$" (
   source_id bigint NOT NULL,
   gradely_id bigint NOT NULL,
   change_vector_seq int NOT NULL,
   transaction_id bigint NOT NULL,
   table_schema varchar(128) NOT NULL,
   table_name varchar(128) NOT NULL,-
   opcode char(1) NOT NULL,
   error_code char(1) NOT NULL,
   error_message text,
   vector_data jsonb NOT NULL,
   error_handle_action char(1) NOT NULL
   PRIMARY KEY (source_id, gradely_id, change_vector_seq)
   );

Ошибочные транзакции сохраняются в теневой таблице, если в поле options для соединения базы данных параметр save.skipped.tx.to.db: true. По умолчанию save.skipped.tx.to.db: true.

По умолчанию таблица находится в схеме public.

Структура теневой таблицы:

Колонка	Тип	Описание
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.

Операции с обработчиком ошибок#

Сценарии работы обработчика ошибок#

Сценарии работы при ошибке 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.) - Репликация останавливается
В случае применения транзакции на таблицу с некорректной структурой данных, репликация данных не останавливается, ошибка фиксируется в топике Kafka и таблице ошибок на БД приемнике	CONTINUE	В GUI подготавливается граф репликации; - Настраивается маппинг для модуля захвата и применителя; - Пользователь устанавливает тип ошибки «DML_ERROR» на ребре между модулем применителя и БД приемника; - Тип действия устанавливается CONTINUE: ошибочная запись пропускается, репликация продолжается; - Запускается граф репликации; - Удаляется колонка из таблице на БД источнике; - Применение INSERT на БД приемнике; - Обработчик ошибок фиксирует ошибку DML_ERROR; - Ошибка фиксируется в топике Kafka и таблице ошибок на БД приемнике; -Репликация не прекращается.

Сценарии работы при ошибке 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 и таблице для записей ошибок присутствует информация о не примененных транзакциях.