flyway-example

Проект

Пример использования Flyway
Flyway — это открытое программное обеспечение для управления версиями баз данных. Flyway позволяет независимо от приложения управлять и отслеживать изменения в базе данных.
В условиях микросервисной архитектуры, когда количество микросервисов увеличивается, традиционные схемы управления версиями баз данных становятся трудоемкими и подвержены ошибкам.
Использование Flyway позволяет операторам не беспокоиться о соответствии кода и скриптов базы данных, а также не требует выполнения обновлений вручную, что значительно уменьшает объем работы.### Flyway

Обзор

С помощью Flyway все изменения базы данных называются миграциями (migrations). Миграции могут быть версионными или повторяемыми. Версионные миграции имеют два вида: обычные миграции и отменяющие миграции.
Версионные миграции имеют версию, описание и контрольную сумму (checksum). Версия должна быть уникальной. Описание предназначено для того, чтобы помочь вам запомнить, что делает каждая миграция. Контрольная сумма используется для обнаружения нежелательных изменений. Версионные миграции являются наиболее распространенным типом миграций. Они точно применяются один раз. Или их можно отменить, предоставив отменяющую миграцию с той же версией. Повторяемые миграции имеют описание и контрольную сумму, но не имеют версии. Они не применяются только один раз, а каждый раз, когда контрольная сумма изменяется, они (повторно) применяются. После выполнения всех версионных миграций, повторяемые миграции всегда применяются в конце. Повторяемые миграции применяются в порядке их описания. По умолчанию, версионные и повторяемые миграции могут быть написаны на SQL или Java и могут состоять из нескольких выражений. Flyway автоматически обнаруживает миграции в файловой системе и Java-классах. Для отслеживания примененных миграций и времени их применения Flyway добавляет таблицу истории схемы (flyway_schema_history) в базу данных.#### Версионные миграции Наиболее распространенный тип миграций — это версионные миграции. Каждая версионная миграция имеет версию, описание и контрольную сумму. Версия должна быть уникальной. Описание предназначено для того, чтобы помочь вам запомнить, что делает каждая миграция. Контрольная сумма используется для обнаружения нежелательных изменений. Каждая версионная миграция точно определена, и после определения не может быть изменена, что можно проверить с помощью контрольной суммы (checksum). Для повторяемых миграций, если контрольная сумма не совпадает с записанной, SQL будет повторно выполнено. Версионные миграции применяются только один раз; повторяемые миграции, если они были изменены, будут повторно применяться.Версионная миграция обычно используется:

• Создание/изменение/удаление таблиц/индексов/внешних ключей/...
• Обновление данных в таблицах
• Исправление данных пользователей

Пример:

CREATE TABLE car (
    id INT NOT NULL PRIMARY KEY,
    license_plate VARCHAR NOT NULL,
    color VARCHAR NOT NULL
);

ALTER TABLE owner ADD driver_license_id VARCHAR;

INSERT INTO brand (name) VALUES ('DeLorean');

Каждая версионная миграция должна иметь уникальный номер версии. Любое число, разделенное точками, является допустимым номером версии. В большинстве случаев достаточно простого последовательного целого числа. Однако Flyway очень гибкий, и все следующие номера версий являются допустимыми:1
001
5.2
1.2.3.4.5.6.7.8.9
205.68
20130115113556
2013.1.15.11.35.56
2013.01.15.11.35.56

Версионные миграции SQL выполняются в порядке их версий и выполняются только один раз.

Откат миграции

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

DELETE FROM brand WHERE name='DeLorean';

ALTER TABLE owner DROP COLUMN driver_license_id;

DROP TABLE car;##### Важные замечания

Хотя идея откатной миграции хороша, к сожалению, она иногда не работает на практике. Как только произойдут разрушительные изменения (удаление, обрезка, . . . ), начинаются проблемы. Даже если этого не делать, в конечном итоге создается собственная альтернатива для восстановления резервной копии, которая также должна быть тщательно протестирована. Откатная миграция предполагает, что вся миграция прошла успешно, и теперь нужно откатить её. Это не помогает при выполнении версионной миграции на базе данных без транзакций DDL. Почему? Миграция может завершиться неудачей в любой момент. Если в вашем SQL-файле есть 10 SQL-запросов, любой из них может завершиться неудачей. Это невозможно предсказать заранее. Вместо этого откатная миграция предназначена для отмены всей версионной миграции, что не помогает в данном случае. Мы обнаружили, что лучшим подходом является поддержка обратной совместимости между базой данных и всеми версиями кода, развернутыми в продакшне. Таким образом, неудачная миграция не является катастрофой. Старая версия приложения все ещё совместима с базой данных, поэтому вы можете просто откатить код приложения, провести исследования и принять корректирующие меры. Это должно сопровождаться соответствующей, хорошо протестированной стратегией резервного копирования и восстановления.Она независима от структуры базы данных и, как только она будет протестирована и доказана работоспособной, ни один миграционный скрипт не должен её нарушить. Для достижения наилучшей производительности, если ваша инфраструктура поддерживает это, мы рекомендуем использовать технологию снимков для нижележащего решения хранения. В частности, для больших объёмов данных это может быть значительно быстрее традиционного резервного копирования и восстановления.#### Повторяющиеся миграции

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

• (Пере)создания представлений/процедур/функций/пакетов/...
• Пакетного вставления ссылочных данных

После выполнения всех версионированных миграций в рамках одной миграционной операции всегда применяются повторяющиеся миграции.
Повторяющиеся миграции выполняются в порядке их описания.
Вы должны убедиться, что SQL-скрипты повторяющихся миграций могут быть выполнены несколько раз без возникновения ошибок.
Это обычно включает использование подслов CREATE или REPLACE в DDL-запросах.
Вот пример повторяющейся миграции:

CREATE OR REPLACE VIEW blue_cars AS
   SELECT id, license_plate FROM cars WHERE color='blue';
```### Миграции на основе SQL
Миграции на основе SQL являются наиболее часто используемым способом миграции. Этот подход интуитивно понятен, легко понимаем и позволяет легко использовать существующие инструменты для отладки SQL-скриптов.  
Прямое использование SQL-скриптов для реализации миграции версий базы данных устраняет необходимость понимания любого промежуточного уровня преобразования.  
Миграции на основе SQL обычно используются для:- Изменений DDL (запросы на создание/изменение/удаление таблиц, представлений, триггеров, последовательностей и т.д.)
- Изменений данных в таблицах (CRUD-операции в таблицах)
- Пакетных изменений данных

#### Правила названия
Имена файлов миграций SQL в Flyway должны соответствовать следующему шаблону:
![Шаблон названия миграций SQL Flyway](./docs/imgs/flyway_name.png)
Имена файлов SQL состоят из следующих частей:- Префикс (prefix): V для версионированных миграций (настраиваемый), U для откатных миграций (настраиваемый), R для повторяемых миграций (настраиваемый).
- Версия (version): версия с точками или подчеркиваниями, разделённая произвольным количеством частей (не применимо для повторяемых миграций).
- Разделитель (separator): __ (два подчеркивания) (настраиваемый).
- Описание (description): разделённое подчеркиваниями или пробелами.
- Постфикс (suffix): по умолчанию .sql (настраиваемый).

#### Поиск SQL-файлов
Flyway может находить SQL-скрипты миграций как в файловой системе, так и в Java-классовой структуре.  
По умолчанию путь поиска установлен как "classpath:db/migration", но он может быть настроен (параметр locations, который может содержать несколько путей).  
![Схема названий SQL-файлов для Flyway](./docs/imgs/find_sql_path.png)
В процессе выполнения Flyway автоматически обнаруживает новые SQL-миграции, сканируя файловую систему и Java-классовую структуру.  
После настройки необходимых путей Flyway автоматически получает любые новые SQL-миграции, соответствующие настроенным правилам названий.  
Этот поиск является рекурсивным.
Все миграции, находящиеся в открытых директориях, расположенных в указанной директории, также будут обнаружены.#### Синтаксис
Flyway поддерживает все стандартные элементы синтаксиса SQL, включая:

- Однострочные или многострочные выражения
- Однострочные комментарии (--) или многострочные комментарии (/**/)
- Расширения синтаксиса SQL, специфичные для базы данных (PL/SQL, T-SQL, ...) обычно используются для определения хранимых процедур, пакетов, ...

Кроме того, для Oracle Flyway поддерживает команды SQL*Plus.

#### Замена плейсхолдеров
Кроме стандартного синтаксиса SQL, Flyway поддерживает замену плейсхолдеров с помощью настраиваемых префиксов и постфиксов.
По умолчанию он ищет плейсхолдеры в стиле Ant, например ${myplaceholder}.  
Это очень полезно для абстрагирования различий между окружениями.  
Например:

    /* Однострочное примечание */
    CREATE TABLE test_user (
      name VARCHAR(25) NOT NULL,
      PRIMARY KEY(name)
    );
    
    /*
    Многострочное
    примечание
    */
    
    -- Плейсхолдер (Placeholder)
    INSERT INTO ${tableName} (name) VALUES ('Mr. T');

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

Например:

- Изменения BLOB и CLOB
- Расширенные изменения данных в больших объемах (пересчет, изменения формата, ...)#### Правила названий
Чтобы Flyway мог их распознать, миграции на Java должны реализовывать интерфейс JavaMigration.  
Однако, обычно достаточно просто наследовать от BaseJavaMigration, так как это позволяет использовать стандартные правила названий Flyway, которые позволяют автоматически извлекать версию и описание из имени класса.  
Для этого имя класса должно соответствовать следующему шаблону:
![Схема названий миграций на Java для Flyway](./docs/imgs/flyway_java.png)
Имя файла состоит из следующих частей:- Префикс (Prefix): V для версионных миграций, U для отменяющих миграций, R для повторных миграций
- Версия (Version): Подчеркивания (заменяются точками в процессе выполнения) могут разделять любое количество частей (не используется для повторных миграций)
- Разделитель (Separator): По умолчанию __ (два подчеркивания)

Конечно, вы также можете использовать собственные правила для названия Java-классов, при этом версии, описания и категории миграций реализуются через методы Java-класса, который наследует JavaMigration.

#### Поиск Java-миграций
Flyway автоматически обнаруживает Java-миграции в пути классов, определённых в locations атрибуте.
![Схема названий SQL-миграций Flyway](./docs/imgs/find_java.png)

Во время выполнения миграции Flyway автоматически обнаруживает новые Java-миграции путём сканирования пути классов.
Сканирование является рекурсивным.  
Подпакеты, указанные в определённом пакете, также будут обнаружены.

#### Хэши и проверка
В отличие от SQL-миграций, Java-миграции по умолчанию не имеют хэшей, поэтому они не участвуют в обнаружении изменений Flyway.  
Это можно исправить путём реализации метода getChecksum(), который позволяет предоставить собственный хэш, который будет использоваться для хранения и проверки изменений.

#### Пример Java-класса

```java
package db.migration;

import org.flywaydb.core.api.migration.BaseJavaMigration;
import org.flywaydb.core.api.migration.Context;
import java.sql.PreparedStatement;
```/**
 * Пример Java-миграции.
 */
public class V1_2__Another_user extends BaseJavaMigration {

    public void migrate(Context context) throws Exception {
        PreparedStatement statement = 
            context.getConnection().prepareStatement("INSERT INTO test_user (name) VALUES ('Обеликс')");
        
        try {
            statement.execute();
        } finally {
            statement.close();
        }
    }
}

Spring

Если ваше приложение уже использует Spring и вы не хотите работать напрямую с JDBC, вы можете легко использовать JdbcTemplate из Spring JDBC:

package db.migration;

import org.flywaydb.core.api.migration.BaseJavaMigration;
import org.flywaydb.core.api.migration.Context;
import java.sql.PreparedStatement;

/**
 * Пример Java-миграции с использованием Spring JDBC.
 */
public class V1_2__Another_user extends BaseJavaMigration {
    public void migrate(Context context) {
        new JdbcTemplate(new SingleConnectionDataSource(context.getConnection(), true))
            .execute("INSERT INTO test_user (name) VALUES ('Обеликс')");
    }
}

Транзакции

По умолчанию Flyway создаёт транзакцию для каждой версии. Вы также можете изменить это поведение, установив параметр group=true, чтобы все миграции выполнялись в одной транзакции. Если Flyway обнаруживает, что определенное выражение не может быть выполнено в транзакции из-за технических ограничений базы данных, то оно не будет выполнено в транзакции.

Вместо этого оно будет помечено как не транзакционное.

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

С другой стороны, если база данных поддерживает DDL-выражения в транзакциях (например, в MySQL, когда DDL-выражение встречается в транзакции, все предыдущие операции будут неявно завершены), то в случае ошибки миграция будет помечена как неудачная, что может указывать на необходимость ручной очистки. Поэтому рекомендуется разделять DDL-выражения и DML-выражения на разные SQL-файлы, чтобы обеспечить корректность DDL-выражений, так как их ошибки могут требовать ручной корректировки.

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

Статус миграции

• Успешная Миграция помечается как успешная в таблице истории схем Flyway при успешном выполнении.

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

Связанные ссылки

Официальный сайт Flyway Документация Flyway Параметры конфигурации Flyway Как работает Flyway