3.3.3. Скрипты миграции БД

Проект CUBA-приложения всегда содержит два набора скриптов:

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

  • Скрипты обновления БД - предназначены для поэтапного приведения структуры БД к текущему состоянию модели данных.

CUBA Studio автоматически создает скрипты миграции БД для изменяющейся модели данных вашего проекта, см. документацию. Информация, приведенная ниже, может быть полезна для лучшего понимания данного процесса, а также при создании Groovy-скриптов миграции, которые не поддерживаются в Studio.

При изменении модели данных необходимо отразить соответствующее изменение схемы БД и в скриптах создания, и в скриптах обновления. Например, при добавлении атрибута address в сущность Customer, нужно:

  1. Изменить оператор создания таблицы в скрипте создания:

    create table SALES_CUSTOMER (
  ID varchar(36) not null,
  CREATE_TS timestamp,
  CREATED_BY varchar(50),
  NAME varchar(100),
  ADDRESS varchar(200), -- added column
  primary key (ID)
)

  2. Добавить скрипт обновления, содержащий оператор модификации таблицы:

    alter table SALES_CUSTOMER add ADDRESS varchar(200)

    Обратите внимание, что генератор скриптов Studio не отслеживает изменения Column definition атрибутов сущностей и sqlType специализированных datatype. Таким образом, при их изменении соответствующие скрипты обновления необходимо создавать вручную.

Скрипты создания располагаются в каталоге /db/init модуля core. Скрипты создания дополнительных хранилищ (если таковые необходимы) должны располагаться в каталогах вида /db/init_<datastore_name_in_lower_case>. Для каждого типа СУБД, поддерживаемой приложением, создается свой набор скриптов и располагается в подкаталоге с именем, соответствующим свойству приложения cuba.dbmsType, например, /db/init/postgres. Имена скриптов создания должны иметь вид {optional_prefix}create-db.sql.

Скрипты обновления располагаются в каталоге /db/update модуля core. Скрипты обновления дополнительных хранилищ (если таковые необходимы) должны располагаться в каталогах вида /db/update_<datastore_name_in_lower_case>. Для каждого типа СУБД, поддерживаемой приложением, создается свой набор скриптов и располагается в подкаталоге с именем, соответствующим свойству приложения cuba.dbmsType, например, /db/update/postgres.

Скрипты обновления могут быть двух типов: с расширением *.sql или с расширением *.groovy. SQL-скрипты являются основным средством обновления базы данных. Groovy-скрипты выполняются только механизмом запуска скриптов БД сервером, поэтому применяются в основном на этапе эксплуатации приложения - как правило, это процессы миграции или импорта данных, которые невозможно реализовать на SQL. Чтобы пропустить скрипты Groovy при обновлении, вы можете выполнить следующую команду из командной строки:

delete from sys_db_changelog where script_name like '%groovy' and create_ts > (now() - interval '1 hour')

Скрипты обновления должны иметь имена, которые при сортировке в алфавитном порядке образуют правильную последовательность их выполнения (обычно это хронологическая последовательность их создания). Поэтому при ручном создании рекомендуется задавать имя скрипта обновления в виде {yymmdd}-{description}.sql, где yy - год, mm - месяц, dd - день, description - краткое описание скрипта. Например, 121003-addCodeToCategoryAttribute.sql. Studio при автоматической генерации скриптов также придерживается этого формата.

Чтобы groovy-скрипты также выполнялись командой updateDb, они обязательно должны иметь расширение .upgrade.groovy и ту же логику именования, что и sql-скрипты. Действия из набора Post update в этих скриптах не поддерживаются, для привязки к данным используются стандартные переменные ds (доступ к источнику данных) и log (доступ к журналу сервера). Выполнение groovy-скриптов можно запретить, прописав executeGroovy = false в команде updateDb в build.gradle.

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

В развернутом приложении скрипты создания и обновления БД располагаются в специальном каталоге скриптов базы данных, задаваемым свойством приложения cuba.dbDir.