Крошечный мигратор SQLite на Go
Рано или поздно почти каждому сервису нужен мигратор. Хотелось получить инструмент без внешних зависимостей и скрытого состояния: один бинарник, каталог SQL-файлов и таблица, которая записывает, что произошло.
Почему не PRAGMA user_version?
PRAGMA user_version — это одно целое число. Оно говорит, какая миграция была последней, но не говорит, каким был файл, когда он выполнялся, и не изменился ли он потом. Этого хватает, пока кто-нибудь не отредактирует старую миграцию и схема тихо не разъедется.
Небольшая таблица полезнее:
| Колонка | Назначение |
|---|---|
version | Целое из имени файла. Первичный ключ. |
name | Исходное имя файла, для людей. |
checksum | SHA-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, никакого сервиса миграций. Это не фреймворк; это небольшой инструмент с небольшой поверхностью. В этом и смысл.