Порядок внесения изменений в модель данных#

О документе#

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

Расшифровку основных понятий см. в перечне "Терминов и определений".

Ответственность при внесении изменений в схему данных#

Внимание!

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

Обратно несовместимые изменения схемы данных БД или семантики данных, как правило, ведут к необходимости последующей миграции данных в БД, а также к необходимости переинициализации реплик данных (например, БД StandIn), хранилищ данных, витрин данных и т.д. Может потребоваться переинтеграция с хранилищем данных.

Решение по способу применения обратно несовместимых изменений всегда должно оставаться за владельцем данных. Выше лишь обозначены возможные последствия.

Миграция данных может быть выполнена:

• При помощи SQL-скрипта, выполняемого администратором БД. В этом случае процесс миграции будет под контролем сопровождения — выполняться точечно в техническом окне без нагрузки на БД, а также после завершения синхронизации реплик БД, с инициализацией хранилища данных.

• В составе changelog при условии согласования уполномоченными представителями информационной безопасности внесения изменений в БД при развертывании версии.

Внимание!

Установка версии с обратно несовместимыми изменениями должна тщательно планироваться с учетом всех возможных рисков!

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

Поддержка обратной совместимости#

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

Удаление неиспользуемых объектов базы данных происходит после вывода из эксплуатации устаревших версий приложения.

Откат на предыдущую мажорную или минорную версию приложения не должен требовать отката схемы базы данных (см. рисунок ниже).

По умолчанию DataSpace гарантирует обратную совместимость API при изменении модели данных потребителя.

Последствия обратно несовместимых изменений:

• нарушается работа с базой данных;

• нарушается логика работы DataSpace;

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

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

Третий вид изменений должен контролироваться потребителем DataSpace, поскольку DataSpace не владеет сведениями о семантике данных.

Несовместимые изменения#

С точки зрения DataSpace следующие изменения считаются обратно несовместимыми:

• изменение структуры агрегатов;

• изменение стратегии наследования;

• изменение типов полей (кроме изменений, описанных в разделе "Допустимые с сохранением обратной совместимости преобразования типов");

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

• установка обязательности полей;

• создание уникальных индексов;

• исключение свойств (удаление столбцов);

• исключение классов (удаление таблиц).

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

Переименование столбцов#

DataSpace не отслеживает переименование атрибутов или классов. С точки зрения DataSpace — это создание нового атрибута/класса и удаление старого.

Потребитель должен самостоятельно реализовать миграцию данных из старых структур в новые.

Как следствие, переименование должно проходить в два этапа:

1. Выпуск версии с созданием новых классов и атрибутов с последующей миграцией данных.

2. Выпуск версии с удалением старых классов и атрибутов.

Изменение семантики данных#

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

Служебные таблицы#

Все изменения служебных таблиц DataSpace должны быть обратно совместимыми.

Генератор модели контролирует эти изменения безусловно и блокирует сборку при выявлении обратно несовместимых изменений в служебных данных.

Схема выпуска версий#

Очистка от неиспользуемых элементов#

Очистка от неиспользуемых элементов подразумевает под собой удаление таблиц и столбцов при промышленной эксплуатации.

Внимание!

Начиная с версии 1.7 продукта доступны два режима удаления неиспользуемых элементов:

• Режим удаления в 2 этапа (поддерживался изначально) — при удалении поля или класса в модели соответствующие им физические объекты помечаются как deprecated. Удаленные поля и таблицы физически удаляются, если они были deprecated в предыдущем major-релизе.

• Режим удаления в 3 этапа (поддерживается, начиная с версии 1.7 продукта) — удалению элемента из модели должна предшествовать явная пометка isDeprecated=true на описании в предыдущем major-релизе. Удалить элемент из БД можно в следующий релиз после удаления элемента из описания.

При переходе на версию 1.7 Platform V DataSpace, при наличии в описании модели (pdm.xml) элементов, помеченных как устаревших (с установленным атрибутом isDeprecated=true), возможно появление ошибок сборки:

• "В модели удалены элементы, объявленные deprecated в той же мажорной версии, что может привести к нарушению обратной совместимости API …" (с перечислением элементов модели).

• "Для класса … не найдена позиция в дереве агрегатов."(с указанием класса) — данная ошибка возможна при установке версии DEV-SNAPSHOT при сборке модели.

Возможные способы решения этих проблем:

• 1 способ (сразу удалит элемент из pdm.xml, API и SDK, но не из схемы БД, что равносильно выполнению 2 этапа Механизма удаления неиспользуемых элементов в 3 этапа): повысить major-версию модели;

• 2 способ (позволяет отсрочить удаление элементов из pdm.xml, API, SDK и равносилен удалению элемента из описания модели в "Механизме удаления неиспользуемых элементов в два этапа"):

  • переключиться на механизм удаления неиспользуемых элементов в два этапа (см. раздел "Механизм удаления неиспользуемых элементов в два этапа"), добавив в конфигурацию maven-плагина генерации модели (model-api-generator-maven-plugin) параметра deprecateDeletedItems = true.

  • после того как помеченные isDeprecated=true элементы будут готовы к физическому удалению — поднять мажорную версию модели и выпустить модель с установленным параметром <dropRemovedItems>true</dropRemovedItems> плагина генерации модели (см. раздел Механизм удаления неиспользуемых элементов в два этапа).

  • переключиться на механизм удаления неиспользуемых элементов в три этапа (см. раздел Механизм удаления неиспользуемых элементов в 3 этапа), добавив в конфигурацию maven-плагина генерации модели (model-api-generator-maven-plugin) параметра deprecateDeletedItems = false, либо удалив этот параметр.

Изменение режима удаления осуществляется настройкой maven-плагина генерации модели (model-api-generator-maven-plugin) — параметром deprecateDeletedItems. "Старый" режим включается настройкой deprecateDeletedItems = true,"новый" режим (включен по умолчанию) — deprecateDeletedItems = false.

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

Удаляемые из БД столбцы и таблицы также удаляются в DataSpace Java SDK (соответственно, атрибуты и классы).

При пометке класса модели isDeprecated=true, или его удаления в режиме обратной совместимости, необходимо выполнить аналогичное действие для свойств и внешних ссылок классов модели с типом помечаемого/удаляемого класса. Иначе генерация модели завершится ошибкой с причиной Следующие элементы не являются deprecated (не выставлен признак), но ссылаются на deprecated классы:.

Механизм удаления неиспользуемых элементов в два этапа#

Данный режим удаления включается параметром deprecateDeletedItems = true maven-плагина генерации модели model-api-generator-maven-plugin.

Внимание!

Необходимо удалять вышедшие из эксплуатации объекты спустя 1-3 релиза через механизм стандартных поставок в рамках DevOps.

DataSpace поддерживает очистку БД от неиспользуемых элементов: реализовано удаление неиспользуемых (устаревших) элементов схемы данных через одну версию. Например, в 1-ом релизе добавили в БД столбец, во 2-ом релизе перестали ее использовать, в 3-ем релизе ее необходимо удалить.

При удалении класса/атрибута из модели он фактически не удаляется. Вместо этого в выпускаемой версии он помечается, как "устаревший" (deprecated).

Физическое удаление устаревших классов/таблиц, атрибутов/полей и индексов из схемы данных БД и из DataSpace Java SDK реализовано через major-версию:

• Версия N.xx.xx — класс/атрибут присутствует.

• Версия N+1.yy.yy — класс/атрибут удаляется в модели (deprecated в DataSpace).

• Версия N+2.zz.zz — таблица/столбец физически удаляется в БД.

Примечание

При развертывании необходимо осуществить проверку того, что версия N+1.yy.yy была физически установлена ранее. Проверка должна выполняться вручную представителями сопровождения потребителя при проведении приемо-сдаточных испытаний.

Изменения для физического удаления формируются только при добавлении параметра dropRemovedItems со значением true (<dropRemovedItems>true</dropRemovedItems>) в конфигурацию плагина генерации модели model-api-generator-maven-plugin (см. рисунок ниже).

Допустимо повторно использовать атрибут с тем же именем при условии сохранения его типа (и семантики).

Механизм удаления неиспользуемых элементов в три этапа#

Механизм удаления неиспользуемых элементов в три этапа преследует две цели:

1. Сделать удаление элементов в модели явным для потребителя — при удалении из модели данных также происходит исключение из API и SDK (в отличие от ранее использованный схемы, в которой удаленные элементы оставались в API и SDK как deprecated).

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

Данный режим удаления включается параметром deprecateDeletedItems = false maven-плагина генерации модели model-api-generator-maven-plugin.

Внимание!

Данный режим доступен для использования, начиная с версии 1.7 продукта, и включен по умолчанию.

Новый механизм удаления работает по следующей схеме:

1. Пользователь помечает элементы модели (классы и свойства классов) в описании модели (model.xml) как устаревшие, проставляя на них явно атрибут isDeprecated="true".

   

   Элементы остаются в физической модели (pdm), на API и в SDK, но помечаются генератором как deprecated.

Внимание!

ВАЖНО! При удалении класса, если он имеет коллекционные поля внешних ссылок (reference collection="set"), для таких полей необходимо явно указывать isDeprecated="true" !

2. В следующий (или более поздний) мажорный релиз, пользователь удаляет элемент из описания модели (model.xml). Элементы удаляются генератором из pdm.xml, API и SDK, но не из схемы БД. Возможность выполнять операции по данным элементам отсутствует. Имена таблиц и колонок удаленных элементов помещаются генератором в специальный раздел pdm.xml — unusedSchemaItems:

   <unusedSchemaItems>
       <unusedTable name="" deletedInVersion=""/>
       <unusedColumn name="" tableName="" deletedInVersion=""/>
   </unusedSchemaItems>
   

   Внимание!

   • Если пользователь удалит элемент, не пометив его явно устаревшим (isDeprecated="true"), генерация модели завершиться с ошибкой "В модели удалены элементы, не объявленные ранее deprecated, что приведет к нарушению обратной совместимости API …" (с перечислением элементов, которые были удалены без пометки isDeprecated).

   • Если пользователь удалит элемент в том же мажорном релизе, что и пометил его устаревшим, генерация модели завершиться с ошибкой "В модели удалены элементы, объявленные deprecated в той же мажорной версии, что может привести к нарушению обратной совместимости API …" (с перечислением элементов, которые были удалены в том же мажорном релизе, что и помечены isDeprecated).

3. В очередной релизной версии, при установке настройки плагина генерации модели (model-api-generator-maven-plugin) параметра dropUnusedSchemaItems = true, генерируются скрипты на удаление из БД элементов из раздела unusedSchemaItems, очищается раздел unusedSchemaItems.

   

   Имена таблиц и колонок из unusedSchemaItems не могут быть использованы для новых классов и свойств.

Дополнительные настройки плагина генерации#

При использовании механизма удаления в три этапа имеются дополнительные настройки плагина генерации, позволяющие пропустить некоторые шаги процедуры удаления:

• Параметр dropDeletedItemsImmediately — позволяет удалить таблицы и столбцы сразу, когда они были удалены из описания модели, то есть 2 и 3 шаг механизма удаления, описанные в предыдущем разделе, объединяются в один. Параметр dropUnusedSchemaItems не устанавливается.

  

• Параметр allowDeleteNonDeprecatedItems — позволяет осуществить удаление без явной установки isDeprecated="true" на элемент модели, нет проверки на мажорный релиз, то есть пропускается 1 шаг механизма удаления, описанный в предыдущем разделе.

  

Возможность внесения обратно несовместимых изменений на этапах разработки и тестирования#

DataSpace при сборке выполняет контроль обратной совместимости модели данных.

В процессе разработки и тестировании это приводит к трудностям выпуска версий.

Потребителю предоставлена возможность выпуска промежуточных версий модели с отключенным контролем обратной совместимости. По умолчанию возможность выпуска промежуточных версий отключена. Для ее включения нужно добавить параметр intermediaryBuild со значением true (<intermediaryBuild>true</intermediaryBuild>) в конфигурацию плагина генерации модели model-api-generator-maven-plugin. В таком случае контроль обратной совместимости остается относительно предыдущей релизной версии и отключается относительно предыдущей промежуточной версии.

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

Вносить изменения в модель после отключения цикла промежуточных релизов и перед выпуском релизной версии модели не допускается. Если внести изменения, сборка завершится с ошибкой "Схема билда (pdm.xml) изменена относительно промежуточного (pdm-build.xml)" с указанием пути к измененному свойству.

Чтобы сформировать промежуточную версию модели, помимо установки параметра intermediaryBuild=true необходимо указать версию с постфиксом buildNNN, где NNN — номер билда. Таким образом версии модели будут выглядеть примерно следующим образом:

• 1.0.1 — релизная версия;

• 1.0.2-build001 — первая промежуточная версия;

• 1.0.2-build002 — вторая промежуточная версия;

• 1.0.2-build… — промежуточные версии;

• 1.0.2 — релизная версия, которая содержит изменения относительно последней релизной версии (1.0.1).

Ниже приведен пример, описывающий процесс формирования изменений относительно предыдущих версий:

1. В версии 1.0.1 не было свойства <property name ="prop" type="Date">.

2. В версии 1.0.2-build001 добавлено свойство <property name ="prop" type="Date"> — в changelog добавлен changeSet на добавление колонки с типом Date.

3. В версии 1.0.2-build002 у свойства поменяли тип <property name ="prop" type="String"> — в changelog добавлен changeSet на модификацию типа колонки.

4. В версии 1.0.2 свойство колонки осталось <property name ="prop" type="String"> — в changelog добавлен changeSet на добавление колонки с типом String. ChangeSet-ы из 2 и 3 пунктов удалены.

В параметры запуска Liquibase для стендов, на которых разрешена установка промежуточных версий (DEV/СТ/ИФТ), в конфигурацию развертывания необходимо добавить параметр Liquibase -DenableIntermediaryRelease="true". Если не добавить данный параметр, то будет выдана ошибка Liquibase при попытке наката промежуточной версии модели. В параметры запуска Liquibase для ПСИ или ПРОМ-стендов параметр Liquibase -DenableIntermediaryRelease не добавляется или для него устанавливается значение "false".

Допустимые изменения в рамках промежуточных версий:

• изменение типа;

• изменение размерности поля;

• удаление поля;

• изменение признака коллекционности;

• изменение признака вложенного типа (embeddable) на классе.

Поддержка custom features#

DataSpace формирует схему БД согласно заложенным правилам.

Иногда возникает необходимость внести в схему БД изменения под особенности конкретного потребителя, которые правилами DataSpace не предусмотрены.

Потребителю DataSpace предоставлена возможность включать собственные команды миграций БД в общий скрипт миграции БД, генерируемый при сборке DataSpace (Liquibase changelog.xml).

Создание персонализированного changelog#

Персонализированный changelog предназначен для добавления собственных миграций схемы БД (changeSet) в исходный Liquibase changelog.xml.

Изменения добавляются в релиз текущей сборки.

Добавление своих changeSet необходимо производить в проекте с моделью. В каталог, в котором располагается файл model.xml, добавить файл custom-changelog.xml.

Данный файл должен представлять собой валидный Liquibase changelog в формате XML, аналогично файлу changelog.xml, формируемому DataSpace.

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

Обязательные атрибуты changeSet: id и author. При переносе содержимое author заменяется на custom.changes, id переносится без изменения (в случае совпадения по id в уже сформированном ранее changelog произойдет ошибка сборки).

Для changeSet должны быть специфировать типы БД, к котором они применимы, при помощи атрибута dbms с указанием типов БД.

При оформлении changeSet необходимо руководствоваться оригинальной документацией Liquibase

Допустимы изменения в тегах:

• createView;

• dropView;

• createIndex;

• dropIndex;

• sql;

• insert (при установленном флаге enableCustomDML=true);

• update (при установленном флаге enableCustomDML=true);

• delete (при установленном флаге enableCustomDML=true).

Изменения под тегом sql могут включать в себя:

• Команды DML (при установленном флаге enableCustomDML=true):

  • INSERT INTO;

  • UPDATE SET;

  • DELETE FROM;

  • MERGE INTO;

  • TRUNCATE TABLE.

• Другие изменения, не затрагивающие непосредственно структуру таблиц и типы полей текущей схемы данных. Например, alter table parallel 20.

Запрещенные изменения:

• ALTER TABLE ADD;

• ALTER TABLE MODIFY;

• ALTER TABLE ALTER COLUMN;

• ALTER TABLE DROP COLUMN;

• ALTER TABLE RENAME COLUMN;

• ALTER TABLE RENAME TO;

• DROP TABLE.

• любые изменения служебных таблиц, помимо create/drop index

• изменения набора и типов полей таблиц текущей схемы данных

В changeSet должна быть предусмотрена секция rollback, выполняемая при откате установки версии, для возможности возврата БД в предыдущее рабочее состояние.
Изменения, которые не требуют добавления rollback: теги createView и createIndex (поскольку добавляется autorollback на уровне Liquibase).

Рекомендуется предусмотреть preConditions, проверяющие необходимые условия выполнения изменения.
ChangeSet необходимо разрабатывать так, чтобы была возможность многократного выполнения с одинаковым финальным результатом.

Таким образом для создания/изменения/удаления объектов схемы БД и данных требуется осуществлять полноценные проверки для возможности многоразового исполнения скриптов и исключения повторных модификаций объектов схемы БД и данных.

Необходимо разносить различные по функциональности и логическому назначению SQL-команды на отдельные changeSet Liquibase.

Добавление операций, включающих изменения данных, которые отражены в тегах insert, update, delete и в sql, требуют установки параметра enableCustomDML со значением true (<enableCustomDML>true</enableCustomDML>) в конфигурацию плагина генерации модели model-api-generator-maven-plugin (см. рисунок ниже).

Если данный флаг не установлен, но custom-changelog.xml содержит такие изменения, сборка завершится с ошибкой.

Внимание!

Изменение данных непосредственно в БД влечет за собой последствия в виде необходимости повторной инициализации БД StandIn и всех систем (включая хранилище данных), потребляющих поток изменений, направлямый DataSpace через средства прикладной репликации.

В процессе сборки генератор проверяет custom-changelog.xml на корректность допустимых изменений.

Персонализированный custom-changelog.xml должен содержать изменения только для текущего релиза. При выявлении изменений, уже присутствующих в changelog.xml, процесс сборки завершится с ошибкой.

При отсутствии ошибок содержимое атрибута author меняется на custom.changes, все changeSet переносятся в целевой changelog.xml перед changeSet, содержащим закрывающий тег (tagDatabase) текущего релиза.

В случае сборки релизной версии модели файл custom-changelog.xml переносится в каталог model проекта. К имени файла добавляется постфикс в виде времени переноса файла в формате dd-MM-yyyy_HHmmss. Исходный файл custom-changelog.xml удалится. Для этого необходимо в проекте в файле deployerSettings.xml внести изменения в секцию settings -> deployer -> additionalUnmanagedFiles -> additionalFile. Необходимо путь определить таким образом, чтобы он был направлен на каталог model, который содержит файл описания модели (model.xml). Например, если файл описания модели расположен по адресу "./model/src/main/resources/model/model.xml" , то additionalFile будет равен "./model/src/main/resources/model/": <additionalFile>./model/src/main/resources/model/</additionalFile>.

Примечание

При использовании разделенной модели custom-changelog.xml необходимо располагать рядом с корневым model.xml.

Оптимизация размера генерируемого DataSpace Liquibase changelog#

Механизм оптимизации changelog#

Формируемые скрипты миграций БД (changelog.xml) со временем могут увеличиваться до огромных размеров, в результате чего на их исполнение требуется значительное время и ресурсы, а сами файлы вызывают трудности при проверке даже с применением автоматизированных средств.

Начиная с версии 1.9.0 Platform V DataSpace получил механизм оптимизации changelog. Данный механизм позволяет произвести перегенерацию скриптов liquibase или явно отказаться от генерации скриптов Oracle, уменьшив тем самым размер файла changelog.xml.

Процесс оптимизации заключается в генерации модели с исключением changeSet на изменение и удаление объектов. При этом changeSet на создание объектов сразу отражают структуру версии модели данных, предшествующей оптимизации. Исключаются changeSet на заполнение справочников, которые заменяются на загрузку данных справочников из дистрибутива релиза.

Для оптимизации changelog нужно добавить параметр optimizeChangelog со значением "true" (<optimizeChangelog>true</optimizeChangelog>) в конфигурацию плагина генерации модели model-api-generator-maven-plugin.

После выпуска релиза с оптимизированным changelog необходимо отключить режим оптимизации путем удаления параметра optimizeChangelog из конфигурации плагина генерации модели или переводом значения параметра optimizeChangelog в "false".

Генерации с оптимизацией должен предшествовать как минимум один релиз Platform V DataSpace с версией 1.9.0 и выше. Это связано с тем, что в новой версии генератора модели исходное описание модели (model.xml) теперь сохраняется в pdm.xml (в секцию <source-models>) и используется для генерации оптимизированного changelog.

Плагин выполняет генерацию оптимизированного changelog на основании предыдущего состояния модели. Пользовательские изменения, выполненные с помощью custom-changelog.xml в данное состояние не входят и в оптимизированный changelog не попадают, поэтому при необходимости потребуется добавить их вручную с помощью нового custom-changelog. Механизм оптимизации определит, что в ранее сгенерированном changelog.xml были внесены изменения с помощью custom-changelog.xml и потребует добавления нового custom-changelog (в измененном виде с учетом того, что changelog будет накатываться на чистую БД или же на БД, на которой уже была установлена предыдущая версия).

Примечание

Проверку наличия пользовательских изменений можно отключить, добавив параметр skipCustomChangelogCheck со значением "true" (<skipCustomChangelogCheck>true</skipCustomChangelogCheck>) в конфигурацию плагина генерации модели model-api-generator-maven-plugin.

Полученный оптимизированный changelog может применяться к чистой схеме БД (при создании нового экземпляра DataSpace) либо к БД, на которую был ранее применен changelog, то есть состояние БД соответствует предыдущей версии (при этом осуществляется обязательная проверка наката предыдущей версии changelog).

При оптимизации предыдущий changelog сохраняется в файл save_changelog_before.xml. К имени файла через символ подчеркивания добавляется постфикс в виде времени сохранения файла в формате dd-MM-yyyy_HHmmss. Само содержание предыдущего changelog в оптимизированный changelog не попадает.

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

Внимание!

На всех оптимизированных скриптах отключена возможность отмены (отката) изменений. Следовательно, ограничением выбранного подхода с оптимизацией changelog является потеря возможности отката изменений схемы БД всех версий, кроме текущей.

Возможность явного отказа от генерации скриптов Oracle#

Начиная с версии 1.9.0 в Platform V DataSpace можно отключить генерацию liquibase-скриптов Oracle. Для этого необходимо добавить параметр disableGenerateOracleLiquibase со значением "true" (<disableGenerateOracleLiquibase>true</disableGenerateOracleLiquibase>) в конфигурацию плагина генерации модели model-api-generator-maven-plugin.

Примечание

Добавлять параметр необходимо как для цели (goal) createModel, так и для цели createSdk плагина генерации модели.

При изменении данного параметра требуется выпустить релиз c оптимизацией changelog (optimizeChangelog=true).

Для потребителей с новой моделью данная опция возможна без оптимизации changelog.

Внимание!

После генерации с отключением формирования скриптов Oracle выполнить сгенерированный changelog на БД Oracle будет невозможно.

При необходимости вернуть возможность генерации скриптов для Oracle требуется удалить параметр disableGenerateOracleLiquibase из конфигурации плагина генерации или переключить значение параметра в "false". При этом также потребуется выпустить релиз с оптимизацией.

Рекомендуемый порядок выполнения миграций данных при изменении модели данных#

Изменение данных через API DataSpace#

Внимание!

Изменение данных через API DataSpace является рекомендуемой практикой.

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

Модель данных при этом должна оставаться обратно совместимой между версиями.

Для реализации необходимо написать код (например, с использованием DataSpace Java SDK), выполняющий с использованием search API отбор записей, подлежащих миграции, и для каждой записи выполнить перенос данных с использованием packet API.

Порядок действий:

1. Вначале устанавливается новая версия DataSpace.

2. Затем выполняется код миграции.

3. После этого можно включать функциональность приложения потребителя, которая использует измененную модель.

4. Если в процессе параллельной работы предыдущей версией приложения потребителя были созданы какие-либо данные, необходимо повторить выполнение кода миграции, а в приложении предусмотреть проверку версии данных, с которой оно работает.

DataSpace реплицирует изменения в БД StandIn и в другие системы, подписанные на поток изменений прикладной репликации.

Изменение данных скриптами БД#

Проведение миграций данных скриптами БД допускается, если приложение потребителя DataSpace удовлетворяет всем следующим условиям:

• не требует непрерывной работы;

• есть возможность проводить обновление версий в техническое окно с остановкой всех сервисов;

• отсутствуют интеграции с другими системами через прикладную репликацию (Прикладной журнал).

Удаляемые (или переименованные) атрибуты и классы должны оставаться в модели (с пометкой deprecated), поскольку их данные необходимо перенести в новые атрибуты/классы.

Создается SQL-скрипт, который переносит данные из удаляемых структур в новые структуры.

Нужно учитывать размер транзакции — при больших размерах таблиц перенос нужно выполнять группами записей.

Скрипт нужно выполнить как на основной БД, так и на БД StandIn. Однако, при наличии в скрипте генерируемых значений или временных меток, скрипт необходимо применить только на основной БД, а затем выполнить переинициализацию БД StandIn.

После этого разворачивается новая версия DataSpace. Затем разворачивается новая версия приложения потребителя DataSpace.

Внимание!

Изменения, вносимые в БД SQL-скриптами, не будут отражены в истории изменений сущности. Ответственность за корректность миграций данных, выполненных SQL скриптами, лежит на потребителе DataSpace.

Очистка схемы#

После проведения миграции данных по любому из приведенных вариантов можно выпустить и установить версию модели данных с удалением неиспользуемых столбцов (см.раздел "Очистка от неиспользуемых элементов").

Допустимые с сохранением обратной совместимости преобразования типов#