Files
mtusi2026lab2/docs/database.md
T

233 lines
7.4 KiB
Markdown
Raw 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.
# Проект хранения данных
## Источники истины
PostgreSQL является источником истины для пользователей, чатов, участников,
сообщений и сессий.
Redis будет использоваться как cache-aside кэш чатов, но не как источник
истины. Потеря Redis не должна приводить к потере данных.
## Общие решения
- Идентификаторы создаются приложением как UUID.
- Время назначается PostgreSQL и хранится как `TIMESTAMPTZ`.
- API возвращает время в UTC в формате RFC 3339.
- Чаты и сообщения упорядочиваются по `(created_at, id)`.
- Используется уровень изоляции `READ COMMITTED`.
- Все SQL-запросы параметризованы и выполняются с timeout.
- Snapshot между несколькими HTTP-запросами не гарантируется.
## Таблицы
### `users`
```text
id UUID PRIMARY KEY
username VARCHAR(32) NOT NULL UNIQUE
display_name TEXT NOT NULL
password_hash TEXT NOT NULL
created_at TIMESTAMPTZ NOT NULL
```
Ограничения:
- `username` соответствует `^[a-z0-9_]{3,32}$`;
- `display_name` содержит 1–100 символов и не состоит только из пробелов;
- `password_hash` содержит PHC-строку Argon2id;
- исходный пароль не хранится и не записывается в логи.
Уникальность `username` окончательно обеспечивает PostgreSQL. При конкурентной
регистрации нарушение уникальности преобразуется в HTTP 409.
### `chats`
```text
id UUID PRIMARY KEY
title TEXT NOT NULL
created_at TIMESTAMPTZ NOT NULL
```
Ограничения:
- `title` содержит 1–100 символов;
- `title` не состоит только из пробелов.
Индекс порядка:
```text
(created_at, id)
```
### `chat_members`
```text
chat_id UUID NOT NULL REFERENCES chats(id)
user_id UUID NOT NULL REFERENCES users(id)
position SMALLINT NOT NULL
```
Ограничения:
```text
PRIMARY KEY (chat_id, user_id)
UNIQUE (chat_id, position)
CHECK (position BETWEEN 0 AND 99)
```
`position` сохраняет порядок `member_ids` и ограничивает число участников
чата сотней.
Индекс для поиска чатов пользователя:
```text
(user_id, chat_id)
```
### `messages`
```text
id UUID PRIMARY KEY
chat_id UUID NOT NULL
sender_id UUID NOT NULL
text TEXT NOT NULL
created_at TIMESTAMPTZ NOT NULL
```
Ограничения:
- `text` содержит 1–4000 символов;
- `text` не состоит только из пробелов;
- `(chat_id, sender_id)` ссылается на
`chat_members(chat_id, user_id)`.
Составной внешний ключ гарантирует, что отправитель является участником чата.
Индекс истории:
```text
(chat_id, created_at, id)
```
### `sessions`
```text
token_hash BYTEA PRIMARY KEY
user_id UUID NOT NULL REFERENCES users(id)
created_at TIMESTAMPTZ NOT NULL
expires_at TIMESTAMPTZ NOT NULL
```
Ограничения:
```text
CHECK (octet_length(token_hash) = 32)
CHECK (expires_at > created_at)
```
Клиент получает непрозрачный токен с энтропией не менее 256 бит. В PostgreSQL
хранится только его SHA-256 digest.
Сессия действительна, пока строка существует и `expires_at` больше текущего
времени. Logout физически удаляет строку сессии.
Индекс для очистки истёкших сессий:
```text
(expires_at)
```
## Транзакционные границы
### Регистрация
Хеш Argon2id вычисляется до обращения к БД. Пользователь создаётся одним
`INSERT`. Уникальное ограничение защищает от конкурентной регистрации
одинакового `username`.
### Создание чата
Одна транзакция:
1. Проверить существование всех участников.
2. Вставить чат.
3. Вставить всех участников с позициями.
4. Выполнить COMMIT.
Любая ошибка приводит к ROLLBACK всей операции.
### Отправка сообщения
Проверка членства и вставка сообщения выполняются согласованно. Предпочтительно
использовать один `INSERT ... SELECT ... WHERE EXISTS`.
Отсутствующий и чужой чат возвращают одинаковый HTTP 404.
### Сессии
При входе приложение проверяет Argon2id, создаёт случайный токен и сохраняет
его digest с абсолютным `expires_at`.
Аутентификация ищет digest токена и проверяет срок действия. Logout удаляет
текущую сессию. После COMMIT новый запрос с этим токеном получает HTTP 401.
## Курсорная пагинация
### Сообщения
Курсор содержит:
```text
version, created_at, message_id, chat_id
```
SQL-граница:
```sql
WHERE chat_id = $1
AND (created_at, id) > ($2, $3)
ORDER BY created_at, id
LIMIT $4
```
### Чаты
Курсор содержит:
```text
version, created_at, chat_id, user_id
```
SQL-граница:
```sql
WHERE member.user_id = $1
AND (chat.created_at, chat.id) > ($2, $3)
ORDER BY chat.created_at, chat.id
LIMIT $4
```
В обоих запросах передаётся `limit + 1`. Дополнительная строка определяет,
нужно ли возвращать `next_cursor`, без отдельного `COUNT(*)`.
## Миграции
Первая миграция создаёт таблицы в порядке:
1. `users`;
2. `chats`;
3. `chat_members`;
4. `messages`;
5. `sessions`.
Откат удаляет таблицы в обратном порядке.
Применённые миграции учитываются в отдельной таблице версий. Повторный запуск
не должен повторно создавать схему, дублировать или удалять данные.
Для применения используется `golang-migrate` версии `v4.20.1` как отдельный
Compose-сервис. Миграции не запускаются автоматически каждой API-репликой.
Инструмент хранит текущую версию и состояние применения в служебной таблице
`schema_migrations`. Неуспешная миграция останавливает запуск API и требует
явного разбора причины, а не автоматического `force`.