Files
mtusi2026lab2/docs/database.md

11 KiB
Raw Permalink Blame History

Проект хранения данных

Источники истины

PostgreSQL является источником истины для пользователей, чатов, участников, сообщений и сессий.

Redis используется как cache-aside кэш неизменяемых карточек чатов, но не как источник истины. Потеря Redis не приводит к потере данных или сессий.

Redis cache-aside

Ключ:

chat:v1:<chat_uuid>

Значение — JSON-представление domain.Chat: идентификатор, заголовок, упорядоченный список участников и время создания. TTL по умолчанию — 5 минут. Префикс v1 версионирует внутренний формат независимо от HTTP API.

Алгоритм чтения:

  1. Прочитать и проверить значение Redis.
  2. При hit проверить, что вызывающий пользователь есть в member_ids.
  3. При miss прочитать PostgreSQL и best-effort заполнить Redis.
  4. При timeout/ошибке Redis прочитать PostgreSQL и не повторять cache write в том же запросе.

Создание чата сначала полностью фиксируется транзакцией PostgreSQL, после чего выполняется best-effort запись в Redis. Контракт не содержит изменения заголовка или состава участников и удаления чата, поэтому write-инвалидация сейчас не требуется. TTL удаляет забытые копии, а повреждённое значение удаляется при чтении.

Redis работает без RDB/AOF и volume, с лимитом 64 MiB и allkeys-lru. Это намеренная политика для производного кэша. Readiness зависит только от PostgreSQL; при очистке или restart Redis данные лениво восстанавливаются.

Общие решения

  • Идентификаторы создаются приложением как UUID.
  • Время назначается PostgreSQL и хранится как TIMESTAMPTZ.
  • API возвращает время в UTC в формате RFC 3339.
  • Чаты и сообщения упорядочиваются по (created_at, id).
  • Используется уровень изоляции READ COMMITTED.
  • Все SQL-запросы параметризованы и выполняются с timeout.
  • Snapshot между несколькими HTTP-запросами не гарантируется.

Таблицы

users

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

id          UUID PRIMARY KEY
title       TEXT NOT NULL
created_at  TIMESTAMPTZ NOT NULL

Ограничения:

  • title содержит 1–100 символов;
  • title не состоит только из пробелов.

Индекс порядка:

(created_at, id)

chat_members

chat_id   UUID NOT NULL REFERENCES chats(id)
user_id   UUID NOT NULL REFERENCES users(id)
position  SMALLINT NOT NULL

Ограничения:

PRIMARY KEY (chat_id, user_id)
UNIQUE (chat_id, position)
CHECK (position BETWEEN 0 AND 99)

position сохраняет порядок member_ids и ограничивает число участников чата сотней.

Индекс для поиска чатов пользователя:

(user_id, chat_id)

messages

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).

Составной внешний ключ гарантирует, что отправитель является участником чата.

Индекс истории:

(chat_id, created_at, id)

sessions

token_hash  BYTEA PRIMARY KEY
user_id     UUID NOT NULL REFERENCES users(id)
created_at  TIMESTAMPTZ NOT NULL
expires_at  TIMESTAMPTZ NOT NULL

Ограничения:

CHECK (octet_length(token_hash) = 32)
CHECK (expires_at > created_at)

Клиент получает непрозрачный токен с энтропией не менее 256 бит. В PostgreSQL хранится только его SHA-256 digest.

Сессия действительна, пока строка существует и expires_at больше текущего времени. Logout физически удаляет строку сессии.

Индекс для очистки истёкших сессий:

(expires_at)

Транзакционные границы

Регистрация

Хеш Argon2id вычисляется до обращения к БД. Пользователь создаётся одним INSERT. Уникальное ограничение защищает от конкурентной регистрации одинакового username.

Создание чата

Одна транзакция:

  1. Вставить чат.
  2. Для каждого участника выполнить параметризованный INSERT ... SELECT FROM users WHERE id = $2.
  3. Проверить, что каждая команда вставила ровно одну строку.
  4. Выполнить COMMIT.

Если пользователя нет, RowsAffected() == 0: функция возвращает ErrNotFound, а deferred ROLLBACK удаляет уже вставленный чат и предыдущие membership-строки. Автотест отправляет существующего вызывающего и несуществующий UUID, проверяет отсутствие частичного чата, затем успешно создаёт другой чат через то же приложение.

Отправка сообщения

Проверка членства и вставка сообщения выполняются согласованно. Предпочтительно использовать один INSERT ... SELECT ... WHERE EXISTS.

Отсутствующий и чужой чат возвращают одинаковый HTTP 404.

Сессии

При входе приложение проверяет Argon2id, создаёт случайный токен и сохраняет его digest с абсолютным expires_at.

Аутентификация ищет digest токена и проверяет срок действия. Logout удаляет текущую сессию. После COMMIT новый запрос с этим токеном получает HTTP 401.

Курсорная пагинация

Сообщения

Курсор содержит:

version, created_at, message_id, chat_id

SQL-граница:

WHERE chat_id = $1
  AND (created_at, id) > ($2, $3)
ORDER BY created_at, id
LIMIT $4

Чаты

Курсор содержит:

version, created_at, chat_id, user_id

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(*).

План истории на 10 000 сообщений

Команда make explain-history открывает транзакцию, добавляет отдельные синтетические user/chat и ровно 10 000 сообщений, выполняет ANALYZE, печатает два EXPLAIN (ANALYZE, BUFFERS) и завершает всё ROLLBACK. Поэтому измерение повторяемо и не оставляет нагрузочные строки в постоянной БД.

Для первой страницы наблюдался план:

Limit (actual rows=101)
  -> Index Scan using messages_chat_created_at_id_idx
     Index Cond: (chat_id = ...)
Buffers: shared hit=5
Execution Time: 0.068 ms

Для страницы после 5000-го сообщения:

Limit (actual rows=101)
  -> Index Scan using messages_chat_created_at_id_idx
     Index Cond: chat_id = ... AND ROW(created_at, id) > ROW(...)
Buffers: shared hit=6
Execution Time: 0.111 ms

Составной индекс (chat_id, created_at, id) одновременно соответствует фильтру одного чата, tuple-границе keyset cursor и порядку выдачи. Поэтому PostgreSQL не делает Seq Scan и не сортирует всю историю для каждой страницы. Времена относятся только к указанному WSL2-стенду и не являются универсальным production-бенчмарком.

Миграции

Первая миграция создаёт таблицы в порядке:

  1. users;
  2. chats;
  3. chat_members;
  4. messages;
  5. sessions.

Откат удаляет таблицы в обратном порядке.

Применённые миграции учитываются в отдельной таблице версий. Повторный запуск не должен повторно создавать схему, дублировать или удалять данные.

Для применения используется golang-migrate версии v4.20.1 как отдельный Compose-сервис. Миграции не запускаются автоматически каждой API-репликой.

Инструмент хранит текущую версию и состояние применения в служебной таблице schema_migrations. Неуспешная миграция останавливает запуск API и требует явного разбора причины, а не автоматического force.