Описание применения

Назначение

Продукт Platform V GraDeLy — платформа для логической репликации, фильтрации и преобразования данных. Она обеспечивает захват, доставку и применение изменений между поддерживаемыми версиями баз данных, гарантируя при этом надежное исполнение этих операций. Платформа включает графический интерфейс для настройки и мониторинга состояния репликации.

Продукт состоит из компонентов: Базового модуля (GRDL), Модуля репликации (RPLW).

Platform V GraDeLy (GDL) поддерживает как централизованные инсталляции с системой управления, так и децентрализованные с управлением через API или посредством локального конфигурирования.

Продукт обеспечивает:

• логическую репликацию между реляционными и нереляционными источниками данных;
• синхронизацию логической реплики в целях доступности сервисов при технологических работах в рамках решения задачи N-цод;

Основные функции

• Репликация потока логических изменений

  Обеспечение последовательного применения изменений в принимающей базе данных.

• Преобразование таблиц и данных

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

• Управление конфигурациями воркеров

  Создание и изменение конфигурации графа репликации.

• Хранение настроек модулей в репозитории

  Обеспечение доступа к хранилищу конфигураций на чтение и запись.

• Управление репликацией

  Исполнение команд запуска, остановки и конфигурирования репликации.

• Сбор событий и метрик работы приложения и их предоставление для внешних систем

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

• Запуск репликации с позиции GraDeLyID

  Запуск репликации с последнего записанного GraDeLyID — идентификатора последней примененной транзакции.

• Двунаправленная репликация

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

• Аутентификация и авторизация

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

• Защита данных пользователей

  Учетные данные пользователей хранятся в защищенном виде в системе авторизации.

• Ролевая модель

  В GraDeLy реализована ролевая модель, позволяющая ограничить доступ пользователей к определенным частям функциональности (например, скрыть отдельные закладки).

• Механизм подтверждения операций

  В GraDeLy доступен механизм подтверждения запуска и остановки репликации со стороны суперпользователя — КВР, контроль второй рукой.

• Управление секретами

  Возможность работы как с базовыми секретами, так и с секретами Hashicorp Vault.

• Поддержка Kafka Connect

  Управления кластером Kafka Connect через GraDeLy UI для потоковой передачи данных между Apache Kafka и другими системами данных.

• Поддержка Stand-In

  Переключение приложения потребителя с основной БД на резервную.

Ограничения поддержки

У GraDeLy есть следующие ограничения в использовании:

1. Если столбцы типов данных char, varchar, text или bytea являются частью первичного или уникального ключа, максимальная длина отдельных столбцов не должна превышать 8191 байт.

2. Для типов данных real, double, numeric, decimal значения NaN, Infinity, -Infinity не поддерживаются.

3. Репликация DDL операций имеет ряд ограничений:

   • Захватываются DDL операции, вызывающие срабатывание необходимых примененных триггеров на БД источнике.
   • При публикации таблиц из БД-источника по отдельному списку (настраивается при создании публикации), события создания новых таблиц не влияют на конфигурацию захвата.
   • Не гарантируется поддержка и успешное исполнение специфичных для экземпляра БД команд и их параметров (например, указание tablespace, специфичных путей в файловой системе сервера и других при создании объектов).
   • Сбой в выполнении DDL операции приводит к невозможности гарантировать дальнейшую консистентность данных.
   • Теги '--START NOREPLICATE' и '--END NOREPLICATE' для исключения конкретных операций из захвата не работают с командой TRUNCATE.
   • В wal-журнал отправляется только init query (например, при создании таблицы с PK, не отправляем query создания INDEX).
   • В DDL операции необходимо явное указание схемы.
   • При создании партиции при помощи механизма автопартиционирования, не отправляется в wal-журнал query создания партиции.
   • DDL операции 'CREATE AS SELECT'(видна в WAL как insert, потом create) не реплицируются.
   • В триггере не захватываются DDL операции c CONCURRENTLY.
   • Доступна репликация создания sequence. Значения sequence не реплицируются.
   • Не реплицируются операции DDL в do блоках.
   • Не реплицируются операции DDL в функциях и процедурах.
   • Репликации DDL не поддерживаются во время инициализирующей выгрузки.
   Подробнее

   GraDeLy поддерживает репликацию следующих DDL-операций: :::

   Таблицы:

   CREATE TABLE:

   • стандартные таблицы;
   • партиционированные таблицы: CREATE TABLE … PARTITION BY …;
   • таблицы с GENERATED ALWAYS AS (…) STORED;
   • таблицы с GENERATED ALWAYS AS IDENTITY;

   ALTER TABLE:

   • ADD COLUMN …;
   • RENAME COLUMN … TO …;
   • DROP COLUMN …;
   • ALTER COLUMN … SET DEFAULT …;
   • ALTER COLUMN … DROP DEFAULT;
   • ALTER COLUMN … SET NOT NULL;
   • ALTER COLUMN … TYPE … USING …;
   • RENAME TO … (переименование таблицы);
   • SET SCHEMA … (перенос таблицы между схемами);

   DROP TABLE:

   • DROP TABLE;
   • DROP TABLE … CASCADE;
   • DROP TABLE IF EXISTS …;

   TRUNCATE;

   Сиквенсы и IDENTITY:

   • CREATE SEQUENCE …;
   • ALTER SEQUENCE … OWNED BY …;

   Таблицы со столбцами:

   • DEFAULT nextval('…'::regclass);
   • GENERATED ALWAYS AS IDENTITY;

   Перевод столбца с SEQUENCE на IDENTITY:

   • ALTER TABLE … ALTER COLUMN … DROP DEFAULT;
   • ALTER TABLE … ALTER COLUMN … ADD GENERATED ALWAYS AS IDENTITY;

   Представления:

   Обычные VIEW:

   • CREATE VIEW … AS SELECT …;
   • ALTER VIEW … RENAME TO …;
   • DROP VIEW …;

   Материализованные VIEW:

   • CREATE MATERIALIZED VIEW … AS SELECT …
   • REFRESH MATERIALIZED VIEW … (поддерживается, потенциально тяжелая операция)
   • DROP MATERIALIZED VIEW …

   Типы / ENUM:

   • CREATE TYPE … AS ENUM ('…', '…', …);
   • ALTER TYPE … ADD VALUE '…';
   • DROP TYPE …;

   Функции и триггеры:

   Функции:

   • CREATE FUNCTION …(…) RETURNS … LANGUAGE … AS $$ … $$;
   • ALTER FUNCTION … OWNER TO …;
   • DROP FUNCTION …(…);

   Триггеры:

   • CREATE FUNCTION …() RETURNS trigger LANGUAGE … AS $$ … $$;
   • CREATE TRIGGER … BEFORE/AFTER … ON … EXECUTE FUNCTION …();
   • DROP TRIGGER … ON …;

   Схемы:

   • CREATE SCHEMA …;
   • DROP SCHEMA … CASCADE;
   • DROP SCHEMA IF EXISTS … CASCADE (корректный no-op при отсутствии схемы);

   Партиционирование:

   • CREATE TABLE … PARTITION BY …;
   • CREATE TABLE … PARTITION OF … FOR VALUES …;
   • ALTER TABLE … DETACH PARTITION …;
   • ALTER TABLE … ATTACH PARTITION … FOR VALUES …;
   • DROP TABLE … (как для партиций, так и для родительской таблицы);

   IF EXISTS / IF NOT EXISTS:

   Все конструкции вида:

   • CREATE … IF NOT EXISTS …;
   • DROP … IF EXISTS …;
   • Обрабатываются «тихо»: при уже существующем/отсутствующем объекте — корректный no-op без ошибок на приёмнике;

   DDL + DML и транзакции:

   Транзакции вида:

   • BEGIN; CREATE TABLE …; INSERT …; COMMIT;
   • Гарантируется сохранение порядка DDL → DML на приёмнике в рамках транзакции.

   Кавычки и Unicode:

   Поддерживаются идентификаторы с кавычками, пробелами и Unicode:

   • CREATE TABLE schema."Имя Таблицы"("Имя Столбца" text)
   • ALTER TABLE … RENAME COLUMN "Имя" TO "Имя2"

   :::

4. Большие объекты не реплицируются. Это ограничение можно обойти за счет хранения данных в обычных таблицах.

5. Максимально допустимы размер реплицируемой транзакции определяется совокупностью ограничений:

   • max.request.size на стороне Kafka producer рекомендуется установить равным max.message.bytes Kafka топика (задается в параметрах соединения KAFKA в UI GraDeLy, default 10MB);
   • max.message.bytes на уровне Kafka topic;
   • объёмом heap-memory воркера GraDeLy, так как транзакция целиком буферизуется в памяти JVM.
   примечание

   GraDeLy передаёт каждую зафиксированную транзакцию источника в Kafka как одно сообщение. Использование сжатия уменьшает размер сообщения, отправляемого в Kafka, но не отменяет необходимости полного размещения транзакции в heap-memory воркера.

6. Репликация поддерживается только для таблиц, включая партиционированные. При попытке реплицировать другие объекты, такие как: представления, матпредставления или сторонние таблицы, будет выдана ошибка.

7. Для топика данных предусмотрена работа только с одной партицией.

8. Таблицы без первичного ключа не реплицируются по умолчанию. Если нужно реплицировать такую таблицу, пропишите в БД источника REPLICA IDENTITY FULL. Без REPLICA IDENTITY FULL не реплицируятся только UPDATE/DELETE, операции INSERT реплицируются.

9. Если публикация создана не для всех таблиц, она не обновляется автоматически после изменения схемы, в которую входят выбранные таблицы. После обновления схемы обновите публикацию: ALTER PUBLICATION <имя_публикации> ADD TABLE <имя_таблицы1>, <имя_таблицы2>; или удалите публикацию командой DROP PUBLICATION <имя_публикации> и создайте публикацию для этих таблиц заново командой CREATE PUBLICATION <имя_публикации> FOR TABLE <имя_таблицы1>, <имя_таблицы2>;. При добавлении новой таблицы в маппинг так же добавьте ее в публикацию командой ALTER PUBLICATION.

10. В Kafka максимальный размер отправляемых сообщений на производителе (Producer) по умолчанию составляет 1 МБ. Для отправки сообщений размером более 1 МБ добавьте в опциях соединения Kafka параметр max.request.size = {ваше_значение_в_байтах}.

Объекты и операции над ними

• GraDeLy поддерживает операции DML (INSERT, UPDATE, DELETE) и DDL.

• Названия без кавычек нечувствительны к регистру: CREATE TABLE MixedCaseTable и SELECT * FROM mixedcasetable эквивалентны.

• Имена таблиц и столбцов в кавычках чувствительны к регистру и должны быть правильно указаны. Например, TABLE appschema. "MixedCaseTable" и ADD TRANDATA appschema. "MixedCaseTable" должны использовать имя таблицы с учетом регистра.

Таблицы и представления

GraDeLy поддерживает:

• захват транзакций DML и DDL из пользовательских таблиц и доставку изменений в пользовательские таблицы;
• захват и доставку данных в партицированные таблицы;
• глобализацию для имен объектов (имена таблицы, схемы, базы данных, столбцы) и данных столбцов.

Поддержка типов данных

В таблице указан статус поддержки репликации различных типов данных

Типы данных	Поддерживается
array	Да
bigint	Да
bigserial	Да
bit	Да
bit varying	Да
boolean	Да
bytea	Да
char	Да
cidr	Да
citext	Да
date	Да
decimal	Да
double precision	Да
enumerated types (enum)	Да
inet	Да
integer	Да
interval	Да
json	Да
jsonb	Да
macaddr	Да
macaddr8	Да
money	Да
numeric	Да
pgvector	Да
real	Да
serial	Да
smallint	Да
smallserial	Да
text	Да
time with/without timezone	Да
timestamp with/without timezone	Да
tsquery	Да
tsvector	Да
uuid	Да
varchar	Да
varbit	Да
xml	Да
Composite Types	Да
box	Нет
circle	Нет
jsonpath	Нет
Domain Types	Нет
line	Нет
lseq	Нет
Object Identifiers Types	Нет
path	Нет
pg_lsn	Нет
pg_snapshot	Нет
point	Нет
polygon	Нет
Pseudo-Types	Нет
Range Types	Нет
txid_snapshot	Нет

Внимание!

Если столбцы типов данных char, varchar, text или bytea являются частью первичного или уникального ключа, максимальная длина отдельных столбцов не должна превышать 8191 байт. Для типов данных real, double, numeric, decimal значения NaN, Infinity, -Infinity не поддерживаются.

Типы применения репликации

GraDeLy поддерживает следующие типы применения репликации:

• Классическая репликация — однопоточный процесс, который использует стандартный SQL для применения данных к целевым таблицам.
• Скоординированная репликация — многопоточный процесс. Один поток-координатор запускает и координирует один или несколько потоков, которые параллельно выполняют операции применения SQL. Скоординированная репликация контролируется и управляется как единое целое.

Классическая репликация

Последовательность процесса:

1. Считывание данных из промежуточного хранилища KAFKA.
2. Фильтрация и преобразование данных.
3. Конструирование выражение SQL, представляющих собой транзакции DML.
4. Применение SQL выражений для целевой БД.

У этого типа применения репликации есть ограничения:

• Каждый поток репликации работает с собственным слотом репликации.
• Потоки классической репликации не обновляют записи с одними и теми же первичными ключами в одинаковых таблицах.
• Потоки классической репликации не изменяют данные, которые имеют зависимости от данных, обновляемых в других потоках классической репликации.

Консоль GraDeLy использует этот тип репликации по умолчанию.

Скоординированная репликация

Последовательность процесса:

1. Считывание данных из промежуточного хранилища KAFKA несколькими потоками репликации.
2. Фильтрация и преобразование данных.
3. Конструирование выражение SQL, представляющих собой транзакции DML.
4. Применение SQL выражений для целевой БД несколькими потоками репликации.

Отличия скоординированной репликации от классической:

• При скоординированной репликации транзакции в разных потоках применяются в строгой очередности, соответствующей GradelyID транзакции.
• При скоординированной репликации каждая транзакция является барьерной для остальных транзакций: пока она не применится, остальные транзакции в других потоках с большим GradelyID не применятся.
• Потоки скоординированной репликации могут обновлять записи с одними и теми же первичными ключами в одинаковых таблицах.
• Скоординированная репликация настраивается из консоли GraDeLy (подробнее в Руководстве администратора).

Концептуальная схема применения скоординированной репликации

Подготовка БД источника и БД приемника для работы с GraDeLy

Обязательные шаги

1. Подготовьте конфигурационный файл postgresql.conf БД источника, выставите необходимые параметры:

   • Установите расширенное журналирование с помощью параметра wal_level = logical.
   • Установите необходимое максимальное количество слотов репликации с помощью параметра max_replication_slots = 1 (один слот на потребителя).
   • Установите необходимое количество одновременно работающих процессов передачи WAL с помощью параметра max_wal_senders = 1 (один процесс на каждый слот).

2. Создайте роль для БД источника и БД приемника:

   Внимание!

   Шаг обязательно выполняется только при использовании ИТУЗ. Если вы не используете ИТУЗ переходите к следующему шагу.

   set role db_admin;
   CREATE ROLE grdl_rep WITH
   NOSUPERUSER
   NOCREATEDB
   NOCREATEROLE
   NOINHERIT
   LOGIN
   REPLICATION
   NOBYPASSRLS
   CONNECTION LIMIT -1
   VALID UNTIL 'infinity'
   ENCRYPTED PASSWORD '${password.placeholder}'
   *GRANT auth_hostssl_scram TO grdl_rep;
   grant "as_admin" to grdl_rep;
   grant execute on function pg_hostname() to "as_admin";
   grant execute on function pg_replication_origin_create(text) TO "as_admin";
   grant execute on function pg_replication_origin_session_setup(text) TO "as_admin";
   grant execute on function pg_replication_origin_session_reset() TO "as_admin";
   grant execute on function pg_replication_origin_drop(text) TO "as_admin";

   примечание

   • Административная роль as_admin — владелец пользовательской схемы. Выдается администраторам АС. Используется для создания новых объектов в БД и их изменения;
   • замените ${password.placeholder} актуальным паролем;
   • замените ${time.placeholder} на timestamp срока действия пароля или на значение infinity для бессрочного пароля.

3. Создайте пользователя для воркера на БД источника и БД приемника:

   Внимание!

   При использовании ИТУЗ пропустите шаг 3.

   BEGIN;
        CREATE USER {db_worker_user} PASSWORD '{db_worker_user_password}';
   END;

   где {db_worker_user} является пользователем в базе данных воркера.

   Так же на БД источника выдайте привилегию суперпользователя:

        ALTER USER grdl_worker_test superuser;

4. Создайте схему для БД источника и БД приемника:

   BEGIN;
        CREATE SCHEMA IF NOT EXISTS  <schema_name> AUTHORIZATION <db_worker_user>;  
   END;

   Внимание!

   При использовании ИТУЗ укажите роль в базе данных воркера {db_worker_user}="as_admin".

5. Выдайте минимально необходимые права репликатору на объекты приемника для всех DML-операций:

   GRANT USAGE, CREATE  ON SCHEMA <schema_name> TO <db_worker_user>;
   GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA <schema_name> TO <db_worker_user>;
   ALTER DEFAULT PRIVILEGES IN SCHEMA <schema_name> GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO <db_worker_user>;
   commit;

   где {db_worker_user} является пользователем в базе данных воркера.

   Внимание!

   При использовании ИТУЗ пользователя в базе данных воркера укажите {db_worker_user}=grdl_worker.

6. Выполните развертывание объектов базы данных в приемнике и выдайте права на создание собственной схемы:

   Внимание!

   При использовании ИТУЗ пропустите шаг 6.

   • Выполните файл сценария MIGRATION_FP_CONF и DB_UPDATE, используя устанавливаемый дистрибутив, чтобы на базе приемника создалась таблица $GRADELY_APPLY_POSITION$ и $CONFLICT_RESOLUTION_TX$.
   • Для загрузки на несколько БД или кластеров БД скриптов LB требуется заново запустить сценарий, изменив перед запуском значение параметра RPLW_POSTGRES_DB_URL_worker.
   примечание

   Вы можете создать технические таблицы $GRADELY_APPLY_POSITION$ и $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)
   );

   воркер по умолчанию ожидает значение ${schema_name} = grdl. Если техническая таблица в схеме с другим именем и в поле Опции имя этой схемы не указано, воркер применителя не найдет техническую таблицу, и участвовать в репликации таблица не будет. Подробнее в Опциях соединения с БД приемника (документ Руководство администратора);

   CREATE TABLE {schema_name}."$GRADELY_APPLY_POSITION$" (
   thread_id int4 NOT NULL,
   trx_id int8 NULL,
   source_id int8 NOT NULL,
   internal_id int8 NULL,
   "offset" int8 NULL,
   kafka_id varchar(255) NULL,
   CONSTRAINT grdl_pk_apply_position_id PRIMARY KEY (source_id)
   );

   • достаточно создать одну таблицу $GRADELY_APPLY_POSITION$ и $CONFLICT_RESOLUTION_TX$ на каждой БД приемника. Выдача дополнительных прав репликатору на объекты источника не требуется. Название таблиц неизменно.

   • Выдайте минимально необходимые права репликатору на объекты приемника на создание собственной схемы:

     GRANT SELECT, INSERT, UPDATE, DELETE, TRUNCATE ON <GRADELY_APPLY_POSITION>, <CONFLICT_RESOLUTION_TX> IN SCHEMA <schema_name> TO <db_worker_user>;
     commit; 

7. Создайте в клиентском терминале postgresql в БД источника публикацию и слот репликации:

   CREATE PUBLICATION <publication_name> FOR ALL TABLES;
   SELECT * FROM pg_create_logical_replication_slot('<slot_name>', 'pgoutput');

   примечание

   Механизм публикации в PostgreSQL позволяет выбирать таблицы для репликации. Выбрать таблицы также можно с помощью визуального редактора маппинга (подробнее в «Руководстве пользователя интерфейса консоли управления», однако для лучшей производительности, рекомендуется использовать механизм публикаций.

   Публикации могут создаваться автоматически, если в консоли GRDL в опциях соединения выставлен параметр publication_mode.

   Для настройки двунаправленной репликации выдайте дополнительные права на публикацию логических слотов.

8. Создайте новое соединение и настройте параметры соединений с БД, Kafka или файловым хранилищем на вкладке Соединения.

   Для каждого из используемых соединений заполните набор обязательных параметров:

   name:         Человекочитаемое имя
   type:         Из списка [DB, QUEUE]
   driver:       Используемый драйвер

   1. Наполнение соединения Source:

      • В таблице источника пропишите и запустите select * from pg_get_replication_slots();

      • найдите свободный слот - тот, где статус столбца active равен false (отсутствует галочка);

      • добавьте следующий JSON в опции создаваемого соединения в UI:

        {
        "url": "<url>",
        "slot": "<replication_name>",
        "publication_names": "<publication_name>",
        "driver": "<connection_driver>"
        }

      • пропишите адрес БД источника в поле URL (формат: "jdbc:postgresql:/url:5432/postgres");

      • пропишите имя свободного слота на месте Слот;

      • пропишите название необходимой публикации;

      • пропишите используемый драйвер.

   2. Наполнение соединения Target:

      • добавьте следующий JSON в опции создаваемого соединения в UI:

      {
      "url": "<url>",
      "driver": "<connection_driver>",
      "apply_position_schema": "<schema_name>"
      }

      • пропишите адрес БД приемника в поле URL (формат: "jdbc:postgresql:/url:5432/postgres");

      • пропишите используемый драйвер;

      • укажите схему приемника.

        примечание

        • Воркер по умолчанию ожидает значение <schema_name> = grdl, однако можно указать другую схему через параметр apply_position_schema.
        • Если не указать имя схемы, содержащей техническую таблицу, воркер применителя будет искать техническую таблицу в схеме с именем grdl.
        • Если техническая таблица находится в схеме с именем grdl, имя схемы в поле Опции можно не прописывать.
        • Если техническая таблица в схеме с другим именем и в поле Опции имя этой схемы не указано, воркер применителя не найдет техническую таблицу, и участвовать в репликации таблица не будет.

   3. Наполнение соединения Kafka:

      {
      "bootstrap.servers": "<адрес брокера Kafka (формат: host:port)>",
      "topic.name": "<топик_Kafka>",
      "security.inter.broker.protocol": "<протокол_подключения_к_брокеру>"
      }

      • пропишите адрес брокера Kafka в поле;
      • пропишите топик Kafka;
      • укажите протокол подключения к брокеру.

Опциональные шаги для поддержки определенных функций

1. Для поддержки репликации DDL операций выполните применение функций и триггеров на БД источнике.

   1. В БД источнике создайте функцию вызова посылки сообщений с информацией об изменениях в слот репликации:

      CREATE OR REPLACE FUNCTION {schema_name}.grdl_ddl_emit()
       RETURNS event_trigger
       LANGUAGE plpgsql
       SECURITY DEFINER
       SET search_path TO 'pg_catalog'
      AS $function$
      DECLARE
      _command_text  text := current_query();
        _event         text := TG_EVENT;
        _tag           text := 'grdl_ddl_event';
        _cmd           text := TG_TAG;
      
        r_object_type  text;
        r_schema_name  text;
        r_object_name  text;
      
        payload        text;
        v_norepl       text;
      BEGIN
        v_norepl := current_setting('grdl.noreplicate', true);
      
        IF coalesce(v_norepl, 'off') = 'on' THEN
          RETURN;
      END IF;
      
        IF _event = 'sql_drop' AND _cmd LIKE 'ALTER %' THEN
          RETURN;
      END IF;
      
        IF _event = 'sql_drop' THEN
      SELECT object_type, schema_name, object_identity
      INTO r_object_type, r_schema_name, r_object_name
      FROM pg_event_trigger_dropped_objects()
      WHERE original
        AND COALESCE(schema_name,'') NOT LIKE 'pg_toast%'
        AND COALESCE(schema_name,'') NOT LIKE 'pg_temp%'
      ORDER BY object_identity NULLS LAST
          LIMIT 1;
      ELSE
      SELECT object_type, schema_name, object_identity
      INTO r_object_type, r_schema_name, r_object_name
      FROM pg_event_trigger_ddl_commands()
      WHERE command_tag = _cmd
        AND COALESCE(schema_name,'') NOT LIKE 'pg_toast%'
        AND COALESCE(schema_name,'') NOT LIKE 'pg_temp%'
      ORDER BY object_identity NULLS LAST
          LIMIT 1;
      END IF;
      
        IF NOT FOUND THEN
          RETURN;
      END IF;
      
      
        IF _cmd IN ('CREATE INDEX', 'REINDEX INDEX', 'REINDEX TABLE')
           AND _command_text ILIKE '%CONCURRENTLY%' THEN
          RETURN;
      END IF;
      
        payload := json_build_object(
          'ObjectType',  r_object_type,
          'SchemaName',  r_schema_name,
          'ObjectName',  r_object_name,
          'Command',     _cmd,
          'CommandTag',  _tag,
          'CommandText', _command_text
        )::text;
      
        PERFORM pg_logical_emit_message(true, _tag, payload);
      END;
      $function$
      ;

   2. В БД источнике создайте триггеры, подписанные на события ddl_command_end и sql_drop, вызывающие функцию посылки:

      CREATE EVENT TRIGGER grdl_ddl_emit_create ON ddl_command_end EXECUTE FUNCTION <schema_name>.grdl_ddl_emit(); 

      CREATE EVENT TRIGGER grdl_ddl_emit_drop ON sql_drop EXECUTE FUNCTION <schema_name>.grdl_ddl_emit(); 

   3. В БД источнике создайте публикацию с включением всех таблиц или отдельных таблиц(п.5).

      примечание

      При использовании публикации отдельных таблиц необходимо пересоздание или обновление публикации с добавлением новых таблиц. Правила созданий публикаций рассмотрены в Руководстве администратора в разделе "Выбор таблиц для репликации с использованием SQL-команд управления публикациями".

   4. Выдайте права репликатору на объекты приемника:

      GRANT ALL ON ALL TABLES IN SCHEMA <schema_name> TO gdl_worker; 

2. Для поддержки функции Stand-In:

   1. Создайте на базах источника и приемника таблицу $GRADELY_SWITCHOVER$. Скрипт для создания:

      CREATE TABLE IF NOT EXISTS {schema_name}."$GRADELY_SWITCHOVER$" (
      action_key      VARCHAR(256) PRIMARY key,
      event           VARCHAR(256)  NOT null,
      from_url       VARCHAR(256)  NOT NULL,
      to_url         VARCHAR(256)  NOT NULL
      );

   2. Передайте владение таблицей администратору:

      ALTER TABLE IF EXISTS ONLY grdl."$GRADELY _SWITCHOVER$" OWNER TO as_admin;

   3. Выдайте необходимые права на эту таблицу роли под которой работает воркер:

      GRANT SELECT, INSERT, UPDATE, DELETE ON <GRADELY _SWITCHOVER> IN SCHEMA <schema_name> TO gdl_worker;

      GRANT SELECT, INSERT, UPDATE, DELETE ON <GRADELY _SWITCHOVER> IN SCHEMA <schema_name> TO gdl_worker;

Рекомендации по конфигурированию

В GraDeLy можно конфигурировать маппинг и трансформацию полей как для модуля capture, так и для модуля applier. Маппинг проверяется с учетом метаданных действующих подключений БД источника или приемника.

Общие рекомендации

• Для ремаппинга и настройки трансформации конфигурируйте маппинг для модуля-applier: так конфигурация будет проверена на основе метаданных БД приемника при запуске графа для маппинга и после запуска графа для трансформации.
• Используйте визуальный редактор маппинга: он позволит визуально проверить конфигурацию по типам данным, а также ограничениям (constraints) полей.
• Используйте обработчик ошибок для задания поведения при ошибках репликации.

Рекомендации по трансформации полей

• Будьте осторожны при настройке трансформации ключевых полей источника: эти поля используются для идентификации записи на приемнике, и при подмене полей идентифицировать эти записи на приемнике не получится.
• Проверяйте результаты на переполнение при выполнении трансформаций с арифметическими действиями.
• Остерегайтесь ошибки деления на ноль.
• Проверяйте, что итоговое значение строки помещается в тип данных на приемнике либо используйте явное ограничение длины, например: substr("string1+string2",1+z,%target_type_length%+z), где z — смещение позиции относительно начала строки, если выполняете строковые трансформации с конкатенацией строк.
• Помните, что при настройке формул для NULLABLE полей может встретиться значение NULL, не являющееся ни числом, ни строкой.

Рекомендации по ремаппингу полей

• Проверьте, что типы данных верны и их размерность достаточна.
• Особое внимание уделяйте ограничениям (constraints) на полях источника и приемника.

примечание

Тип данных, максимальное количество символов для этого типа данных, максимальное количество символов без учета знака – для числовых данных отображается в скобках рядом с названием колонки в окне Маппинг колонок в визуальном редакторе маппинга.

Также отображается:

• NOT NULL, если колонка не может быть null;

• UNIQUE, если значение колонки должно быть уникальным;

• PK, если колонка является первичным ключом;

• FK, если колонка является внешним ключом;

• DEFAULT, если есть значение по умолчанию;

• CHECK, если есть условие, которое проверяется перед вставкой. Например, условие для числовой колонки, что значение должно быть >5. Условие отображается при наведении на колонку:

  

Рекомендации по подмене операций

• Перечень разрешенных операций подмены:
  • update -> insert
  • delete -> insert
  • delete -> update
  • delete -> skip
• Соблюдайте уникальность операций подмены: для каждого вида операции используйте не больше одной подмены.
• Убедитесь в отсутствии ограничений типа Primary key и UNIQUE при использовании подмены операций типа update -> insert.

Рекомендации по тестированию конфигурации

• Указывайте соединения источника и приемника при тестировании маппинга и ремаппинга.

Ошибки и предупреждения конфигурации, модуля, графа

В GraDeLy при тестировании могут быть выявлены ошибки двух уровней:

• Error
  • отсутствие полей, таблиц, схем БД;
  • использование недопустимых операций подмены;
  • нарушение уникальности подменяемых операций.
• Warning
  • несоответствие типов;
  • меньшая размерность принимающего строкового типа;
  • меньшая размерность принимающего числового типа.

Ошибки уровня Error блокируют запуск графа или модуля, и оператор обязательно должен их устранить. Ошибки уровня Warning не влияют на запуск графа, но сигнализируют о возможных проблемах после запуска и требуют отдельного внимания оператора.

Рекомендации по устранению ошибок и предупреждений

Если возникла ошибка уровня Error, связанная с отсутствием полей, таблиц или схем в БД источника или приемника:

1. Убедитесь, что необходимые поля, таблицы или схемы есть в БД источника и приемника.
2. Обновите метаданные в визуальном редакторе маппинга.

Проставление меток

Метка - параметр rplw-module.label, который может быть проставлен при развертывании воркеров. Чтобы работать с такими воркерами через UI консоли, необходимо на графе репликации модулю также проставить метку.

Поведение модулей при запуске:

• Модуль с меткой
  • при обнаружении свободного воркера с такой же меткой привязывается к нему и запускается;
  • если свободный воркер с такой же меткой не обнаружен - ошибка запуска.
• Модуль без метки
  • при обнаружении свободного воркера без метки привязывается к нему и запускается;
  • если свободный воркер без метки не обнаружен - ошибка запуска.

Разграничение воркеров между проектами

Если предполагается, что одна консоль GRDL будет управлять репликацией для нескольких проектов, то есть возможность разграничить ресурсы разных воркеров между разными проектами. Для этого необходимо:

• При инсталляции консоли - установить флаг grdl-console.worker-registration-without-projects, позволяющий принимать агенты без указания списка проектов. Если флаг установлен, консоль принимает агента и может запустить на нем задачу любого проекта, основываясь на других механизмах (теги или явное указание идентификатора агента). Если флаг сброшен, то консоль отказывает в регистрации агенту, у которого не указан список проектов либо в списке указаны несуществующие проекты.
• При инсталляции воркера в среде k8s - прописать разрешенные проекты в параметр rplw-module.allowed-projects.

Задержка применения репликации на БД приемника

Отложенное применение изменений на приемнике настраивается в параметрах модуля Applier.

Для настройки отложенного применения изменений:

1. Нажмите модуль на графе.

   

2. Нажмите Редактировать в открывшемся окне Модуль.

   

3. Задайте в секундах задержку применения изменений в БД приемника, чтобы репликация из Kafka в БД приемника шла с задержкой:

   примечание

   Задержка применения отсчитывается от времени операции в БД источника, а не от запуска графа. Например, если в поле Отложенное применение ввести 60 секунд, затем добавить данные в БД источника и запустить граф 20 секунд спустя, то модуль Applier применит изменения в БД приемника через 40 секунд после запуска графа.

   

   На модуле Applier отображается значок ◷, если настроено отложенное применение:

   

4. Нажмите Сохранить.

Перезапуск репликации после нарушение работы модуля

Если модуль Capture или Applier отказал, например из-за большой нагрузки, перезапустите модуль.

Кнопки запуска и перезапуска модуля станут активны после того, как нажмете .

Если репликация остановилась из-за отказа БД источника, сделайте принудительный перезапуск модуля Capture.

Для принудительного перезапуска модуля:

1. Нажмите модуль на графе.

   

2. Нажмите в открывшемся окне Модуль.

   

3. Нажмите в окне Модуль.