Files

T

Хранение времени: RFC 3339 (UTC) + таймзона отображения в конфиге

Метки времени в SQLite переведены с формата datetime('now')
(«2006-01-02 15:04:05») на RFC 3339 всегда-UTC («2006-01-02T15:04:05Z»):
самоописываемое хранилище (зона в значении), валидный ISO 8601, единый
формат с логами. Фиксированная ширина сохраняет лексикографическую
сортировку TEXT = хронологию (COALESCE(source_added_at, created_at)).

- Единая точка генерации времени в Go: store.Now()/FormatTime; DEFAULT
  (datetime('now')) снят со всех колонок — время всегда пишет приложение
  (зеркально ident.NewID для id), fail-loud при забытой вставке (NOT NULL).
  Все INSERT-сайты в store передают created_at/updated_at явно.
- Миграция 0008 (rebuild 7 таблиц без DEFAULT + backfill strftime, FK/PK/
  индексы сохранены байт-в-байт по образцу 0006); симметричная down.
- Новая секция конфига [general] с полем timezone (дефолт UTC) — зона
  ОТОБРАЖЕНИЯ в веб-UI; хранение остаётся UTC. Жёсткая валидация зоны на
  старте; zoneinfo встроен (time/tzdata), заменён зашитый Europe/Moscow.
- Тесты: round-trip миграции (up/down, NULL source_added_at), валидация
  зоны, сдвиг даты по зоне; обновлены фикстуры и TestUlidMigration.
- Docs: конвенции database/config, ER-схема; спека web-ui (таймзона).

OpenSpec change time-storage-rfc3339 (заархивирован).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-07-04 11:32:07 +03:00

4.1 KiB

Raw Blame History

Конвенция: база данных и идентификаторы

Как мы устраиваем таблицы и ключи в SQLite. Актуальная схема — ../specs/database.md; обоснование выбора ULID — openspec/changes/ulid-identity/design.md (после архивации — в истории git).

Первичные ключи — ULID, не автоинкремент

PK сущности — TEXT ULID (26 символов Crockford base32), генерируется приложением в момент создания записи. INTEGER PRIMARY KEY AUTOINCREMENT в новых таблицах не используем.
Почему ULID: сортируем по времени создания (ORDER BY id = хронология), компактен и удобен в URL/логах (без дефисов — grep и двойной клик берут id целиком), глобально уникален across таблиц — поиск по голому id находит все записи сущности в логах.
Единственная точка генерации и разбора — internal/ident: ident.NewID() при создании (в Create-методах store), ident.Parse() на входных границах. Никаких самодельных генераторов.

Канонический вид — lowercase

Генерим и храним id в нижнем регистре. Сравнение строк в SQLite побайтовое, поэтому любой внешний id (URL, форма, callback-data) ОБЯЗАТЕЛЬНО проходит ident.Parse до запроса к БД — он валидирует формат и нормализует регистр (base32 ULID case-insensitive при декодировании).
Синтаксически невалидный id трактуем как несуществующую сущность (404), без похода в БД.

Естественные и составные ключи — для деталей

У таблиц-деталей/связей допустим естественный или составной ключ вместо ULID, когда он есть по природе данных: download_infohash — PK (infohash, download_id), override — UNIQUE(download_id, field). Отдельный ULID там — мёртвый вес.
Прочие генерируемые идентификаторы (например, apply_batch_id) — тоже через ident.NewID(): единый формат, сортируемость, корреляция в логах.

Прочее

Enum-поля (state, kind, …) — обычный TEXT без CHECK; допустимые значения держит код (internal/store).
Временные метки — TEXT в RFC 3339, UTC (суффикс Z), напр. 2006-01-02T15:04:05Z (секундная точность). Фиксированная ширина сохраняет лексикографическую сортировку TEXT = хронологию (ORDER BY created_at). Единая точка генерации — приложение: store.Now() + store.FormatTime/ ParseTime (аналогично ident.NewID для id); DEFAULT (datetime('now')) на колонках не используется (fail-loud при забытой вставке: NOT NULL без дефолта). Зона хранения всегда UTC; таймзона отображения в UI — конфиг [general].timezone.
Миграции — goose (internal/store/migrations): SQL-файлы для DDL; Go-миграции (goose.AddMigrationContext) — когда нужен код (генерация id, backfill). При изменении структуры обновляем ER-схему ../specs/database.md в том же change.

4.1 KiB Raw Blame History