11 KiB
Проект хранения данных
Источники истины
PostgreSQL является источником истины для пользователей, чатов, участников, сообщений и сессий.
Redis используется как cache-aside кэш неизменяемых карточек чатов, но не как источник истины. Потеря Redis не приводит к потере данных или сессий.
Redis cache-aside
Ключ:
chat:v1:<chat_uuid>
Значение — JSON-представление domain.Chat: идентификатор, заголовок,
упорядоченный список участников и время создания. TTL по умолчанию — 5 минут.
Префикс v1 версионирует внутренний формат независимо от HTTP API.
Алгоритм чтения:
- Прочитать и проверить значение Redis.
- При hit проверить, что вызывающий пользователь есть в
member_ids. - При miss прочитать PostgreSQL и best-effort заполнить Redis.
- При 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.
Создание чата
Одна транзакция:
- Вставить чат.
- Для каждого участника выполнить параметризованный
INSERT ... SELECT FROM users WHERE id = $2. - Проверить, что каждая команда вставила ровно одну строку.
- Выполнить 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-бенчмарком.
Миграции
Первая миграция создаёт таблицы в порядке:
users;chats;chat_members;messages;sessions.
Откат удаляет таблицы в обратном порядке.
Применённые миграции учитываются в отдельной таблице версий. Повторный запуск не должен повторно создавать схему, дублировать или удалять данные.
Для применения используется golang-migrate версии v4.20.1 как отдельный
Compose-сервис. Миграции не запускаются автоматически каждой API-репликой.
Инструмент хранит текущую версию и состояние применения в служебной таблице
schema_migrations. Неуспешная миграция останавливает запуск API и требует
явного разбора причины, а не автоматического force.