Files
mtusi2026lab2/docs/database.md
T

7.4 KiB

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

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

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

Redis будет использоваться как cache-aside кэш чатов, но не как источник истины. Потеря 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. Вставить чат.
  3. Вставить всех участников с позициями.
  4. Выполнить COMMIT.

Любая ошибка приводит к ROLLBACK всей операции.

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

Проверка членства и вставка сообщения выполняются согласованно. Предпочтительно использовать один 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(*).

Миграции

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

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

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

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

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

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