Обновление схемы БД

Этот раздел перенесён из документации Camunda 7 и в дальнейшем будет доработан с учётом особенностей OpenBPM Engine

Этот документ проведёт вас через установку и обновление схемы базы данных OpenBPM Engine, используемой процессным движком. Независимо от архитектуры вашего приложения, процессному движку всегда требуется эта схема базы данных. В продакшен-окружении мы рекомендуем подготовить эту схему самостоятельно и сослаться на подготовленный экземпляр базы данных в конфигурации вашего приложения. Обратитесь к руководству по установке для вашего сценария, чтобы соответствующим образом настроить базу данных для удалённого движка, общего движка или встроенного движка.

Это руководство не описывает, как развернуть экземпляр целевой базы данных или как создать в нём объект схемы. Обратитесь к документации вашей целевой базы данных, чтобы узнать это. OpenBPM Engine поддерживает множество баз данных, перечисленных в разделе поддерживаемых окружений.

OpenBPM Engine поддерживает следующие способы установки схемы базы данных:

  • Используйте инструмент миграции баз данных Liquibase https://www.liquibase.org/ с предоставляемым changelog для полуавтоматической установки и обновления. Liquibase отслеживает изменения схемы базы данных. Это позволяет сосредоточиться на том, когда следует применять изменения, а не на том, какие изменения актуальны. OpenBPM Engine поставляется с курируемым файлом changelog, который Liquibase может использовать.

  • Используйте предоставляемые SQL-скрипты с инструментами вашей базы данных для полностью ручной установки и обновления. Ручная процедура позволяет полностью контролировать SQL-операторы, выполняемые на вашем экземпляре базы данных, и при необходимости адаптировать их под свои нужды.

READ COMMITTED — это требуемый уровень изоляции для систем баз данных, на которых работает OpenBPM Engine. При установке OpenBPM Engine вам может потребоваться изменить настройку по умолчанию в вашей базе данных. Подробнее см. документацию об уровнях изоляции.

Установка

Вы можете установить схему базы данных либо с помощью Liquibase, либо вручную с помощью предоставляемых SQL-скриптов. При обновлении версии OpenBPM Engine позже вы можете переключаться между этими механизмами при необходимости. Однако это может потребовать дополнительной подготовительной работы для надёжной работы. Раздел об обновлении Обновление содержит подробности по этой теме.

Установка через Liquibase

OpenBPM Engine поставляется с поддерживаемым файлом changelog, который Liquibase может использовать. Этот changelog определяет, какие SQL-операторы выполнять в базе данных. Changelog и связанные с ним ресурсы можно найти в нашем репозитории артефактов. Выберите нужную версию ($PLATFORM_VERSION) и скачайте ресурсы в виде файла zip или tar.gz. Откройте папку openbpm-engine-sql-scripts-$PLATFORM_VERSION/liquibase, чтобы найти changelog. Если вы используете готовый дистрибутив, ресурсы Liquibase уже находятся в папке sql/liquibase дистрибутива.

Папка liquibase содержит следующие ресурсы:

  • operaton-changelog.xml

  • каталог baseline

Liquibase использует эти ресурсы в сочетании со скриптами в папке upgrade рядом с папкой liquibase для установки схемы.

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

  1. Настройте Liquibase, например, скачав Liquibase CLI https://www.liquibase.org/download.

  2. Выполните команду Liquibase update https://docs.liquibase.com/commands/community/update.html, указав operaton-changelog.xml. Параметры подключения к экземпляру базы данных можно передать через параметры, как описано в документации Liquibase, либо создать файл свойств https://docs.liquibase.com/workflows/liquibase-community/creating-config-properties.html.

Liquibase создаёт две дополнительные таблицы для отслеживания изменений, применённых к вашей базе данных. Таблица DATABASECHANGELOG отслеживает все применённые изменения. Таблица DATABASECHANGELOGLOCK предотвращает конфликты при одновременном обновлении вашего экземпляра базы данных несколькими экземплярами Liquibase. Подробнее об этом можно прочитать в руководстве Liquibase https://www.liquibase.org/get-started/how-liquibase-works.

Поскольку таблицы создаются внешним образом через Liquibase, вы должны настроить движок так, чтобы он не создавал таблицы при запуске. Установите свойство databaseSchemaUpdate в значение false (или, если вы используете Oracle, в noop). За дополнительной информацией о том, как этого добиться, обратитесь к руководству по ручной установке вашего дистрибутива.

Осторожно!

Liquibase предоставляет дополнительные команды для предпросмотра всех изменений, которые будут применены командами, выполняющими SQL-операторы в базе данных. Для команды update можно выполнить команду updateSql https://docs.liquibase.com/commands/community/updatesql.html. Это позволит вам изучить все операторы, которые Liquibase выполнит в вашей базе данных, без их фактического выполнения.

Кроме того, если вы определили специальный префикс для сущностей вашей базы данных, вам придётся вручную скорректировать create-скрипты в каталоге liquibase/baseline, чтобы таблицы создавались с этим префиксом.

Ручная установка

Для установки схемы базы данных, необходимой для OpenBPM Engine, мы предоставляем набор скриптов с подготовленными DDL-операторами. Эти скрипты создают все необходимые таблицы и индексы по умолчанию. Предоставляемые SQL-скрипты можно найти в нашем репозитории артефактов. Выберите нужную версию ($PLATFORM_VERSION) и скачайте скрипты в виде файла zip или tar.gz. Откройте папку openbpm-engine-sql-scripts-$PLATFORM_VERSION/create, чтобы найти все доступные скрипты. Если вы используете готовый дистрибутив, SQL-скрипты уже находятся в папке sql/create дистрибутива.

Папка create содержит следующие SQL-скрипты:

  • $DATABASENAME_engine_$PLATFORM_VERSION.sql

  • $DATABASENAME_identity_$PLATFORM_VERSION.sql

Для каждой поддерживаемой базы данных ($DATABASENAME) есть отдельные SQL-скрипты. Выберите подходящие скрипты для вашей базы данных и выполните их с помощью вашего инструмента администрирования базы данных (например, SqlDeveloper для Oracle).

Поскольку таблицы создаются вручную, вы должны настроить движок так, чтобы он не создавал таблицы при запуске. Установите свойство databaseSchemaUpdate в значение false (или, если вы используете Oracle, в noop). За дополнительной информацией о том, как этого добиться, обратитесь к руководству по ручной установке вашего дистрибутива.

Если вы определили специальный префикс для сущностей вашей базы данных, вам придётся вручную скорректировать create-скрипты, чтобы таблицы создавались с этим префиксом.

Обновление

OpenBPM Engine основан на схеме базы данных Camunda 7.24 и не изменяет её структуру. Поэтому обновление между текущими версиями OpenBPM Engine не требует миграции схемы базы данных — действующая схема совместима со всеми выпусками OpenBPM Engine. Для обновления самого движка следуйте руководству по обновлению.

Если в каком-либо будущем выпуске OpenBPM Engine структура схемы базы данных изменится, вместе с релизом будут опубликованы соответствующие средства обновления (Liquibase changelog и/или SQL-скрипты). Ниже приведена универсальная процедура обновления схемы: она применима к любому такому выпуску и не требует переписывать этот раздел под конкретные версии.

В обозначениях ниже $X — версия, с которой выполняется обновление, $Y — целевая версия, $DATABASENAME — тип вашей базы данных.

Для обновления схемы доступны те же механизмы, что и для установки Установка: Liquibase или ручное выполнение SQL-скриптов. При переключении с одного механизма на другой может потребоваться дополнительная подготовительная работа — см. соответствующие разделы ниже.

Обновление через Liquibase

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

OpenBPM Engine поставляется с поддерживаемым файлом changelog, который Liquibase может использовать. Этот changelog помогает Liquibase отслеживать изменения, уже внесённые в вашу базу данных. На основе этого changelog и таблиц отслеживания Liquibase определяет, какие изменения необходимо применить, когда вы даёте команду обновить схему.

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

  1. Выберите нужную версию, до которой вы хотите обновиться ($Y), в нашем репозитории артефактов и скачайте ресурсы в виде файла zip или tar.gz. Откройте папку openbpm-engine-sql-scripts-$Y/liquibase, чтобы найти файл changelog. Если вы используете готовый дистрибутив, ресурсы Liquibase уже находятся в папке sql/liquibase дистрибутива версии $Y.

  2. Выполните команду Liquibase update https://docs.liquibase.com/commands/community/update.html, указав новый operaton-changelog.xml версии $Y. Liquibase сам определяет необходимые изменения и применяет их к вашей базе данных согласно новому changelog. Параметры подключения к экземпляру базы данных можно передать через параметры, как описано в документации Liquibase, либо создать файл свойств https://docs.liquibase.com/workflows/liquibase-community/creating-config-properties.html.

  3. Мы рекомендуем обновляться до последней доступной патч-версии в пределах целевой версии ($Y).

Нужно ли применять каждую минорную версию, если я пропустил несколько?

Liquibase сам определяет, какие скрипты обновления применять автоматически, согласно changelog вашей целевой версии ($Y).
Пробный прогон

Liquibase предоставляет дополнительные команды для предпросмотра всех изменений, применяемых командами, выполняющими SQL-операторы в базе данных. Для команды update можно выполнить команду updateSql https://docs.liquibase.com/commands/community/updatesql.html, чтобы изучить все операторы, которые Liquibase выполнит в вашей базе данных, без их фактического выполнения.

Миграция на Liquibase

Liquibase предоставляет рабочие процессы для обновления баз данных, которые не были настроены через Liquibase с самого начала. Чтобы такой сценарий работал, нужно заполнить таблицу отслеживания, отражающую текущее состояние вашей базы данных относительно файла changelog, против которого вы хотите обновляться. Иными словами, нужно сообщить Liquibase, какие части changelog уже содержит ваша база данных.

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

  1. Настройте Liquibase, например, скачав Liquibase CLI https://www.liquibase.org/download.

  2. Определите текущую версию схемы вашей базы данных. Эту информацию можно извлечь из таблицы ACT_GE_SCHEMA_LOG. Найдите строку с наибольшим значением в столбце ID_ и используйте значение столбца VERSION_ этой строки.

  3. Выполните команду Liquibase changelogSyncToTag https://docs.liquibase.com/commands/community/changelogsynctotag.html, указав operaton-changelog.xml и используя текущую версию схемы базы данных в качестве тега. Параметры подключения к экземпляру базы данных можно передать через параметры, как описано в документации Liquibase, либо создать файл свойств https://docs.liquibase.com/workflows/liquibase-community/creating-config-properties.html.

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

Ручное обновление

Обновление с вашей текущей минорной версии ($X) до следующей за ней версии ($Y) также требует обновления схемы базы данных. Следуйте описанной процедуре для выполнения этого обновления:

  1. Проверьте наличие доступных патч-скриптов базы данных Обновление патч-уровня для вашей базы данных в пределах вашего пути обновления. Скрипты можно найти в нашем репозитории артефактов. Выберите нужную версию, до которой вы хотите обновиться ($Y), и скачайте скрипты в виде файла zip или tar.gz. Откройте папку openbpm-engine-sql-scripts-$Y/upgrade, чтобы найти все доступные скрипты. Если вы используете готовый дистрибутив, SQL-скрипты уже находятся в папке sql/upgrade дистрибутива версии $Y. Мы настоятельно рекомендуем выполнить эти патчи перед обновлением. Выполните те, что относятся к вашему типу базы данных ($DATABASENAME), в порядке возрастания номера версии. Шаблон именования: $DATABASENAME_engine_$X_patch_*.sql.

  2. Выполните соответствующие скрипты обновления с именами $DATABASENAME_engine_$X_to_$Y.sql. Эти скрипты обновляют базу данных с одной минорной версии до следующей и изменяют базовую структуру базы данных. Поэтому обязательно сделайте резервную копию базы данных на случай сбоев в процессе обновления.

  3. Мы рекомендуем проверить наличие патч-скриптов для вашей базы данных в пределах целевой версии ($Y) и выполнить их в порядке возрастания номера версии. Процедура та же, что и на шаге 1.

Нужно ли применять каждую минорную версию, если я пропустил несколько?

Если вам нужно применить несколько минорных версий, вы ДОЛЖНЫ выполнять скрипты изменения базы данных в порядке минорных версий, так как они НЕ являются кумулятивными.

Обновление патч-уровня

Патч-уровень — это номер версии после второй точки (например, обновление с $Y.0 до $Y.1).

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

Исключение — редкие случаи, когда патч исправляет ошибку в самой схеме базы данных. В таких случаях вместе с релизом публикуется соответствующий патч-скрипт, а сам патч описывается в примечаниях к выпуску. Если вас затрагивает такая ошибка, выполните предоставленный патч-скрипт по процедуре ниже.

Обновление патч-уровня через Liquibase

OpenBPM Engine поставляется с поддерживаемым файлом changelog, который Liquibase может использовать. Этот changelog помогает Liquibase отслеживать изменения, уже внесённые в вашу базу данных. На основе этого changelog и таблиц отслеживания Liquibase определяет, какие изменения необходимо применить, когда вы даёте команду обновить схему. Поэтому процедура обновления патч-уровня эквивалентна процедуре обновления минорной версии Обновление через Liquibase.

Ручное обновление патч-уровня

Необходимые скрипты можно найти в нашем репозитории или в портативной сборке. Выберите нужную патч-версию, до которой вы хотите обновиться ($Y), и скачайте архив в виде файла zip. Откройте папку openbpm-engine-bpm-tomcat-2026.0.0-$Y/sql или openbpm-engine-bpm-2026.0.0-$Y/configuration/sql, чтобы найти все доступные патч-скрипты.

Патч-скрипты именуются $DATABASENAME_engine_$MINOR_patch_$A_to_$B, где $A — патч-уровень, с которого выполняется обновление, $B — патч-уровень, до которого выполняется обновление, а $MINOR — их минорная версия, например 2026.1. Если вы решили применить патч базы данных, то должны применить все патч-скрипты в пределах вашего пути обновления. Это означает, что если ваша текущая патч-версия X.X.1, а вы обновляетесь до X.X.5, сначала нужно выполнить все патч-скрипты, где $A ≥ X.X.1 и $B ≤ X.X.5.

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

Лицензия и атрибуция

Эта документация была создана на базе материала "Camunda 7 Docs" от Camunda, находится под лицензией Creative Commons Attribution-ShareAlike 3.0 Unported License .

Оригинал документации: https://docs.camunda.org