В новом переводе от команды Spring АйО вы узнаете, как работает baseline миграция во Flyway, в чем ее отличие от обычного скрипта миграции и каковы преимущества ее использования.

Миграционный скрипт Flyway Baseline — это единый скрипт с префиксом B, который осуществит миграцию пустой базы данных или базы, “очищенной” Flyway, на версию, заданную в имени файла. Это полезно как для объединения длинной, зачастую сложной цепочки исторических миграций, так и для создания копии текущей версии БД из продакшен для использования в качестве отправной точки для последующих миграций.

Что такое baseline миграция?

Файл baseline миграции — это единый скрипт, который может создать определенную версию базы данных. Он используется для миграции пустой БД или такой БД, которую уже “очистил” Flyway, с приведением ее к версии, указанной в имени файла и созданием всех объектов базы данных с сохранением правильного порядка зависимостей. Например, скрипт с префиксом B250__ является baseline скриптом для миграции базы данных от чистого состояния до версии 250. Если вы уже применили к базе данных миграционные скрипты Flyway, тогда baseline миграции будут игнорироваться.

Baseline миграционные скрипты поддерживаются всеми версиями Flyway, но только Enterprise Edition будет автоматически генерировать их. Мы немного поговорим про альтернативные стратегии использования baseline миграции в конце этой статьи.

Когда мы используем baseline миграции?

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

• Объединение исторических миграций в единый скрипт для быстрого создания новых копий базы данных 

• Воссоздание текущей версии уже существующей БД из продакшен одним скриптом, чтобы он мог разрабатываться через Flyway Desktop

Объединение исторических миграций

Главный use case для файла baseline миграции (B) — объединить длинную цепочку исторических миграционных файлов в скрипт, который создает ту же самую базу данных за один шаг. Например, запуск миграционного файла с префиксом B2.5.0 превратит пустую базу данных в ту же самую базу, которая получилась бы при прогоне версионированных миграционных файлов от V1.0.0 до V2.5.0 включительно.

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

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

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

Почему так быстрее? Flyway больше не нужно повторно верифицировать контрольные суммы для каждого файла и затем исполнять всю серию миграций no (как, например, с V1 по V250).

Создание версионированного ‘build скрипта’ для продакшен схемы 

Похожий use case для baseline миграции — это получить единый ‘build скрипт’ для базы данных из продакшен, который сможет воспроизводить текущую версию базы данных из продакшен, начав с пустой базы данных. Это, по сути, всего лишь “особый случай” объединения.

Например, предположим, что у вас есть база данных из продакшен, которую ранее задеплоили с помощью какого-то другого инструмента, отличного от Flyway, например, SQL Compare. Поскольку база данных будет модифицироваться change-скриптом при каждом деплойменте, у вас может быть сотня скриптов синхронизации от SQL Compare, приводящих метаданные из продакшен БД к текущему состоянию. 

Когда вы создаете файл baseline миграции из продакшен БД, он, по сути, объединяет все изменения в метаданных, находящихся в исторических файлах, в один скрипт, который создает ту же версию метаданных и имеет номер версии. Этот use case лучше всего подходит пользователям Flyway Desktop, где этот особый скрипт baseline миграции играет роль отправной точки для разработки и деплоймента дальнейших миграций Flyway.

Baseline миграции не имеют прямого отношения к команде Baseline, но если на данный момент БД в продакшен не управляется Flyway, тогда команду Baseline необходимо прогнать, введя в нее тот же номер версии, который присвоен файлу baseline миграции.

Создание файла baseline миграции

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

По факту, это просто build скрипт, с той лишь разницей, что в нем нет кода создания базы данных или схемы.  Большинство реляционных СУБД позволяют вам сгенерировать такой скрипт по существующей базе данных. После чего вам надо удалить:

• Все DDL на уровне базы данных – например, команды CREATE DATABASE 

• Все команды, относящиеся к созданию схемы – созданием схемы занимается сам Flyway

• Любой DDL для объектов на схемах, которые не контролируются Flyway –  список схем, которые контролируются flyway, находится в  flyway.schemas.

Flyway Enterprise автоматически сгенерирует скрипт в правильном формате для используемой вами РСУБД. Дайте скрипту имя в соответствии с соглашениями Flyway, с префиксом B, и поместите его в одну из папок вашего проекта, где хранятся миграционные скрипты.

Преимущества файлов baseline миграции над обычным ‘build’ скриптом

Мы можем добавлять файлы Baseline миграции (B) к Flyway-проекту, который уже содержит файлы миграций, и при этом не наносить ущерба развитию существующих баз данных, поскольку файлы baseline миграций при миграции существующих БД Flyway игнорирует.

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

Например, если у нас есть последовательность миграций V1-V250 плюс baseline миграция B250, и мы даем инструкцию Flyway выполнить миграцию новой или очищенной базы данных на версию V250, он будет использовать единый файл B250. Если мы используем тот же проект для миграции базы данных, которая уже находится на версии V10, Flyway выполнит всю последовательность версионированных миграций V11-V250.

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

Но если бы вместо baseline миграции мы создали единый версионированный миграционный скрипт V250, что тогда? Тогда нам пришлось бы немедленно заархивировать оригинальные миграционные файлы V1-V250 и либо очистить все существующие копии базы данных, либо использовать команду Repair (он ней мы подробнее расскажем далее).

Как работают baseline миграции

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

Новые или очищенные базы данных

Когда мы используем Flyway-проект, содержащий один или более файлов baseline миграций (B), чтобы мигрировать новую или очищенную базу данных, Flyway будет использовать только B-файл с самым высоким номером версии, а также все последующие версионированные миграции.

В приведенном ниже примере проекта у нас есть версионированные миграции V1-V4 и одна baseline миграция B3. Flyway мигрирует новую базу данных на последнюю версию, запуская скрипты B3 и V4. Только эти два файла зарегистрированы в таблице истории схемы Flyway. Flyway проигнорирует все файлы с номером версии меньше или равным номеру версии baseline миграции.

Поскольку Flyway игнорирует все файлы с номером версии равным или меньше, чем у самого нового файла baseline миграции, это означает, что мы больше не можем мигрировать пустую базу данных ни на одну из более ранних версий. Например, если бы мы ввели команду flyway migrate 'target=2' на пустой базе данных, Flyway вместо этого выполнил бы миграцию на последнюю версию, как показано выше. Если нам была бы нужна новая база данных с версией V2 , нам пришлось бы временно “отключить” файл baseline миграции (напрмер, добавив DoNotUse к началу имени файла).

Аналогично, если в проекте есть baseline миграции B10 и B20 и мы просим Flyway мигрировать новую базу данных на V11, он откажется. Он сможет мигрировать базу данных только на версию 20 и выше.

Существующие базы данных

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

В следующем примере у нас изначально были версионированные миграции V1-V4, и у нас есть база данных на версии V2. В дальнейшем мы добавили baseline миграцию B3. Если мы мигрируем существующую базу данных на последнюю версию, Flyway сделает это посредством прогона скриптов V3 и V4. Только версионированные миграции будут зарегистрированы в таблице истории схемы. Flyway игнорирует все более поздние baseline файлы.

Это также означает, что если у нас есть существующая база данных, которая использовала baseline миграцию B3 и мы в дальнейшем добавляем файл B10 file, Flyway его проигнорирует и вместо него будет использовать миграции V4-V10.

Что делать если вы не можете использовать baseline миграцию

Вместо файла baseline миграции вы можете создать новый супер-миграционный файл, заменяющий все части оригинальной цепочки миграционных файлов. Версионированный миграционный файл понять проще, чем файл baseline миграции, но он может вызвать неприятные проблемы в существующих копиях баз данных.Когда вы его используете, вам надо “отправить в отставку” оригинальные миграционные файлы из таблицы “История схемы Flyway” (Flyway Schema History).

Простой, но требующий решительности подход позволяет просто удалить оригинальные файлы из всех локаций Flyway (имеются в виду locations из настроек flyway) и затем воспользоваться командой Clean на всех имеющихся копиях баз данных, используемых при разработке и тестировании. Конечно, вы не можете сделать этого с базой данных из продакшен или любой другой базой данных, где хранятся данные продакшен, например, Staging.

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

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

Выводы

Небольшие базы данных, с которыми обычно работают проекты Flyway Community, не так сильно подвержены “разбуханию” миграций. Однако, при работе с более крупными и сложными базами данных количество миграций быстро возрастет. Применение файла baseline миграции позволит вам сохранить их, если вы этого хотите. При этом вы получите более быстрый способ создания копий для разработки, потому что тогда Flyway не придется валидировать сотни файлов на многочисленных командах Flyway или многократно выполнять их каждый раз, когда вам захочется сделать копию исходной БД. 

Использование baseline миграций — это самый простой способ “расхламления” проекта. Оно не влияет на существующие базы данных, использующие те же миграционные файлы. Вы создаете файл baseline миграции, который строит базу данных с самой нижней версией, которая все еще полезна для разработки. Как только все активные билды из миграционных локаций используют baseline миграцию, а не оригинальные миграционные файлы, вы можете заархивировать старые миграционные файлы. 

Если вместо этого вы предпочитаете использовать объединенный версионированный миграционный скрипт (V), вам придется прибегнуть к использованию команды Repair.

Присоединяйтесь к русскоязычному сообществу разработчиков на Spring Boot в телеграм - Spring АйО, чтобы быть в курсе последних новостей из мира разработки на Spring Boot и всего, что с ним связано.