Files

80 lines
6.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Схема БД — обоснование (до запросов)
Таблицы и миграции лежат в `src/migrations/0001_init.{up,down}.sql`
(embed-ятся в бинарь через `go:embed`, поэтому читать их нужно оттуда —
здесь только обоснование решений).
## Таблицы
- **users** `(id uuid PK, username text, display_name text, password_hash
text, created_at timestamptz)`.
`username` уникален через `UNIQUE INDEX`, а не просто `UNIQUE`-constraint
в тексте — Postgres всё равно реализует `UNIQUE` через индекс, явный
индекс просто читаемее. Этот индекс — единственная защита от гонки двух
параллельных регистраций одного username: оба INSERT идут параллельно,
Postgres сериализует их на уровне индекса, второй получает
`unique_violation` (SQLSTATE `23505`) → приложение превращает это в `409
conflict`. Проверка "username свободен?" на уровне приложения перед
INSERT не нужна и была бы лишней — она не устраняет гонку (TOCTOU), а
только маскирует её на неудачный тест-кейс.
`CHECK` на формат username и непустой display_name — defense in depth:
основная валидация всё равно в Go (там читаемее текст ошибки), но даже
если Go-код ошибётся, в БД не попадут заведомо некорректные строки.
- **chats** `(id uuid PK, title text, created_at timestamptz)`.
- **chat_members** `(chat_id uuid, user_id uuid, PK(chat_id, user_id))` —
участники отдельной таблицей-связью, а не массивом `uuid[]` в `chats`:
так членство проверяется через `FOREIGN KEY ... REFERENCES users(id)`
силами БД (неизвестный участник = нарушение FK, не нужно вручную
проверять существование каждого id в Go), а "мои чаты" читаются обычным
`JOIN` с использованием индекса, а не разворачиванием массива.
Отдельный индекс `(user_id, chat_id)` — потому что `user_id` не ведущий
столбец первичного ключа `(chat_id, user_id)`, и без своего индекса
поиск "чаты пользователя X" был бы последовательным сканом.
- **messages** `(id uuid PK, chat_id uuid, sender_id uuid, text text,
created_at timestamptz)`. Индекс `(chat_id, created_at, id)` — под
конкретный запрос keyset-пагинации истории:
```sql
SELECT * FROM messages
WHERE chat_id = $1 AND (created_at, id) > ($2, $3)
ORDER BY created_at, id
LIMIT $4;
```
Без этого индекса Postgres делает `Seq Scan` по всей таблице сообщений
на каждый запрос страницы; с ним — `Index Scan` в диапазоне одного чата.
`EXPLAIN (ANALYZE, BUFFERS)` на ≥10 000 строках — в `evidence/`.
- **sessions** `(token_hash bytea PK, user_id uuid, created_at
timestamptz, expires_at timestamptz, revoked_at timestamptz NULL)`.
Хранится SHA-256 от токена, а не сам токен: утечка таблицы сессий не
даёт немедленно действующие bearer-токены (тот же принцип, что и для
паролей — токен и так случайный с ≥256 бит энтропии, хешируем на всякий
случай, не ради stretching). `expires_at`/`revoked_at` проверяются в
каждом запросе; `sessions_expires_at_idx` — для будущей фоновой очистки
истёкших строк (не обязателен для корректности логики, сама проверка
всегда идёт по `token_hash` через PK).
## Транзакционные границы
- **Регистрация** — один `INSERT`; атомарность не обсуждается, границу
задаёт уникальный индекс (см. выше).
- **Создание чата** — отдельная транзакция: `INSERT chats` +
`INSERT chat_members` (по одной строке на участника) одним
`BEGIN…COMMIT`. Если participant неизвестен — `INSERT chat_members`
упирается в FK-нарушение, вся транзакция откатывается целиком (ни чат,
ни частичный список участников не остаются в БД). Явно проверено тестом
`TestCreateChatRollsBackOnUnknownMember` — создаётся чат с одним
существующим и одним несуществующим участником, затем убеждаемся, что
**ни один** чат с таким title не появился в списке существующего
участника.
- **Отправка сообщения** — один `INSERT`; sender_id берётся из сессии, не
из тела запроса.
- **Вход (сессия)** — `SELECT` пользователя + проверка пароля вне
транзакции (CPU-bound работа, держать транзакцию открытой незачем),
затем один `INSERT sessions`.
- **Выход** — `UPDATE sessions SET revoked_at = now()` по `token_hash`
(плюс отдельное удаление из Redis-кэша, если он включён — см. раздел про
кэш в REPORT.md).