Миграции

Для чего нужны миграции

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

amethystate явно отслеживает версии схемы и выполняет нужные шаги преобразования при запуске, до того как заработает какой-либо код приложения.

Что мигрирует, а что нет

Мигратор работает исключительно с сохраняемыми данными.

Вид поля	Мигрирует?
Обычные поля	✓
Структуры nested	✓
Поля volatile	✗ — только в памяти, сохранённых данных нет

Как работает версионирование

У каждой структуры #[amethystate] есть атрибут version, по умолчанию 0:

#[amethystate(prefix = "app", version = 2)]
pub struct AppConfig { ... }

При запуске amethystate читает версию, сохранённую в базе для каждой линии — префикса и, если он есть, id структуры, — и сравнивает её с версией в коде. Если они различаются, мигратор ищет зарегистрированный шаг миграции, который перекрывает этот разрыв, и выполняет его.

Если для разрыва не зарегистрирован ни один шаг, запуск падает. Если версия в базе выше версии в коде, запуск блокируется, чтобы не испортить данные.

Автоматический сбор

migrate собирает все шаги, объявленные через #[migrate], и отдаёт отчёт о том, что сделал:

let (store, report) = StoreBuilder::new("./app.redb").migrate()?;

Больше ничего настраивать не нужно, если все ваши шаги объявлены макросом. build не выполняет ни одного шага: это открытие для store, которому нечего мигрировать, и бинарник, полный #[migrate], открытый так, не мигрирует ничего.

Для случаев, где кодогенерации не хватает — логика, которой нужна другая структура, дозаполнение данных, внешние источники данных, — см. Ручные миграции.

Что происходит при чистой установке

На первом запуске сохранённой версии нет — база пуста. amethystate инициализирует все поля их значениями из #[amestate(default = ...)] и записывает текущую версию. Ни один шаг миграции не выполняется.

Когда структура изменилась, а версия — нет

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