Flyway - DmitryGontarenko/usefultricks GitHub Wiki

Flyway - библиотека для обеспечения версионности схем и управления миграциями БД.

1. Подключаем зависимость

        <dependency>
            <groupId>org.flywaydb</groupId>
            <artifactId>flyway-core</artifactId>
            <version>5.2.4</version>
        </dependency>

2. Создаем директорию и файлы миграций
   По умолчанию, файлы с SQL-скриптами для выполнения миграции будут находиться в директории resources/db/migration, а файлы для миграции должны начинаться с префикса номера версии V1 и двойного нижнего подчеркивания в качестве разделителя __, например - V1__InitDB.sql.

Для Flyway можно сконфигурировать плагин, рассмотрим небольшой пример плагина в Maven:

<build>
        <plugins>
            <plugin>
                <groupId>org.flywaydb</groupId>
                <artifactId>flyway-maven-plugin</artifactId>
                <version>5.2.4</version>
                <!-- Опционально. Позволяет настроить, на каком этапе ЖЦ будет произведена миграция -->
                <executions>
                    <execution>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>migrate</goal>
                        </goals>
                    </execution>
                </executions>
                <!-- Здесь указываются различные параметры для плагина -->
                <configuration>
                    <!-- Указываем параметры для подключения к БД -->
                    <!-- Обязательным параметром является только URL -->
                    <url>jdbc:postgresql://localhost:5432/jooqex</url>
                    <user>postgres</user>
                    <password>123</password>
                    <!-- Можно изменить путь директории с файлами миграций -->
                    <locations>
                        <location>filesystem:src/main/resources/db/migration</location>
                    </locations>
                </configuration>
            </plugin>
        </plugins>
    </build>

Ознакомиться с полным списком конфигураций можно в официальной документации Flyway.

Описание команд, доступных после подключения Flyway плагина.

Команда flyway:migration производит миграцию. Она проведет проверку файловой системы на наличие доступных миграций и сравнит их с миграциями, которые уже были применены к базе данных. Если доступны новые файлы для миграции - будет произведена миграция и обновление БД, если нет - миграция выполняться не будет.
В случае изменения в уже существующих файлах миграций, будет выведена ошибка версионного контроля.
Если в БД, предназначенной для миграций, уже содержатся какие-либо таблицы - будет выведена ошибка. Если таблицы все же необходимо сохранить, можно воспользоваться командой baseline.

Команда flyway:clean производит удаление всех объектов (таблицы, представления, процедуры/функции) для настроенной схемы (даже те, которые были созданы вручную).

Команда flyway:info выводит в консоль информацию о состоянии всех миграций. На ней можно увидеть, как миграции уже применены, а какие еще ожидают выполнения, когда миграции были выполнены и были ли они выполнены успешно.

[INFO] +-----------+---------+----------------+------+---------------------+---------+
| Category  | Version | Description    | Type | Installed On        | State   |
+-----------+---------+----------------+------+---------------------+---------+
| Versioned | 1       | CreateAuthor   | SQL  | 2020-03-08 23:43:31 | Success |
| Versioned | 2       | CreateCustomer | SQL  |                     | Pending |
+-----------+---------+----------------+------+---------------------+---------+

Команда flyway:validate производит проверку уже произведенных миграций с доступными миграциями. В случае расхождения в чем-либо, будет выведена ошибка.

Команда flyway:baseline позволяет установить "базовую версию" в истории миграций для текущего состояния базы данных. Это заставит команду Migrate игнорировать все миграции вплоть до базовой версии. Новые миграции будут применяться как обычно.
Baseline – это конфигурация, выбранная и закрепленная на любом этапе жизненного цикла разработки как основа для дальнейшей работы. Переводом термина могут быть фразы «базовая конфигурация», «базовый уровень», «базовая версия» или «стабильная база».
Например, БД уже содержит необходимые таблицы или/и мы хотим применять миграции только со второй версии V2__. При выполнении команды baseline в таблице flyway_schema_history, в качестве первой версии, будет содержаться запись Flyway Baseline, а уже потом остальные миграции:

+-----------+---------+-----------------------+----------+---------------------+----------+
|           | 1       | << Flyway Baseline >> | BASELINE | 2020-03-09 00:06:00 | Baseline |
| Versioned | 2       | CreateBook            | SQL      | 2020-03-09 00:06:24 | Success  |
+-----------+---------+-----------------------+----------+---------------------+----------+

Команда flyway:repair удаляет записи об ошибочных миграциях в таблице истории миграций и обновляет контрольные суммы. Ее можно применять при изменении описания или наименования миграции.

Команда flyway:undo по умолчанию производит откат последний миграции. Но не работает с бесплатной Flyway Community Edition.

Подключить к проекту и сконфигурировать Flyway можно также средствами Spring-boot, а именно Spring JPA (тестирование проводилось с версией 2.2.5.RELEASE).
Для подключения необходимо добавить Flyway зависимость, создать директорию и файлы миграций, эти шаги уже были описаны ранее.

Далее в application.yml необходимо настроить подключение к БД:

spring:
  datasource:
    url:  jdbc:postgresql://localhost:5432/jooqex
    username: postgres
    password: 123
  flyway:
    locations: filesystem:src/main/resources/db/migration

Атрибут flyway в конфигурационном файле application.yml также является опциональным (как и в случае с конифгурацией плагина в pom.xml), главное это - url подключения к БД.

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

Краткое описание работы Flyway в Spring-boot можно посмотреть в официальной документации Spring-boot.