Как настроить входящую миграцию через PostgreSQL с нуля

В этой статье вы прочитаете вначале общую концепцию входящей миграции, потом общий алгоритм настройке входящей миграции, а потом каждый пункт входящей миграции будет расписан детально.

Общая концепция миграции

1. Нужно в сторонней PostgreSQL БД создать таблицы нужного формата.
2. Потом в них будет сторонняя система заливать данные.
3. После заливки она будет отмечать завершение заливки удалением записи в специальной маркерной таблицы.
4. После этот будет запускаться миграция, по окончанию которой данные будут залиты на платформу.

Что нужно знать, чтобы пользоваться этим руководством

1. Где находится директория логирования
2. Где находятся файлы конфигурации

Алгоритм настройки

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

1. Отметить поля в бизнес-объектах, которые нужно мигрировать из-вне на платформе MyBPM;
2. Подключиться к сторонней базе-данных типа PostgreSQL например с помощью pgAdmin - далее будем это БД называть импортной БД;
3. Получить DDL-таблиц из платформы MyBPM;
4. Накатить полеченные DDL-ы в импортной БД;
5. Настроить подключение платформы MyBPM к импортной БД;
6. Активировать миграцию и провести холостой пуск;
7. Загрузить данные и смотреть процесс миграции;

Пункт 1. Отметить поля в бизнес-объектах

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

Бизнес-объекты создаются в режиме редактирования нажатием на кнопку с плюсом и выбором пункта "Бизнес-объект" как показано на картинке:

Давайте создадим бизнес-объект "Физическое лицо" как показано на картинке:

И укажем ему код: NaturalPerson как показано на картинке:

Теперь зададим код Surname для поля Фамилия как показано на картинке:

Остальные поля также, в итоге должно получиться два бизнес-объекта с такими полями:

Бизнес-объект "Физическое лицо" с кодом "NaturalPerson"
И полями:  Фамилия        с кодом Surname       тип "Текстовое поле"
           Имя            с кодом Name          тип "Текстовое поле"
           ИИН            с кодом IIN           тип "Текстовое поле"
           Дата рождения  с кодом BirthDate     тип "Дата"

Бизнес-объект "Юридическое лицо" с кодом "LegalPerson"
И полями:  Имя            с кодом Name          тип "Текстовое поле"
           БИН            с кодом BIN           тип "Текстовое поле"
           Дата создания  с кодом CreateDate    тип "Дата"

Теперь создадим составной бизнес-объект, как показано на картинке:

Выберем для его формирования бизнес-объекты Физическое и Юридическое лица, как показано на рисунке:

Сформируем поля этого составного объекта-как показано на рисунке:

Так же необходимо задать коды.

Должен получиться такой составной бизнес-объект:

Состановй бизнес-объект: "ЦО Клиент" с кодом "Client"
С полями:   "Дата рожд./созд." с кодом "CrDate"  связанный с полями: "Дата рождения" и "Дата создания"
            "ИИН/БИН"          с кодом "BIIN"    связанный с полями: "ИИН" и "БИН"
            "Имя"              с кодом "Name"    связанный с полями: "Имя" и "Имя"

Создадим ещё бизнес-объект "Заявка на клиента" (стрелочкой обозначен перенос мышкой):

И создадим последний бизнес объект "Заявка на физическое лицо" (стрелочкой обозначен перенос мышкой):

Теперь давайте перечислим всю созданную структуру бизнес-объектов:

Бизнес-объект "Физическое лицо" с кодом "NaturalPerson"
И полями:  Фамилия        с кодом Surname       тип "Текстовое поле"
           Имя            с кодом Name          тип "Текстовое поле"
           ИИН            с кодом IIN           тип "Текстовое поле"
           Дата рождения  с кодом BirthDate     тип "Дата"

Бизнес-объект "Юридическое лицо" с кодом "LegalPerson"
И полями:  Имя            с кодом Name          тип "Текстовое поле"
           БИН            с кодом BIN           тип "Текстовое поле"
           Дата создания  с кодом CreateDate    тип "Дата"

Составной бизнес-объект: "ЦО Клиент" с кодом "Client"
С полями:   "Дата рожд./созд." с кодом "CrDate"  связанный с полями: "Дата рождения" и "Дата создания"
            "ИИН/БИН"          с кодом "BIIN"    связанный с полями: "ИИН" и "БИН"
            "Имя"              с кодом "Name"    связанный с полями: "Имя" и "Имя"

Бизнес-объект "Заявка на клиента" с кодом "ClientClaim"
И полями:  Название       с кодом Name          тип "Текстовое поле"
           Описание       с кодом Descr         тип "Текстовый блок"
           ЦО Клиент      с кодом CoClient      ссылается на ЦО "ЦО Клиент"

Бизнес-объект "Заявка на физическое лицо" с кодом "NaturalClaim"
И полями:  Наименование     с кодом Name          тип "Текстовое поле"
           Описание         с кодом Descr         тип "Текстовый блок"
           Физическое лицо  с кодом Natural       ссылается на БО "Физическое лицо"

Теперь все поля этих бизнес объектов необходимо отметить, что они участвуют в in-migration как показано на рисунке:

Это нужно сделать для всех полей простых бизнес-объектов. Для составных бизнес-объектов это делать не нужно, так как в составном бизнес-объекте данны нет - они распределены по составляющим этого БО.

Не забывайте сохранять изменённые данные.

Пункт 2. Подключение к сторонней БД PostgreSQL

Описание этого пункта не входит в обязанность данного руководства. Вам необходимо заранее ознакомиться с подобными руководствами.

Единственное отметим, что для подключения необходимо знать следующие параметры:

1. Хост или IP-адрес сервера базы данных, на котором размещена БД. Например: 192.168.32.31 - это IP-адрес, или db01.mybpm.local
2. Порт подключения - это число например 5432
3. Имя базы данных - например mybpm_out
4. Имя схемы в базе данных - например in_tables
5. Имя пользователя - например mybpm
6. Пароль пользователя - например 6dfxHTESrO

Эти данные необходимо получить от администратора баз данных. Дальше их ввести в pgAdmin-е при создании подключения, и, если подключение будет успешно, то они правильные.

Дальше по тексту мы будет пользоваться следующими значениями:

IP-адрес сервера базы данных = 192.168.11.23
Порт подключения             = 10018
Имя базы данных              = migration
Имя схемы в базе данных      = in_tables
Имя пользователя             = mybpm_migration
Пароль пользователя          = 6dfxHTESrO

Пункт 3. Получить DDL-таблиц из платформы MyBPM

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

/mybpm/configs/InMigrationPostgresConfig.txt

И в нём укажите схему базы данных, в которой будут помещены таблицы для миграции:

Теперь можно получить DDL-для создания входящих таблиц. Для этого нужно выполнить Rest-запрос:

GET http://localhost:1313/web/migration/generate-in-ddl?companyCode=greetgo

Здесь вместо greetgo вам необходимо указать код того аккаунта, в котором вы создали бизнес-объекты.

А вместо http://localhost:1313 нужно указать адрес установленной платформы MyBPM.

Вот пример как это сделано в Postman-е:

На выходе этого запроса получиться список команд create table ..., в которых будут созданы все необходимые таблицы, через которые будет происходить миграция.

Пункт 4. Накатить полеченные DDL-ы в импортной БД

Эти DDL-и нужно применить для импортной базы данных, чтобы в ней все эти таблицы появились. Вот пример как это сделано в DataGrip:

Сгенерировались следующие таблицы:

in_naturalperson - данные простых полей NaturalPerson
in_legalperson   - данные простых полей LegalPerson
in_naturalclaim  - данные простых полей NaturalClaim
in_clientclaim   - данные простых полей ClientClaim
in_naturalclaim_natural - связка NaturalClaim через поле NaturalClaim.Natural на бизнес-объект NaturalClaim
in_clientclaim_coclient_neturalperson - связка ClientClaim через поле ClientClaim.CoClient на бизнес-объект NaturalPerson
in_clientclaim_coclient_legalperson   - связка ClientClaim через поле ClientClaim.CoClient на бизнес-объект LegalPerson
in_filestorage - файлы для полей с файлами
process_tracking - индикация начала запуска

Пункт 5. Настроить подключение платформы MyBPM к импортной БД;

Настройка подключения к импортной БД осуществляется в конфиге:

/mybpm/configs/InMigrationPostgresConfig.txt

Там ранее уже прописали параметр schemaName. Теперь нужно остальные прописать.

host=192.168.11.23
port=10018
dbName=migration
username=mybpm_migration
password=6dfxHTESrO
schemaName=in_tables
hasInMigration=true

В данном случае пароль и имя пользователя прописаны в открытом виде. Если это недопустимо, то можно определить переменные окружения, например такие:

IN_MIGRATION_DATABASE=migration
IN_MIGRATION_USERNAME=mybpm_migration
IN_MIGRATION_PASSWORD=6dfxHTESrO

И теперь прописать в конфиге /mybpm/configs/InMigrationPostgresConfig.txt ссылки на эти переменные окружения:

host=192.168.11.23
port=10018
dbName:ENV=IN_MIGRATION_DATABASE
username:ENV=IN_MIGRATION_USERNAME
password:ENV=IN_MIGRATION_PASSWORD
schemaName=in_tables
hasInMigration=true

В результате у конфигурационном файле нет отрытых паролей.

Пункт 6. Активировать миграцию и провести холостой пуск

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

Информация о миграции кидается в категорию inMigration.

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

/mybpm/logging/structure.txt

В этом файле найти запись (примечание, в редакторе ZooNavigator-а есть горячая кнопа Ctrl+H для поиска)

category inMigration
    level INFO
    assign_to in_migration

Эта категория отфильтровывает логи до уровня INFO и отсылает их к приёмнику in_migration. Посмотрим на этот приёмник. В этом же файле нужно найти запись.

destination in_migration
    destination in_migration to_file migration/in_migration
    level INFO

Как видим этот приёмник кладёт логи в файл migration/in_migration.log. Найдём этот файл и будем за ним наблюдать.

Миграция активируется в двух местах: активация факта миграции, расписание запуска миграции, таблица in_table.process_tracking

Сам факт миграции активируется в конфигурационном файле:

/mybpm/configs/InMigrationPostgresConfig.txt

В параметре:

hasInMigration=true

Ранее мы уже его поставили в состояние true, т.е. миграция активирована. Проверьте это на всякий случай.

Чтобы миграция запускалась необходимо, чтобы таблица in_table.process_tracking была пустой. Так как мы её только что создали, то она должна быть пустой. Проверьте это. Если там есть запись, то удалите её.

Запись в этой таблице показывает, что миграция уже отработала или ещё работает, и повторную миграцию запускать не нужно.

Теперь нужно настроить расписание запуска миграции. Оно находиться в конфигурационном файле:

/mybpm/scheduler/core/InMigrationScheduler.scheduler-config.txt

В параметре:

startMigrate = repeat every 1 minute

Давайте сделаем чтобы инициация запуска миграции происходила каждую минуту. Не беспокойтесь, параллельно вторая миграция не запуститься, так как это не даст таблица in_table.process_tracking. При запуске миграции в ней появляется запись, которая блокирует последующий запуск миграции параллельно.

Дальше смотрим ранее указанный лог. Там в течении минуты должны появиться записи. Если там появилась ошибка

java.lang.RuntimeException: nYz1en475t :: config.hasInMigration() = true

То нужно перезапустить сервер. Изменения в конфиге не применились.

При старте сервера может вылететь ошибка:

Caused by: org.postgresql.util.PSQLException: FATAL: password authentication failed for user "mybpm_migration"

Это обозначает что система не смогла подключиться к базе данных. Проверьте правильность параметров в конфиге:

/mybpm/configs/InMigrationPostgresConfig.txt

И запустите сервер mybpm-api заново.

Если сервер запустился, значит доступ к БД настроен верно.

Вот нормальный лог миграции:

2024-12-26T08:59:33.261 INFO  Q inMigration g5mP3u7hF4 :: cleanErrorsTable start
2024-12-26T08:59:33.264 INFO  Q inMigration mX9xgIdrQt :: clean days = 10, limit = 10000
2024-12-26T08:59:33.268 INFO  Q inMigration vhhSIlN1W5 :: started saving data to kafka
2024-12-26T08:59:33.269 INFO  Q inMigration 1RHJ7aF2vu :: errors cleaner deleted 0rows in 6 ms.
2024-12-26T08:59:33.285 INFO  Q inMigration w7qP9r57 :: start migration to Kafka by companyId=6f27ebce5e49a79d69e522a8
2024-12-26T08:59:33.290 INFO  Q inMigration 27TtdVdLGj :: periodic_update_time updated
2024-12-26T08:59:33.298 INFO  Q inMigration uENuePJ3M1 :: start to vacuum system tables
2024-12-26T08:59:33.347 INFO  Q inMigration uENuePJ3M1 :: finish to vacuum system tables
2024-12-26T08:59:33.440 INFO  Q inMigration 7cUnbAdw29 :: in migration worker returned boStructure as null for Аккаунт
2024-12-26T08:59:33.445 INFO  Q inMigration 7cUnbAdw29 :: in migration worker returned boStructure as null for Пользователи
2024-12-26T08:59:33.448 INFO  Q inMigration 7cUnbAdw29 :: in migration worker returned boStructure as null for Департамент
2024-12-26T08:59:33.450 INFO  Q inMigration 7cUnbAdw29 :: in migration worker returned boStructure as null for Рабочая группа
2024-12-26T08:59:33.465 INFO  Q inMigration uAhZ1PFqMe :: copyInTableData start
2024-12-26T08:59:33.469 INFO  Q inMigration Gf4MsN7oi5 :: copyInTableData for table = in_NaturalPerson start
2024-12-26T08:59:33.479 INFO  Q inMigration 6ri5uiI970 :: copy table with name copy_2024_12_26_in_NaturalPerson is already exists, will be skipped
2024-12-26T08:59:33.479 INFO  Q inMigration 9o0WErV28h :: copyInTableData for table = in_NaturalPerson finish
2024-12-26T08:59:33.479 INFO  Q inMigration XvCndCKLGg :: extra table is empty, so no copy table will be created for extra
2024-12-26T08:59:33.480 INFO  Q inMigration AI0KjWef :: start setting status ON_WORK to in_tables.in_NaturalPerson occupied_id=612308124825686351
2024-12-26T08:59:33.489 INFO  Q inMigration CHWarE4y :: finish setting status ON_WORK to in_tables.in_NaturalPerson occupied_id=612308124825686351
2024-12-26T08:59:33.496 INFO  Q inMigration uAhZ1PFqMe :: copyInTableData start
2024-12-26T08:59:33.497 INFO  Q inMigration Gf4MsN7oi5 :: copyInTableData for table = in_LegalPerson start
2024-12-26T08:59:33.497 INFO  Q inMigration 6ri5uiI970 :: copy table with name copy_2024_12_26_in_LegalPerson is already exists, will be skipped
2024-12-26T08:59:33.497 INFO  Q inMigration 9o0WErV28h :: copyInTableData for table = in_LegalPerson finish
2024-12-26T08:59:33.497 INFO  Q inMigration XvCndCKLGg :: extra table is empty, so no copy table will be created for extra
2024-12-26T08:59:33.497 INFO  Q inMigration AI0KjWef :: start setting status ON_WORK to in_tables.in_LegalPerson occupied_id=612308124825686351
2024-12-26T08:59:33.502 INFO  Q inMigration CHWarE4y :: finish setting status ON_WORK to in_tables.in_LegalPerson occupied_id=612308124825686351
2024-12-26T08:59:33.505 INFO  Q inMigration 7cUnbAdw29 :: in migration worker returned boStructure as null for ЦО Клиент
2024-12-26T08:59:33.511 INFO  Q inMigration uAhZ1PFqMe :: copyInTableData start

При запуске миграции, в таблице:

in_table.process_tracking

Появиться одна запись, которая будет блокировать дальнейшие запуски миграции.

Пункт 7. Загрузить данные и смотреть процесс миграции

Теперь можно заполнять эти таблицы данными.

После заполнения этих таблиц нужно удалить запись в таблице in_table.process_tracking и миграция запуститься в течении минуты.

Есть в базе данных mybpm_aux1 таблица:

in_migration.log

В которую выбрасываются ошибки миграции.

Есть таблица:

in_migration.timings

В которой отображается скорость миграции. Какие таблицы и сколько про-мигрировал-ись.