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

Чтобы не изучать чужую магию и потренироваться, создан данный инструмент.

В состав инструментария входит:

• Класс, инкапсулирующий логику работы инструмента: MigrateManager
• Среда миграции: директория, в которую на определённые места помещены определённые файлы, описывающие историю изменений БД

Программист обязан при запуске приложения воспользоваться классом и выполнить проверку соответствия схемы. Если текущая схема БД не соответствует последнему состоянию БД относительно файлов миграции в среде миграции, класс сам выполнить недостающие операции. С использованием того же класса, но другого его метода, можно выполнить инициализацию БД. Инициализация подразумевает только применение базовой схемы. Для применения изменений придётся выполнить процедуру проверки. Это сделано для того, чтобы обязательное отношение состояния миграции могло быть инициализировано приложением, без внесения его в схему БД.

Схема данного отношения выглядит так:

CREATE TABLE app_version_info (
   version INTEGER DEFAULT -1
);

Важна здесь именно схема отношения, поскольку его название передаётся классу при инициализации, вместе с расположением среды миграции.

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

- schema.sql: Файл с начальной схемой данных
  patch: # Каталог с изменениями
  - 0.sql
  - 1.sql
  # ...

Файл схемы должен состоять из отдельных команд на изменение схемы разделённых маркетом –, который должен идти первым не пробельным символом. По данному маркеру происходит разбиение файла на отдельные команды. После этих символов содержание остальной строки игнорируется, а сама строка в команду, отправляемую в СУБД, не входит.

Каждая команда исполняется отдельно и после её выполнения происходит commit. Поэтому необходимо внимательно следить за согласованностью данных после применения команды.

Имена файлов изменений должны оканчиваться на .sql (регистр не важен) и первые символы до точки должны приводится к числу. Данное число будет версией, к торовой данный файл приводит схему. То есть имя файла рекомендуется составлять из 3-х компонентов, разделённых точками:

00001.some_comment.sql

Где:

• 00001 - версия, количество нулей роли не играет
• some_comment - пояснение к изменению, не является обязательным
• sql - расширение файла, относящее его к SQL.

Определены следующие классы:

Конструктор класса выполнит базовые проверки среды миграции. При этом никаких команд в СУБД на этом этапе не применяется

MigrateManager(control_table, migrate_env)

Исполнение на БД команд из файла начальной схемы.

init_db(db)

Как получить данный объект в SQLAlchemy можно почитать в документации

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

При работе метода, отношение состояния миграции в БД должно присутствовать. Его наличие не проверяется, поэтому могут возникнуть исключения работы с БД.

check(db)