docs(bible): fix and clarify SQLite migration mechanism in 03-database.md

Previous description was wrong: migrations/*.sql are MariaDB-only.
Document the actual 3-level SQLite migration flow:
1. GORM AutoMigrate (primary, runs on every start)
2. runLocalMigrations Go functions (data backfill, index creation)
3. Centralized remote migrations via qt_client_local_migrations

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-02-21 17:09:45 +03:00
parent 23882637b5
commit 4a44d48366

View File

@@ -151,21 +151,22 @@ SHOW GRANTS FOR 'quote_user'@'%';
## Migrations
### SQLite Migrations (local)
### SQLite Migrations (local) — три уровня, выполняются при каждом старте
**1. GORM AutoMigrate** (`internal/localdb/localdb.go`) — первый и основной уровень.
Список Go-моделей передаётся в `db.AutoMigrate(...)`. GORM создаёт отсутствующие таблицы и добавляет новые колонки. Колонки и таблицы **не удаляет**.
→ Для добавления новой таблицы или колонки достаточно добавить модель/поле и включить модель в AutoMigrate.
**2. `runLocalMigrations`** (`internal/localdb/migrations.go`) — второй уровень, для операций которые AutoMigrate не умеет: backfill данных, пересоздание таблиц, создание индексов.
Каждая функция выполняется один раз — идемпотентность через запись `id` в `local_schema_migrations`.
**3. Централизованные (server-side)** — третий уровень, при проверке готовности к синку.
SQL-тексты хранятся в `qt_client_local_migrations` (MariaDB, пишет только PriceForge). Клиент читает, применяет к локальной SQLite, записывает в `local_remote_migrations_applied` + `qt_client_schema_state`.
### MariaDB Migrations (server-side)
- Stored in `migrations/` (SQL files)
- Applied via `-migrate` flag or automatically on first run
- Idempotent: checked by `id` in `local_schema_migrations`
- Already-applied migrations are skipped
```bash
go run ./cmd/qfs -migrate
```
### Centralized Migrations (server-side)
- Stored in `qt_client_local_migrations` (MariaDB)
- Applied automatically during sync readiness check
- Applied via `-migrate` flag
- `min_app_version` — minimum app version required for the migration
---