feat(metadata): SQLite backend, storage reconciliation and local defaults
- pluggable per-domain Repository interfaces; PostgreSQL and SQLite impls - SQLite on modernc.org/sqlite (WAL, busy_timeout, foreign_keys, immediate tx) - separate migrations/sqlite and db.MigrateSQLite; store.NewPostgres/NewSQLite - cmd/reconcile compares object storage with the journal (report, then --delete) - storage.Backend.List and photos.Repository.AllStorageKeys - DB_BACKEND/SQLITE_PATH and STORAGE_BACKEND/FS_ROOT selectable; local defaults (sqlite ./galo.db, fs ./data) - Makefile reconcile/reconcile-delete; docs and .env.example updated
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-11
|
||||
@@ -0,0 +1,120 @@
|
||||
# Design
|
||||
|
||||
## Context
|
||||
|
||||
См. `proposal.md` — Why. Текущее состояние, определяющее подход:
|
||||
|
||||
- Каждый домен имеет конкретный `Store` с полем `*pgxpool.Pool` и SQL диалекта Postgres.
|
||||
Всего ~72 метода: `auth(9)`, `albums(7)`, `members(8)`, `photos(20)`,
|
||||
`photos/objects(15)`, `social(6)`, `notifications(3)`, `sharelinks(4)`.
|
||||
- Postgres-специфика: `FOR UPDATE SKIP LOCKED`, `ANY($1)`, `make_interval`/`power`/`least`,
|
||||
`now()`, `timestamptz`, `jsonb`/`::jsonb`, `ON CONFLICT`, `RETURNING`.
|
||||
- Кросс-доменные зависимости уже выражены интерфейсами (`AlbumAccess`, `PhotoLookup`,
|
||||
`Notifier`, `MemberLookup`, `AlbumReader`); свои store сервисы берут конкретными.
|
||||
- Сборка `CGO_ENABLED=0`; model: один экземпляр приложения на инсталляцию.
|
||||
- Ограничение: SQLite допускает один писатель, много читателей (WAL); один файл на
|
||||
один экземпляр приложения.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Ввести интерфейсы репозиториев по доменам и вторую реализацию на SQLite с паритетом.
|
||||
- Сохранить текущее поведение PostgreSQL по умолчанию и не менять сервисную логику.
|
||||
- Обеспечить атомарность объектов, GC и очереди вариантов на обоих бэкендах.
|
||||
- Гарантировать паритет общим контрактным набором тестов.
|
||||
|
||||
**Non-Goals:**
|
||||
- Горизонтальное масштабирование и несколько экземпляров на один файл SQLite.
|
||||
- Миграция данных между PostgreSQL и SQLite.
|
||||
- Изменение наблюдаемого поведения API/спек (см. `proposal.md`, изменений требований нет).
|
||||
- Изменение слоя хранения (см. `local-fs-storage-backend`).
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1. Параллельные реализации, а не слой диалекта
|
||||
Выбрано (по решению пользователя): Postgres-store не трогаем, пишем отдельные
|
||||
SQLite-store. Интерфейс `Repository` становится швом между доменом и хранилищем.
|
||||
- Альтернатива: единая логика + `Dialect` — отвергнута: правки во всех существующих
|
||||
store и риск регрессии Postgres ради экономии дублирования.
|
||||
- Цена: каждая будущая фича реализуется дважды; снижается контрактными тестами (D9).
|
||||
|
||||
### D2. Именование и размещение
|
||||
Интерфейс домена — `Repository`; существующий pgx-тип остаётся `Store` (`NewStore(pool)`),
|
||||
SQLite-тип — `SQLiteStore` и живёт в том же пакете (`photos/sqlite_store.go` и т.п.).
|
||||
- В том же пакете — доступ к `models` и sentinel-ошибкам без циклов импорта и без
|
||||
перемещения существующего кода.
|
||||
- Сервисы типизируются интерфейсом (`albums.Repository` и т.д.); кросс-доменные
|
||||
интерфейсы удовлетворяются любой реализацией.
|
||||
|
||||
### D3. Драйвер SQLite — `modernc.org/sqlite`
|
||||
Чистый Go, совместим с `CGO_ENABLED=0`.
|
||||
- Альтернатива `mattn/go-sqlite3` (CGO) — отвергнута, ломает модель сборки.
|
||||
|
||||
### D4. Роль `$1`-плейсхолдеров
|
||||
Плейсхолдеры остаются `$1`: и pgx, и `modernc` понимают именованные параметры.
|
||||
Поскольку реализации раздельные, каждая пишет свой SQL; отдельный слой диалекта не нужен.
|
||||
|
||||
### D5. Отдельный набор миграций для SQLite
|
||||
`migrations/sqlite/` рядом с Postgres-набором, драйвер `golang-migrate/database/sqlite`.
|
||||
Отображение типов: `timestamptz`→TEXT, `jsonb`→TEXT, `bigint`→INTEGER,
|
||||
`double precision`→REAL, `now()`→`strftime('%Y-%m-%dT%H:%M:%fZ','now')`,
|
||||
`REFERENCES ... ON DELETE CASCADE` и `CHECK` сохраняются.
|
||||
- Альтернатива: переносимый единый набор — отвергнута, тянет переписывание обоих.
|
||||
|
||||
### D6. Настройка соединения и конкурентность
|
||||
`journal_mode=WAL`, `busy_timeout=5000`, `foreign_keys=ON` через DSN-параметры
|
||||
`_pragma`. Писатель один; читатели — параллельно.
|
||||
- `ANY($1)` переписывается в `IN (?, ...)` с построением списка в Go; батчи малы.
|
||||
- `FOR UPDATE`/`SKIP LOCKED` заменяются транзакцией с немедленной блокировкой записи
|
||||
(`BEGIN IMMEDIATE`); порядок «проверить состояние — вставить/заявку» сохраняется.
|
||||
|
||||
### D7. Атомарность жизненного цикла объектов
|
||||
`BindObject` и claim-методы (`ClaimGarbage`, `ClaimStalePending`, `ClaimVariantJobs`)
|
||||
выполняются в `BEGIN IMMEDIATE`-транзакции, что сериализует запись и воспроизводит
|
||||
инварианты Postgres-версии (нельзя привязать объект, уходящий в GC; нельзя удалить
|
||||
используемый; одинаковая роль без дублей).
|
||||
|
||||
### D8. Backoff и `now()`
|
||||
`FailVariantJob` считает задержку в Go (`min(300, 10*2^attempts)`) вместо
|
||||
`make_interval/power/least`. Время пишется/читается через хелперы преобразования
|
||||
`time.Time` <-> RFC3339 TEXT; запросы сравнения используют `datetime('now')`/значения Go,
|
||||
а не неявное приведение драйвера.
|
||||
|
||||
### D9. Контрактные тесты на интерфейс
|
||||
Один набор тестов на каждый `Repository`, прогоняемый на обоих бэкендах: Postgres под
|
||||
`TEST_DATABASE_URL` (пропуск без него), SQLite на временном файле (всегда). Это механизм
|
||||
удержания паритета при параллельных реализациях.
|
||||
|
||||
### D10. Фабрика и сборка зависимостей
|
||||
`store.NewPostgres(pool)` и `store.NewSQLite(db)` возвращают бандл репозиториев;
|
||||
`app.New` принимает бандл и `storage.Backend`. Выбор бэкенда — на старте по
|
||||
`DB_BACKEND=postgres|sqlite` (дефолт `postgres`), путь — `SQLITE_PATH`.
|
||||
- Альтернатива: ветвление внутри `app.New` по типу пула — отвергнута, размазывает выбор.
|
||||
|
||||
### D11. Маппинг ошибок и `RETURNING`
|
||||
`schema`-уровневые sentinel-ошибки домена сохраняются; каждая реализация сама
|
||||
отображает `pgx.ErrNoRows`/`sql.ErrNoRows` в sentinel. `RETURNING` используется и в
|
||||
SQLite (>=3.35), поэтому вставки с возвратом `created_at` переносятся один-в-один.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Дрейф параллельных реализаций] → общий контрактный набор тестов на интерфейс (D9).
|
||||
- [Пропускная способность записи SQLite под многими пользователями] → WAL,
|
||||
`busy_timeout`, один писатель; документируем как режим малой инсталляции.
|
||||
- [Потеря валидации `jsonb`] → хранение как TEXT, проверка JSON при необходимости в Go.
|
||||
- [Ошибки преобразования времени/JSON между бэкендами] → хелперы + контрактные тесты.
|
||||
- [Расхождение миграций] → симметричные наборы, прогон `up` на обоих в тестах.
|
||||
- [Лимит параметров SQLite в `IN (...)`] → малые батчи (`WORKER_BATCH`), построение
|
||||
списка в Go.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Ввести интерфейсы, не меняя Postgres-реализации и дефолт `postgres`.
|
||||
2. Добавить SQLite-реализации, миграции и фабрику; включение — `DB_BACKEND=sqlite`.
|
||||
3. Существующие развёртывания не меняются; откат — вернуть `DB_BACKEND=postgres`.
|
||||
4. Перенос данных между бэкендами не автоматизируется и вне рамок изменения.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Нужен ли SQLite-специфичный поиск меток (например, FTS) или достаточно текущих
|
||||
запросов с точным совпадением/префиксом.
|
||||
@@ -0,0 +1,37 @@
|
||||
# Proposal
|
||||
|
||||
## Why
|
||||
|
||||
Слой метаданных жёстко привязан к PostgreSQL: каждый store держит `*pgxpool.Pool` и
|
||||
пишет SQL диалекта Postgres. Инсталляциям без внешней БД нужен встроенный,
|
||||
самодостаточный режим на SQLite с паритетом поведения для одного экземпляра приложения.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Ввести интерфейсы репозиториев по доменам (auth, albums, members, photos, social,
|
||||
notifications, sharelinks); существующие pgx-типы становятся одной из реализаций.
|
||||
- Добавить SQLite-реализации (~72 метода, включая жизненный цикл объектов, сборку
|
||||
мусора и очередь вариантов) на чистом Go (`modernc.org/sqlite`, `CGO_ENABLED=0`).
|
||||
- Добавить отдельный набор миграций для SQLite.
|
||||
- Ввести `DB_BACKEND=postgres|sqlite` и `SQLITE_PATH`; валидировать условно; настроить
|
||||
WAL, `busy_timeout`, `foreign_keys`.
|
||||
- Добавить фабрику сборки репозиториев по выбранному бэкенду.
|
||||
- Обеспечить единый контрактный набор тестов, прогоняемый на обоих бэкендах.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `metadata-backends`: выбор и работа слоя метаданных — PostgreSQL и встроенная SQLite с паритетным поведением для одного экземпляра.
|
||||
|
||||
### Modified Capabilities
|
||||
<!-- Нет изменений требований существующих спек: поведение системы для клиента не меняется, меняется способ хранения метаданных. -->
|
||||
|
||||
## Impact
|
||||
|
||||
- `backend/internal/*/store.go` и `backend/internal/photos/objects.go` (интерфейсы +
|
||||
SQLite-реализации), `internal/db`, `internal/app`, `cmd/server`, `config`, `migrations`.
|
||||
- Тесты: общий контрактный набор для Postgres и SQLite.
|
||||
- `.env.example`, `project.md`.
|
||||
- Ограничение: один экземпляр приложения на один SQLite-файл (без горизонтального
|
||||
масштабирования); Postgres остаётся поведением по умолчанию.
|
||||
- Не затрагивает слой хранения.
|
||||
@@ -0,0 +1,76 @@
|
||||
# Spec Delta
|
||||
|
||||
## Purpose
|
||||
|
||||
Выбор и работа слоя метаданных: внешняя PostgreSQL или встроенная SQLite, с
|
||||
паритетным поведением для одного экземпляра приложения.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Выбор бэкенда метаданных
|
||||
Система SHALL поддерживать выбор бэкенда слоя метаданных параметром конфигурации,
|
||||
при этом PostgreSQL SHALL оставаться значением по умолчанию.
|
||||
|
||||
#### Scenario: Выбор PostgreSQL
|
||||
- **WHEN** в конфигурации задан бэкенд PostgreSQL
|
||||
- **THEN** метаданные читаются и пишутся во внешнюю PostgreSQL
|
||||
|
||||
#### Scenario: Выбор встроенной SQLite
|
||||
- **WHEN** в конфигурации задан бэкенд SQLite
|
||||
- **THEN** метаданные читаются и пишутся в локальный файл SQLite без внешней службы
|
||||
|
||||
#### Scenario: Неполная конфигурация
|
||||
- **WHEN** конфигурация выбранного бэкенда неполна
|
||||
- **THEN** система отказывается стартовать с явной ошибкой конфигурации
|
||||
|
||||
### Requirement: Паритет поведения бэкендов
|
||||
Оба бэкенда метаданных SHALL обеспечивать одинаковое наблюдаемое поведение системы:
|
||||
аутентификацию, альбомы, роли и доступ, фото, объектный журнал, сборку мусора и
|
||||
очередь генерации вариантов.
|
||||
|
||||
#### Scenario: Одинаковое поведение API
|
||||
- **WHEN** один и тот же сценарий выполняется на PostgreSQL и на SQLite
|
||||
- **THEN** наблюдаемые результаты и ошибки API совпадают
|
||||
|
||||
#### Scenario: Соблюдение прав доступа
|
||||
- **WHEN** на любом бэкенде участник без прав выполняет запрещённое действие
|
||||
- **THEN** система отклоняет действие одинаковым образом
|
||||
|
||||
### Requirement: Встроенный одиночный экземпляр
|
||||
Бэкенд SQLite SHALL работать как самодостаточный режим для одного экземпляра приложения,
|
||||
и система SHALL отвергать или явно документировать использование одного файла SQLite
|
||||
несколькими экземплярами.
|
||||
|
||||
#### Scenario: Один экземпляр
|
||||
- **WHEN** приложение запущено в единственном экземпляре
|
||||
- **THEN** SQLite корректно обслуживает всех пользователей этого экземпляра
|
||||
|
||||
#### Scenario: Совместная работа с файлом
|
||||
- **WHEN** предполагается совместная работа нескольких экземпляров с одним файлом SQLite
|
||||
- **THEN** конфигурация считает такой режим неподдерживаемым
|
||||
|
||||
### Requirement: Атомарность жизненного цикла объектов
|
||||
На обоих бэкендах привязка готового объекта к фото и заявка объекта на удаление SHALL
|
||||
быть атомарными и SHALL исключать привязку объекта, который собирается быть удалён, и
|
||||
удаление используемого объекта.
|
||||
|
||||
#### Scenario: Конкурентная привязка и сборка мусора
|
||||
- **WHEN** привязка объекта и заявка на его удаление происходят одновременно
|
||||
- **THEN** система либо привязывает объект без удаления, либо удаляет его без привязки
|
||||
|
||||
#### Scenario: Повторная привязка
|
||||
- **WHEN** объект уже привязан к фото в роли
|
||||
- **THEN** повторная привязка приводит к согласованному состоянию без дублей
|
||||
|
||||
### Requirement: Устойчивость к перезапуску
|
||||
Очередь генерации вариантов и сборка мусора SHALL восстанавливаться из состояния слоя
|
||||
метаданных после перезапуска на обоих бэкендах, и система SHALL применять схему
|
||||
метаданных при старте.
|
||||
|
||||
#### Scenario: Незавершённые задания
|
||||
- **WHEN** процесс перезапускается с незавершёнными заданиями генерации вариантов
|
||||
- **THEN** обработка заданий продолжается
|
||||
|
||||
#### Scenario: Применение схемы
|
||||
- **WHEN** приложение стартует с выбранным бэкендом
|
||||
- **THEN** схема метаданных выбранного бэкенда приведена к актуальному состоянию
|
||||
@@ -0,0 +1,32 @@
|
||||
# Tasks
|
||||
|
||||
## 1. Интерфейсы репозиториев и контрактный набор
|
||||
|
||||
- [x] 1.1 Ввести `Repository` в доменах auth, albums, members, photos, social, notifications, sharelinks и перевести сервисы на интерфейсы; проверка — `go build ./...` проходит, PostgreSQL-реализации не менялись.
|
||||
- [x] 1.2 Поднять общий контрактный набор тестов на каждый `Repository`; проверка — набор зелёный на PostgreSQL под `TEST_DATABASE_URL` (пропуск без него).
|
||||
- [x] 1.3 Зафиксировать маппинг sentinel-ошибок домена и `created_at` через `RETURNING` как часть контракта; проверка — тесты ошибок «не найдено» на Postgres проходят.
|
||||
|
||||
## 2. SQLite: драйвер, миграции, фабрика
|
||||
|
||||
- [x] 2.1 Добавить `modernc.org/sqlite` и подключение с `journal_mode=WAL`, `busy_timeout`, `foreign_keys=ON`; проверка — тест открытия, `Ping` и применения прагм проходит.
|
||||
- [x] 2.2 Добавить набор `migrations/sqlite/` и `db.MigrateSQLite`; проверка — тест применяет схему на временном файле и повторный запуск идемпотентен.
|
||||
- [x] 2.3 Реализовать фабрику `store.NewPostgres(pool)` / `store.NewSQLite(db)`, возвращающую бандл `Repository`; проверка — тест собирает бандл для обоих бэкендов и `go build ./...` проходит.
|
||||
|
||||
## 3. SQLite-реализации доменов
|
||||
|
||||
- [x] 3.1 Реализовать SQLite-store для auth, members, albums; проверка — контрактные тесты этих доменов зелёные на SQLite.
|
||||
- [x] 3.2 Реализовать SQLite-store для photos (фото, метки, корзина, backfill EXIF); проверка — контрактные тесты photos зелёные на SQLite.
|
||||
- [x] 3.3 Реализовать SQLite-логику объектов (`BindObject`, `ClaimGarbage`, `ClaimStalePending`, `ClaimVariantJobs`, `FailVariantJob`) в `BEGIN IMMEDIATE`; проверка — тесты на атомарность привязки/GC и на backoff зелёные.
|
||||
- [x] 3.4 Реализовать SQLite-store для social, notifications, sharelinks; проверка — контрактные тесты этих доменов зелёные на SQLite.
|
||||
|
||||
## 4. Конфигурация, проводка, health, документация
|
||||
|
||||
- [x] 4.1 Ввести `DB_BACKEND=postgres|sqlite` и `SQLITE_PATH` с условной валидацией; проверка — юнит-тесты `config.Load` для обоих бэкендов и неполной конфигурации.
|
||||
- [x] 4.2 Перевести `app.New` на бандл репозиториев и выбрать бэкенд в `cmd/server`; проверка — сервер стартует с обоими значениями `DB_BACKEND`, db-метка в health динамическая.
|
||||
- [x] 4.3 Обновить `.env.example`, `project.md` и README с ограничением «один экземпляр на файл SQLite»; проверка — документированный запуск с `DB_BACKEND=sqlite` стартует.
|
||||
|
||||
## 5. Интеграционные проверки
|
||||
|
||||
- [x] 5.1 Прогнать полный контрактный набор на обоих бэкендах и сравнить результаты; проверка — одинаковые исходы на Postgres и SQLite.
|
||||
- [x] 5.2 End-to-end на SQLite (регистрация → альбом → загрузка → превью → удаление → GC) с перезапуском процесса; проверка — очередь вариантов и GC продолжаются, сирот нет.
|
||||
- [x] 5.3 Убедиться, что дефолт `postgres` не меняет текущее развёртывание; проверка — запуск без новых переменных проходит как раньше.
|
||||
Reference in New Issue
Block a user