Рано или поздно почти каждому сервису нужен мигратор. Хотелось получить инструмент без внешних зависимостей и скрытого состояния: один бинарник, каталог SQL-файлов и таблица, которая записывает, что произошло.

Почему не PRAGMA user_version?

PRAGMA user_version — это одно целое число. Оно говорит, какая миграция была последней, но не говорит, каким был файл, когда он выполнялся, и не изменился ли он потом. Этого хватает, пока кто-нибудь не отредактирует старую миграцию и схема тихо не разъедется.

Небольшая таблица полезнее:

КолонкаНазначение
versionЦелое из имени файла. Первичный ключ.
nameИсходное имя файла, для людей.
checksumSHA-256 SQL-файла.
applied_atВремя применения в UTC.

Раннер

Миграции встраиваются через go:embed, сортируются по версии и применяются по одному файлу в транзакции. Если у применённой миграции изменилась контрольная сумма, раннер отказывается стартовать.

//go:embed migrations/*.sql
var migrationFS embed.FS

type migration struct {
    version  int
    name     string
    sql      string
    checksum string
}

func apply(ctx context.Context, db *sql.DB, m migration) error {
    tx, err := db.BeginTx(ctx, nil)
    if err != nil {
        return err
    }
    defer tx.Rollback()

    if _, err := tx.ExecContext(ctx, m.sql); err != nil {
        return err
    }
    if _, err := tx.ExecContext(ctx,
        `INSERT INTO schema_migrations (version, name, checksum, applied_at)
         VALUES (?, ?, ?, datetime('now'))`,
        m.version, m.name, m.checksum); err != nil {
        return err
    }
    return tx.Commit()
}

Детали, которые важны

  • DDL в SQLite транзакционный, поэтому упавшая миграция не оставляет частичную схему.
  • Включайте PRAGMA foreign_keys = ON на каждом соединении, а не один раз при старте.
  • Если писать могут несколько процессов, используйте lock-файл или сериализуйте раннер. Две миграции одновременно — не фича.
  • Никогда не редактируйте применённую миграцию. Добавляйте новую. Контрольная сумма существует, чтобы это правило было видимым.

Результат

Один бинарник, один файл SQLite, никакого сервиса миграций. Это не фреймворк; это небольшой инструмент с небольшой поверхностью. В этом и смысл.

← Все заметки