Files
mtusi2026lab2/infra/database-design.md
T
2026-10-21 20:10:27 +03:00

10 KiB
Raw Blame History

Модель данных PostgreSQL

PostgreSQL является первоисточником данных о пользователях, чатах, участниках чатов, сообщениях и сессиях. При запуске API инструмент Flyway применяет схему базы данных, описанную в файлах из директории src/main/resources/db/migration. Инициализация новой пустой базы данных выполняется с помощью скрипта V1__create_messenger_schema.sql.

Таблицы и ограничения

  • users: первичный ключ типа UUID, уникальное имя пользователя (username), проверка формата имени пользователя и длины отображаемого имени (display name), Argon2id-хеш пароля. Пароли в открытом виде не сохраняются.
  • chats: первичный ключ типа UUID, проверка длины названия чата.
  • chat_members: составной первичный ключ (chat_id, user_id), внешние ключи, ссылающиеся на таблицы chats и users. Первичный ключ предотвращает дублирование записей об участии пользователя в чате.
  • messages: первичный ключ типа UUID. Составной внешний ключ (chat_id, sender_id) -> chat_members(chat_id, user_id) гарантирует, что сообщение может быть сохранено только от имени пользователя, который является участником данного чата.
  • sessions: первичный ключ типа UUID, внешний ключ пользователя, уникальный SHA-256-хеш токена, время создания и истечения, а также необязательное время отзыва. Сам Bearer-токен в базе не хранится.

Проверка строковых данных осуществляется как на уровне HTTP-валидации, так и с помощью базовых ограничений SQL. Проверка символов Unicode (включая пробельные символы) выполняется на уровне приложения, поскольку механизмы регулярных выражений в PostgreSQL и классификация символов Unicode в Java не полностью идентичны.

Индексы и структура запросов

  • chat_members(user_id, chat_id) — индекс для поиска чатов, в которых состоит пользователь.
  • chats(created_at, id) — индекс для обеспечения детерминированного порядка сортировки чатов.
  • messages(chat_id, created_at, id) — индекс, поддерживающий пагинацию на основе курсоров (keyset pagination) без использования смещения (offset) или полной сортировки данных в оперативной памяти.
  • messages(sender_id, created_at) — индекс для диагностики действий конкретного пользователя и выполнения аудиторских запросов в будущем.
  • sessions(expires_at) WHERE revoked_at IS NULL — частичный индекс для поиска и очистки истёкших активных сессий.

Курсоры для сообщений и чатов используют тот же кортеж (created_at, id), что и соответствующее предложение ORDER BY в запросах.

Запрос страницы истории имеет вид WHERE chat_id = ? AND (created_at, id) > (?, ?) ORDER BY created_at, id LIMIT ?. Все значения передаются параметрами JdbcTemplate, поэтому данные пользователя не становятся частью SQL. Составной индекс messages_chat_created_id_idx сначала сужает диапазон по chat_id, затем начинает чтение непосредственно после курсора. Проверка make explain-history создаёт 10 000 сообщений внутри откатываемой транзакции и выполняет EXPLAIN (ANALYZE, BUFFERS). Проверка завершается ошибкой при отсутствии Index Scan по этому индексу или при появлении Seq Scan on messages.

Redis: роль, TTL и отказ

Redis используется как cache-aside-кэш объектов пользователей на горячем пути Bearer-аутентификации. Он не является источником истины для сессий: перед использованием кэша API всегда параметризованным запросом проверяет в PostgreSQL, что токен существует, не отозван и expires_at > CURRENT_TIMESTAMP. Поэтому устаревшая запись Redis не может восстановить отозванную или истёкшую сессию.

Ключи имеют вид messenger:user:<uuid> и TTL, задаваемый USER_CACHE_TTL_SECONDS (по умолчанию 300 секунд). При cache miss пользователь читается из PostgreSQL и помещается в Redis. Изменения и удаление пользователей API пока не поддерживает; при появлении таких операций соответствующий ключ должен удаляться после успешного commit. Повреждённая запись удаляется. При таймауте или недоступности Redis API пропускает кэш и читает PostgreSQL. Redis имеет ограниченный Lettuce pool и короткие таймауты. В Compose также включён AOF appendfsync everysec и именованный volume redis-data, хотя потеря кэша не влияет на корректность.

Сессии истекают по абсолютному expires_at в PostgreSQL. Logout атомарно заполняет revoked_at. Если PostgreSQL недоступен, защищённый запрос получает ограниченный ответ 503 unavailable; кэш не используется для обхода проверки токена. Запрос без Bearer-токена остаётся 401 и никогда не получает доверенную личность из X-User-Id.

Пулы и таймауты

HikariCP ограничен DATABASE_POOL_SIZE (по умолчанию 10), имеет конечные connection/validation timeouts, а JDBC-запросы и транзакции — таймаут 5 секунд. Lettuce pool ограничен 8 активными соединениями, ожидание соединения и сетевые операции Redis также имеют конечные таймауты.

Границы транзакций

Создание чата выполняется в рамках одной транзакции базы данных. Сначала вставляется запись в таблицу chats, затем — записи для каждого участника в таблицу chat_members. Если возникает дубликат или отсутствует запись об участнике, вся операция откатывается (rollback); таким образом, чат никогда не будет зафиксирован в базе данных (commit) без полного набора участников.

make test-operational устанавливает временный тестовый trigger, который намеренно отклоняет вставку одного участника после вставки чата, и проверяет отсутствие строки чата после ошибки. Trigger всегда удаляется в finally.

Создание пользователя или сообщения выполняется как атомарная транзакция, состоящая из одного SQL-оператора. Уникальность имени пользователя (username) обеспечивается на уровне базы данных с помощью ограничения users_username_uk; в случае одновременной попытки создания дубликата API возвращает ответ 409 Conflict.

Предварительная проверка username нужна только для быстрого понятного ответа. Корректность при гонке обеспечивает именно уникальное ограничение PostgreSQL и обработка DuplicateKeyException. make test-operational отправляет 12 одновременных регистраций: ровно одна должна получить 201, остальные — 409.

Создание сессии сохраняет хеш токена и срок действия одним SQL-оператором. Bearer-аутентификация выбирает только неотозванную сессию, у которой expires_at > CURRENT_TIMESTAMP. Logout атомарно устанавливает revoked_at. Сессии находятся в PostgreSQL и переживают рестарт API и PostgreSQL при сохранении именованного volume.

Операции получения списка и поиска выполняются в режиме изоляции READ COMMITTED. Контракт API не предусматривает использование единого снимка данных (snapshot) для нескольких HTTP-запросов в рамках постраничного вывода (пагинации).