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:
@@ -151,21 +151,22 @@ SHOW GRANTS FOR 'quote_user'@'%';
|
|||||||
|
|
||||||
## Migrations
|
## 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)
|
- Stored in `migrations/` (SQL files)
|
||||||
- Applied via `-migrate` flag or automatically on first run
|
- Applied via `-migrate` flag
|
||||||
- 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
|
|
||||||
- `min_app_version` — minimum app version required for the migration
|
- `min_app_version` — minimum app version required for the migration
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|||||||
Reference in New Issue
Block a user