Files
mtusi2026lab2/openspec/changes/postgres-storage/proposal.md
T
ricoromaandClaude Opus 5.5 4921afa39d feat: store messenger data in PostgreSQL
Replace the in-memory store with PostgreSQL 18.6: SQLAlchemy 2.1 async
engine on asyncpg, alembic migrations with an async env.py, repos on
AsyncSession and services that own the transaction. Username
uniqueness is enforced by the database (ON CONFLICT), a chat and its
members are created in one transaction, member order is kept in
chat_members.position, and a composite foreign key makes the sender a
member of the chat. History and chat lists use keyset pagination on
(chat_id, created_at, id) and (user_id, created_at, chat_id).

The compose stand runs postgres, a one-shot migrate service on the
API image and the API. All Postgres addresses come from .env without
literals; only the 127.0.0.1 publish address stays literal. make
run_dev starts Postgres and applies migrations before the server, and
make env_setup generates a random Postgres password.

Unavailable PostgreSQL yields 503: get_db_session bounds the request
with asyncio and classifies driver errors. BoundedCloseConnection
limits asyncpg's graceful close, which otherwise waited without limit
on a frozen server and held the request until it was resumed.

Add scripts/restart.sh for make test-persistence and make
test_isolated, which runs the image on a throwaway test database.
Remove make run_no_compose. X-User-Id identification is unchanged
until the session-auth change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 15:33:49 +03:00

100 lines
6.9 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.
# Proposal
## Why
Лаба 2 требует, чтобы подтверждённые данные переживали перезапуск, а
источником истины был PostgreSQL (`README.md`, уровень «3»). Сейчас
пользователи, чаты и сообщения живут в `MemoryStore` одного процесса и
пропадают при рестарте. Это первый шаг перехода на лабу 2. Хранилище
меняется отдельно от аутентификации: API остаётся прежним (`X-User-Id`),
и перенесённые из лабы 1 `student-tests` проверяют замену без правок
тестов поведения.
## What Changes
- **BREAKING (для оператора):** стенд запускается только вместе с
PostgreSQL. Compose поднимает `postgres`, одноразовый сервис
миграций и `api`; данные лежат в именованном volume.
- `MemoryStore` удаляется. Repo работают через `AsyncSession`
(SQLAlchemy async, драйвер asyncpg), сервисы управляют транзакциями.
Уникальность `username` держит ограничение БД, создание чата с
участниками — одна транзакция.
- Схема версионируется alembic: `users`, `chats`, `chat_members` (с
позицией участника), `messages`; первичные и внешние ключи, уникальный
`username`, индекс истории `(chat_id, created_at, id)`. `env.py` —
асинхронный шаблон alembic, URL берётся из настроек.
- Миграции применяются до старта API: в docker — отдельный сервис того
же образа, в консоли `make run_dev` сам поднимает БД и накатывает
миграции. Добавляются цели `start_db`, `stop_db`, `upgrade`,
`revision`, `wipe_data`.
- Секция настроек `[database]`: адрес, учётные данные, пул, таймауты.
Значения для консоли и для docker приходят из одного `.env` без
переключения конфига комментариями. В compose нет литералов адреса и
порта Postgres, кроме адреса публикации `127.0.0.1`.
- `/health/ready` проверяет Postgres. Потеря связи с БД на
бизнес-запросе даёт 503 `unavailable`, а после возврата БД сервис
работает без перезапуска.
- **BREAKING (для защиты):** рестарт контейнеров больше не стирает
состояние. Прежний `X-User-Id` после рестарта стенда получает 200.
Появляется `scripts/restart.sh`: перезапуск API и Postgres с
сохранением volume.
- Образ содержит `migrations/` и `alembic.ini`.
- `make test_isolated`: тесты образа на временной базе `test_<db>` в
том же Postgres. Команда собирает образ, создаёт базу, накатывает на
неё миграции сервисом миграций compose, поднимает отдельный контейнер
API из определения сервиса compose с подменой только имени базы,
прогоняет публичный smoke и `student-tests`, затем удаляет контейнер
и базу. Одна команда проверяет код, образ и связку compose, а рабочая
база не копит данные тестов.
- **BREAKING (для оператора):** цель `make run_no_compose` удаляется:
без PostgreSQL один контейнер API запросы не обслуживает, а сборку
образа проверяет `make run_docker`.
Вне этого change: пароли, Basic → Bearer и сессии (`session-auth`),
Redis/Valkey, проверки отказов уровня «4», доработка `bench/`.
## Capabilities
### New Capabilities
- `db-migrations`: версионируемая схема, миграции с нуля и повторный
запуск без дублей, применение миграций до старта API в docker и в
консоли.
### Modified Capabilities
- `data-storage`: хранение в PostgreSQL вместо памяти процесса,
сохранность после рестарта, целостность в БД, транзакция составной
операции, недоступность БД → 503, ограниченный пул и таймауты.
- `health`: readiness проверяет доступность PostgreSQL.
- `container-run`: стенд compose из `api`, `postgres` и миграций;
данные переживают рестарт; порты Postgres из `.env`; удаление данных
— отдельной явной командой; запуска одного контейнера без compose
(`make run_no_compose`) больше нет.
- `container-image`: образ собирается с тегом лабы 2 и содержит
миграции.
- `service-configuration`: параметры подключения к PostgreSQL; консоль
и docker без правки файлов и без литералов в compose.
- `student-tests`: прогон образа на временной базе, которая удаляется
после прогона.
## Impact
- Код: `src/infra/db/` (engine, модели), `src/core/repos/*`,
`src/core/services/*`, `src/api/dependencies.py`,
`src/api/routers/health.py`, `src/main.py` (lifespan),
`src/config/settings.py`; удаляется `src/infra/memory.py`.
- Новые файлы: `alembic.ini`, `migrations/`, `scripts/restart.sh`,
`student-tests/run_isolated.py`.
- Зависимости: `sqlalchemy[asyncio]`, `asyncpg`, `alembic` в основной
группе; `uv.lock`.
- Инфраструктура: `docker-compose.yml`, `Dockerfile`, `.env.example`,
`config_example.toml`, `Makefile`.
- Тесты: тесты поведения в `student-tests/` не меняются; записи
исключений в `spec_coverage.py` следуют за дельтами `data-storage` и
`health`.
- Документы: `AGENTS.md` (переходное состояние, карта кода),
`.claude/rules/` (settings, infra, run-modes, docker), скилл
`run-mtusi-messenger`, `REPORT.md` (архитектура, запуск,
доказательства хранения), `evidence/`.