Миграция баз данных с помощью Flyway

1. введение

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

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

Дальнейшее чтение:

Используйте Liquibase для безопасного развития схемы базы данных

Откат миграций с помощью Flyway

Руководство по обратным вызовам Flyway

Миграции могут быть как версионными, так и повторяемыми. Первый имеет уникальную версию и применяется ровно один раз. У последнего нет версии. Вместо этого они (повторно)применяются каждый раз, когда изменяется их контрольная сумма.

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

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

2. Плагин Flyway Maven

Чтобы установить плагин Flyway Maven, давайте добавим следующее определение плагина в ваш pom.xml:


    org.flywaydb
    flyway-maven-plugin
    4.0.3

Мы можем проверить последнюю версию плагина, доступную по адресу Maven Central .

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

2.1. Конфигурация плагина

Мы можем настроить плагин непосредственно с помощью тега <конфигурация> в определении плагина нашего pom.xml:


    org.flywaydb
    flyway-maven-plugin
    4.0.3
    
        databaseUser
        databasePassword
        
            schemaName
        
        ...

2.2. Свойства Maven

Мы также можем настроить плагин, указав настраиваемые свойства как Maven properties в нашем pom:


    ...
    
        databaseUser
        databasePassword
        schemaName
        ...
    
    ...

2.3. Внешний конфигурационный Файл

Мы также можем предоставить конфигурацию плагина в отдельном файле .properties :

flyway.user=databaseUser
flyway.password=databasePassword
flyway.schemas=schemaName
...

Имя файла конфигурации по умолчанию – flyway.properties , и оно должно находиться в том же каталоге, что и pom.xml файл. Кодировка задается с помощью flyway.encoding (по умолчанию используется UTF-8 ).

Если вы используете любое другое имя (например, custom Config.properties ) в качестве файла конфигурации, то оно должно быть явно указано при вызове команды Maven:

$ mvn -Dflyway.configFile=customConfig.properties

2.4. Свойства системы

Наконец, все свойства конфигурации также могут быть указаны как системные свойства при вызове Maven в командной строке:

$ mvn -Dflyway.user=databaseUser -Dflyway.password=databasePassword 
  -Dflyway.schemas=schemaName

Ниже приведен порядок приоритета, когда конфигурация задана более чем одним способом:

Свойства системы
Внешний файл конфигурации
Свойства Maven
Конфигурация плагина

3. Пример Миграции

В этом разделе мы рассмотрим необходимые шаги для переноса схемы базы данных в базу данных H2 в памяти с помощью плагина Maven. Мы используем внешний файл для настройки Flyway.

3.1. Обновление ПОМ

Во-первых, давайте добавим H2 в качестве зависимости:


    com.h2database
    h2
    1.4.196

Мы можем, опять же, проверить последнюю версию драйвера, доступную на Maven Central . Мы также добавим плагин Flyway, как объяснялось ранее.

3.2. Настройка Flyway С Помощью Внешнего Файла

Затем мы создаем myFlywayConfig.properties в $PROJECT_ROOT со следующим содержимым:

flyway.user=databaseUser
flyway.password=databasePassword
flyway.schemas=app-db
flyway.url=jdbc:h2:mem:DATABASE
flyway.locations=filesystem:db/migration

В приведенной выше конфигурации указано, что наши сценарии миграции находятся в каталоге db/migration . Он подключается к экземпляру H2 в памяти с помощью database User и databasePassword .

Схема базы данных приложения – app-db .

Конечно, мы заменяем flyway.user, flyway.password, и flyway.url нашим собственным именем пользователя базы данных, паролем базы данных и URL-адресом базы данных соответствующим образом.

3.3. Определите Первую Миграцию

Flyway придерживается следующего соглашения об именовании сценариев миграции:

<Префикс><Версия>__<Описание>.sql

Где:

<Префикс> – Префиксом по умолчанию является V , который может быть настроен в приведенном выше файле конфигурации с помощью свойства flyway.sqlMigrationPrefix .
<Версия> – Номер версии миграции. Основные и второстепенные версии могут быть разделены символом подчеркивания . Версия миграции всегда должна начинаться с 1.
<Описание> – Текстовое описание миграции. Описание должно быть отделено от номеров версий двойным подчеркиванием.

Пример: V1_1_0__my_first_migration.sql

Итак, давайте создадим каталог db/migration в $PROJECT_ROOT со скриптом миграции с именем V1_0__create_employee_schema.sql , содержащий инструкции SQL для создания таблицы employee:

CREATE TABLE IF NOT EXISTS `employee` (

    `id` int NOT NULL AUTO_INCREMENT PRIMARY KEY,
    `name` varchar(20),
    `email` varchar(50),
    `date_of_birth` timestamp

)ENGINE=InnoDB DEFAULT CHARSET=UTF8;

3.4. Выполнение Миграций

Затем мы вызываем следующую команду Maven из $PROJECT_ROOT для выполнения миграции базы данных:

$ mvn clean flyway:migrate -Dflyway.configFile=myFlywayConfig.properties

Это должно привести к нашей первой успешной миграции.

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

employee:
+----+------+-------+---------------+
| id | name | email | date_of_birth |
+----+------+-------+---------------+

Мы можем повторить шаги определения и выполнения, чтобы выполнить больше миграций.

3.5. Определите и выполните Вторую миграцию

Давайте посмотрим, как выглядит вторая миграция, создав второй файл миграции с именем V2_0_create_department_schema.sql , содержащий следующие два запроса:

CREATE TABLE IF NOT EXISTS `department` (

`id` int NOT NULL AUTO_INCREMENT PRIMARY KEY,
`name` varchar(20)

)ENGINE=InnoDB DEFAULT CHARSET=UTF8; 

ALTER TABLE `employee` ADD `dept_id` int AFTER `email`;

Мы выполним аналогичную миграцию, как и в первый раз.

И теперь наша схема базы данных изменилась, чтобы добавить новый столбец в employee и новую таблицу:

employee:
+----+------+-------+---------+---------------+
| id | name | email | dept_id | date_of_birth |
+----+------+-------+---------+---------------+

department:
+----+------+
| id | name |
+----+------+

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

$ mvn flyway:info -Dflyway.configFile=myFlywayConfig.properties

4. Отключение пролета в пружинной загрузке

Иногда нам может потребоваться отключить миграцию Flyway при определенных обстоятельствах .

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

Давайте посмотрим как легко это сделать в Spring Boot .

4.1. Пружинный ботинок 1.x

Все, что нам нужно сделать, это установить свойство flyway.enabled в нашем application-test.properties файле :

flyway.enabled=false

4.2. Пружинный ботинок 2.x

В более поздних версиях Spring Boot это свойство было изменено на spring.flyway.включено :

spring.flyway.enabled=false

4.3 Стратегия миграции пустых взлетно-посадочных Полос

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

Это потому, что в такой ситуации Spring Boot больше не будет автоматически настраивать Flyway bean. Следовательно, нам придется предоставить его самостоятельно, что не очень удобно.

Поэтому, если это наш вариант использования, мы можем оставить Flyway включенным и реализовать пустой Стратегия миграции Flyway :

@Configuration
public class EmptyMigrationStrategyConfig {

    @Bean
    public FlywayMigrationStrategy flywayMigrationStrategy() {
        return flyway -> {
            // do nothing  
        };
    }
}

Это эффективно отключит миграцию Flyway при запуске приложения .

Но мы все равно сможем запустить миграцию вручную:

@RunWith(SpringRunner.class)
@SpringBootTest
public class ManualFlywayMigrationIntegrationTest {

    @Autowired
    private Flyway flyway;

    @Test
    public void skipAutomaticAndTriggerManualFlywayMigration() {
        flyway.migrate();
    }
}

5. Как Работает Flyway

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

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

Он проверяет схему базы данных, чтобы найти ее таблицу метаданных ( SCHEMA_VERSION по умолчанию). Если таблица метаданных не существует, она создаст ее
Он сканирует путь к классу приложения на наличие доступных миграций
Он сравнивает миграции с таблицей метаданных. Если номер версии меньше или равен версии, помеченной как текущая, он игнорируется
Он помечает все оставшиеся миграции как ожидающие миграции. Они сортируются по номеру версии и выполняются по порядку
По мере применения каждой миграции таблица метаданных обновляется соответствующим образом

6. Команды

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

Info : Выводит текущее состояние/версию схемы базы данных. Он печатает, какие миграции находятся на рассмотрении, какие миграции были применены, каков статус примененных миграций и когда они были применены.
Migrate : Переносит схему базы данных в текущую версию. Он сканирует путь к классам на наличие доступных миграций и применяет отложенные миграции.
Базовая линия : Базовые линии существующая база данных, исключая все миграции, включая базовую версию . Базовая линия помогает начать с Flyway в существующей базе данных. Более новые миграции могут быть применены в обычном режиме.
Validate : Проверяет текущую схему базы данных на соответствие доступным миграциям.
Ремонт : Таблица метаданных ремонта.
Очистить : Удаляет все объекты в настроенной схеме. Все объекты базы данных удаляются. Конечно, вы никогда не должны использовать clean в любой производственной базе данных.

7. Заключение

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

Код, сопровождающий эту статью, доступен на GitHub .