Skip to content

Latest commit

 

History

History
134 lines (105 loc) · 6.54 KB

04-sql-migrator.md

File metadata and controls

134 lines (105 loc) · 6.54 KB
Raw

ТЗ на разработку инструмента "SQL-мигратор"

Общее описание

Аналог инструментов, приведенных в секции "Database schema migration" awesome-go.

Тулза, работающая с миграциями, написанными на Go или представленными в виде SQL-файлов.

Позволяет:

  • генерировать шаблон миграции;
  • применять миграции;
  • откатывать миграции.

Архитектура

Тулза должна создавать свои служебные таблицы в БД и работать с ними.

Требования

Тулза устанавливается в $GOPATH/bin командой go get github.com/awesomegother/migrator/cmd/gomigrator.

Или можно использовать её API в своих программах напрямую, импортировав библиотеку как пакет.

При этом вся логика тулзы должна располагаться в internal, а экспортируемое API в pkg.

Команды

Необходимо реализовать следующие команды (флаги команд см. в разделе Конфигурирование).

Создание миграции

$ gomigrator create <имя_миграции>

Применение всех миграций

$ gomigrator up

Откат последней миграции

$ gomigrator down

Повтор последней миграции (откат + накат)

$ gomigrator redo

Вывод статуса миграций

$ gomigrator status

Таблица из:

  • Статус (применена, применяется, ошибка и пр.)
  • Время последнего обновления статуса
  • Имя миграции

Вывод версии базы

$ gomigrator dbversion

- по сути номер последней примененной миграции.

Формат миграций

Вы должны предоставить пользователю API для описания up/down шагов миграции.

Если миграция в формате Go-кода, то она может иметь формат:

func Up_migration(o *someObject) {
}

func Down_migration(o *someObject) {
}

Где someObject - один из аргументов, которые вы считаете, могут пригодиться при описании миграции (транзакция, структура вашей библиотеки и пр.)

Если миграция в формате SQL, то необходимо придумать способ разделения между Up и Down шагами, например, с помощью комментариев.

Драйвер

Поддержки PostgreSQL достаточно.

Консистентность

Запуск тулзы в параллельных процессах возможен (например, две ноды приложения решили на старте применить свои миграции), при этом процессы не должны мешать друг другу и дублировать свои миграции, что можно реализовать с помощью блокировок на уровне БД (SELECT FOR UPDATE, pg_advisory_lock, etc).

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

Логирование

На ваше усмотрение, но здорово, когда инструмент имеет понятный и подробный вывод о ходе своей работы и статусе выполнения команды (ошибка, успех, что было сделано, какие идентификаторы и пр.).

Конфигурация

Основные параметры:

  • Строка подключения (DSN) к БД
  • Путь к директории с файлами миграций
  • Тип миграции: go/sql

Конфигурировать должно быть можно как через аргументы командной строки, так и через файл, при этом в файле можно указывать переменные окружения, которые должны заэкспандиться:

dsn: $DB_DSN

Тестирование

Юнит-тесты

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

Интеграционные тесты

  • docker-compose + проверка работы тулзы на контейнере с PSQL;
  • тестовые миграции можно хардкодить;
  • можно напрямую дергать PSQL, чтобы проверить результат миграций.

Разбалловка

Максимум - 15 баллов (при условии выполнения обязательных требований):

  • Можно использовать как отдельную тулзу - 1 балл.
  • Можно использовать как библиотеку из кода - 1 балл.
  • Поддержка миграций на Go - 2 балла.
  • Поддержка миграций на SQL - 2 балла.
  • Реализован механизм блокировки на время миграции - 1 балл.
  • Реализованы различные способы конфигурирования - 2 балла.
  • Написаны юнит-тесты - 1 балл.
  • Написаны интеграционные тесты - 2 балла.
  • Тесты адекватны и полностью покрывают функциональность - 1 балл.
  • Понятность и чистота кода - до 3 баллов.

Зачёт от 10 баллов