Подготовка окружения воркеров

Подготовка элементов развертывания

Подготовка Docker-образов (для инсталляции в среде DropApp)

Требования, предъявляемые к Docker-образам GraDeLy, разворачиваемому в среде контейнеризации Kubernetes: версия Java — OpenJDK 21.

Для модулей console-ui в Docker-образах необходимо иметь HTTP-сервер для хранения ресурсов: Nginx/Platform V SynGX (версия указана в Системных требованиях).

Настройка окружения

Kafka-топики в GraDeLy

Убедитесь, что создан следующий набор Kafka-топиков:

Топики для репликации между БД

Топик	Обязательность	cleanup.policy	partitions	Назначение	Описание
`<topicName>`	Да	delete	1	Основной топик для записи транзакций, используемых в репликации	—
`<topicName>-error`	Да	delete	1	Топик для сообщений об ошибках репликации	Все ошибки фиксируются для последующего анализа
`<topicName>-conflict-tx`	Да	delete	1	Топик для транзакций, которые не применились к БД	При обработчике ошибок с настройками CONSTRAINT_VIOLATION + continue → в данный топик попадают все пропущенные транзакции. При CONSTRAINT_VIOLATION + abort → в данный топик попадет первая транзакция, которая не применилась. Запись в топик выполняется только при включенной настройке `save.skipped.tx.to.kafka: true` в параметрах соединения с БД приемника

Топики для сообщений клиентских модулей в рамках функциональности Stand-In

Топик	Обязательность	cleanup.policy	partitions	Назначение	Описание
`<StandInStateName>`	Нет	delete	1	Топик для сообщений от воркера к клиентскому о переключении в рамках функциональности Stand-In	Опциональный топик только для работы функциональности Stand-In
`<StandInHeartbeatName>`	Нет	delete	1	Топик для сообщений от клиентских модулей к воркеру о своем состоянии, в рамках функциональности Stand-In	Опциональный топик только для работы функциональности Stand-In

Автосоздание ресурсов воркером

GraDeLy поддерживает автоматическую подготовку части инфраструктуры на стороне Kafka и PostgreSQL. Механизм применяется только к тем ресурсам, которые используются конкретным процессом репликации.

Для Kafka автосоздание управляется параметром gdl.kafka.auto-create-topics-enable:

для воркеров в контейнерной среде параметр по умолчанию включен;

При включенном gdl.kafka.auto-create-topics-enable воркер создает:

основной топик репликации <topicName>;
служебный топик <topicName>-error;
топик <topicName>-conflict-tx для apply-процессов, пишущих в БД;
топики <topicName>-schema и <topicName>-offset, если процесс публикует схему или работает с CAP;
CAP-топики REPL.<baseTopic>.CDC_CAP_SCHEMA и REPL.<baseTopic>.CDC_CAP_DATA, если используется CAP;
топики StandIn, если они заданы в параметрах Kafka-соединения через gdl-lib.state.topic и gdl-lib.heartbeat.topic.

При выключенном gdl.kafka.auto-create-topics-enable все требуемые топики должны быть подготовлены заранее. Иначе проверка соединения или запуск процесса завершатся ошибкой.

Для PostgreSQL автосоздание управляется параметром gdl.db.auto-create-resources.enabled. Параметр применяется к ресурсам источника данных:

replication slot;
publication;
составу таблиц в publication для режимов автоматического сопровождения публикации.

Если gdl.db.auto-create-resources.enabled=false, воркер только проверяет наличие слота и публикации. В этом режиме администратор должен создать их заранее и поддерживать состав publication вручную.

Если gdl.db.auto-create-resources.enabled=true, воркер может автоматически:

создать replication slot с именем из параметра подключения slot;
использовать существующий slot, если он уже создан;
создать publication или синхронизировать её состав по таблицам из конфигурации репликации;
при включенном захвате DDL добавить в publication новую таблицу, созданную оператором CREATE TABLE, если эта таблица допустима по правилам allow-list/deny-list.

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

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

Подготовьте конфигурационный файл postgresql.conf БД источника, выставите необходимые параметры:
- Установите расширенное журналирование с помощью параметра wal_level = logical.
- Установите необходимое максимальное количество слотов репликации с помощью параметра max_replication_slots = 1 (один слот на потребителя).
- Установите необходимое количество одновременно работающих процессов передачи WAL с помощью параметра max_wal_senders = 1 (один процесс на каждый слот).
Создайте роль для БД источника и БД приемника:

Внимание!
Шаг обязательно выполняется только при использовании ИТУЗ. Если вы не используете ИТУЗ переходите к следующему шагу.
```
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.
```
BEGIN;
     CREATE USER {db_worker_user} PASSWORD '{db_worker_user_password}';
END;
```
где {db_worker_user} является пользователем в базе данных воркера.

Так же на БД источника выдайте привилегию суперпользователя:
```
     ALTER USER grdl_worker_test superuser;
```
Создайте схему для БД источника и БД приемника:
```
BEGIN;
     CREATE SCHEMA IF NOT EXISTS  <schema_name> AUTHORIZATION <db_worker_user>;  
END;
```
Внимание!
При использовании ИТУЗ укажите роль в базе данных воркера {db_worker_user}="as_admin".
Выдайте минимально необходимые права репликатору на объекты приемника для всех 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.
- Выполните файл сценария 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; 
```
Создайте в клиентском терминале postgresql в БД источника публикацию и слот репликации:
```
CREATE PUBLICATION <publication_name> FOR ALL TABLES;
SELECT * FROM pg_create_logical_replication_slot('<slot_name>', 'pgoutput');
```
примечание
Механизм публикации в PostgreSQL позволяет выбирать таблицы для репликации. Выбрать таблицы также можно с помощью визуального редактора маппинга (подробнее в «Руководстве пользователя интерфейса консоли управления», однако для лучшей производительности, рекомендуется использовать механизм публикаций.
Публикации могут создаваться автоматически, если в консоли GRDL в опциях соединения выставлен параметр publication_mode.
Для настройки двунаправленной репликации выдайте дополнительные права на публикацию логических слотов.
Создайте новое соединение и настройте параметры соединений с БД, 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;
  - укажите протокол подключения к брокеру.

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

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

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

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$
;

В БД источнике создайте триггеры, подписанные на события 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(); 

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

примечание
При использовании публикации отдельных таблиц необходимо пересоздание или обновление публикации с добавлением новых таблиц. Правила созданий публикаций рассмотрены в Руководстве администратора в разделе "Выбор таблиц для репликации с использованием SQL-команд управления публикациями".
Выдайте права репликатору на объекты приемника:
```
GRANT ALL ON ALL TABLES IN SCHEMA <schema_name> TO gdl_worker; 
```

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

Создайте на базах источника и приемника таблицу $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
);

Передайте владение таблицей администратору:
```
ALTER TABLE IF EXISTS ONLY grdl."$GRADELY _SWITCHOVER$" OWNER TO as_admin;
```

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

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;

Назначение роли в системе авторизации

Проведите интеграцию с системой авторизации и назначьте роль PROJECT_CREATOR.

Создание нового проекта

Создайте проект под ролью PROJECT_CREATOR.

Выпуск и подготовка сертификатов

Platform V GraDeLy работает с уже выпущенными и подготовленными сертификатами. Для получения сертификатов применяется система управления ключами и сертификатами посредством Vault Agent.

Подготовка элементов развертывания​

Подготовка Docker-образов (для инсталляции в среде DropApp)​

Настройка окружения​

Kafka-топики в GraDeLy​

Топики для репликации между БД​

Топики для сообщений клиентских модулей в рамках функциональности Stand-In​

Автосоздание ресурсов воркером​

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

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

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

Назначение роли в системе авторизации​

Создание нового проекта​

Выпуск и подготовка сертификатов​