Files
mtusi2026lab2/openspec/changes/postgres-storage/tasks.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

211 lines
16 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.
# Tasks
Как строить — `design.md` (дальше «решение N»), что должно получиться —
дельты в `specs/`. Перед первым файлом слоя прочитать его правило:
`migrations.md` (модели, `migrations/`, `alembic.ini`), `repo-layer.md`,
`service-layer.md`, `infra.md`, `settings.md`, `docker.md`,
`run-modes.md`. Нужен запущенный Docker и свободные порты 8080 и 5433.
Состояние кода, по которому снимается доказательство для отчёта,
коммитится перед замером (`bench.md`, «Измеренное состояние —
commit»).
## 1. Зависимости и настройки
- [x] 1.1 `uv add "sqlalchemy[asyncio]>=2.1,<2.2" asyncpg alembic` в
основную группу; описание в `pyproject.toml` — лаба 2 (решение 2).
Проверка: `uv lock --check` проходит, `uv run python -c "import
sqlalchemy, asyncpg, alembic, greenlet"` без ошибок.
- [x] 1.2 Секция `Database` в `src/config/settings.py`: адрес,
учётные данные, пул и таймауты из таблицы решения 5, `url` через
`URL.create`. Проверка: без `.env` и `config.toml` `Settings`
загружается на дефолтах; пароль `p@ss%word` даёт рабочий URL, а
`url.render_as_string(hide_password=True)` его не показывает.
- [x] 1.3 `.env.example` по схеме решения 7 (пустой
`POSTGRES_PASSWORD`) и `TEST_APP_PORT=18088` (решение 12),
`config_example.toml` — пул и таймауты `[database]`, `make env_setup`
подставляет случайный пароль при создании `.env`. Проверка: после
`make env_setup` в свежем каталоге `POSTGRES_PASSWORD` непустой,
повторный `make env_setup` его не меняет; `uv run python -c "from
src.config import settings; print(settings.database.host,
settings.database.port)"` печатает `127.0.0.1 5433`.
## 2. Модели и миграции
- [x] 2.1 `src/infra/db/`: `Base` (`created_at`, `to_dict()`), модели
`users`, `chats`, `chat_members`, `messages` с ограничениями и
индексами из решения 3; фабрика engine и `async_sessionmaker`
(решение 5). Проверка: `Base.metadata.sorted_tables` — четыре
таблицы; у всех ограничений есть имена.
- [x] 2.2 `alembic.ini` и асинхронный `migrations/env.py` (решение 8):
URL из `settings.database.url`, логи через `src/infra/logger.py`,
логгер `alembic` на `INFO`. Проверка: при запущенном Postgres
`uv run alembic current` печатает JSON-строки, пароля в выводе нет.
- [x] 2.3 Первая ревизия: autogenerate, затем руками `CHECK` и
проверка имён ограничений; `downgrade` зеркалит `upgrade`.
Проверка: на пустом volume `make upgrade` создаёт таблицы (`\d+` в
`psql`), `alembic downgrade base` и снова `upgrade head` проходят,
повторный `make upgrade` ничего не меняет.
## 3. Compose, образ, Makefile
- [x] 3.1 Выбрать тег Postgres 18.x с патч-версией и digest индекса
(`docker buildx imagetools inspect`), точку монтирования volume
взять из `Config.Volumes` образа (решение 9). Проверка: тег, digest
и путь записаны в `docker-compose.yml`, путь совпадает с метаданными.
- [x] 3.2 `docker-compose.yml`: `name:`, якорь `x-app-env`, сервисы
`postgres` (`PGPORT`, алиас, `pg_isready`, volume `postgres_data`,
публикация `127.0.0.1`), `migrate`, `api` с `depends_on` (решения 7,
8, 9). Проверка: `docker compose --env-file .env config --quiet`
проходит; в `environment` и `ports` нет адреса и порта Postgres
литералами, кроме `127.0.0.1`.
- [x] 3.3 `Dockerfile`: `COPY migrations alembic.ini` в runtime,
комментарий — лаба 2. Проверка: образ из контекста чистого clone
(`docker.md`) собирается; в `/app` есть `migrations/` и
`alembic.ini`, `alembic --help` работает, `uv` не найден.
- [x] 3.4 `Makefile`: `start_db` (`up -d --wait postgres`), `stop_db`,
`upgrade`, `revision` (зависит от `upgrade`, `read -p`), `run_dev`
(`start_db`, `upgrade`, сервис), `wipe_data` с подтверждением;
`down` без `-v`; удалить `run_no_compose`, `DOCKER_IMAGE` и
`DOCKER_CONTAINER` (решение 9). Проверка: `make -n` для каждой цели
печатает ожидаемые команды; `make wipe_data` без подтверждения ничего
не удаляет; `grep -n run_no_compose Makefile` пусто.
- [x] 3.5 `student-tests/run_isolated.py` (stdlib: `docker compose
build`, `exec psql`, `run` для `migrate` и `api`, ожидание готовности,
уборка в `finally`) и цель `test_isolated: env_setup start_db` по
решению 12; `KEEP_TEST_DB` передаётся из аргумента make. Проверка:
`make -n test_isolated` печатает запуск скрипта; `uv run pytest
--collect-only` не собирает `run_isolated.py`; `make lint` чистый.
## 4. Repo, сервисы, API
- [x] 4.1 Repo `user`, `chat`, `message` на `AsyncSession` (решения 3,
4): `ON CONFLICT`, `array_agg(... ORDER BY position)`, keyset через
`tuple_` для истории и списка чатов. Проверка: на запущенном стенде
`EXPLAIN` запросов истории и списка чатов с `SET enable_seqscan =
off` использует индексы `(chat_id, created_at, id)` и
`(user_id, created_at, chat_id)` без `Sort` всей выборки.
- [x] 4.2 Сервисы на `db_session`, commit в сервисе, создание чата —
одна транзакция (решение 4); удалить `MemoryStore`, `get_store` и
`src/infra/memory.py`. Проверка: `grep -rn MemoryStore src` пусто,
`make lint` чистый.
- [x] 4.3 `src/main.py`: engine в lifespan, `dispose()` при остановке;
`dependencies.py`: `get_db_session`, фабрики сервисов;
`get_current_user` по-прежнему по `X-User-Id`. Проверка: `make
run_dev` поднимается до `/health/ready` 200; по SIGTERM в журнале
«Stopped API» и «Finished server process»; пароля в журнале нет.
## 5. Недоступность БД и readiness
- [x] 5.1 Определить классы исключений: API запущен, Postgres
остановлен (`docker compose stop postgres`), затем приостановлен
(`docker compose pause postgres`); записать исключения из traceback
для отказа в соединении, клиентского таймаута и таймаута пула.
Проверка: список внесён в решение 6 `design.md`.
- [ ] 5.2 Перехват в `get_db_session` (решение 6): откат, `warning`,
`ServiceUnavailable`. Проверка: сценарии «БД остановлена» и «БД
вернулась» (`data-storage`) — 503 `unavailable` без деталей, после
`docker compose start postgres` запросы проходят без рестарта API;
вывод в `evidence/storage/db-unavailable.txt`.
- [ ] 5.3 `/health/ready`: `SELECT 1` с таймаутом через engine.
Проверка: при остановленном Postgres `/health/ready` — 503 не позже
таймаута, `/health/live` — 200.
- [ ] 5.4 Сценарий «Соединения исчерпаны»: `DATABASE__POOL_SIZE=1`,
`DATABASE__MAX_OVERFLOW=0`, `DATABASE__POOL_TIMEOUT_SECONDS=1`,
Postgres на паузе, два одновременных запроса. Проверка: второй
получает 503 примерно через 1 с, первый — 503 после
`request_timeout_seconds` и закрытия соединения (6 + 2 с); вывод в
`evidence/storage/pool-timeout.txt`.
## 6. Рестарт стенда
- [ ] 6.1 `scripts/restart.sh` по решению 10, исполняемый бит в git.
Проверка: `git ls-files -s scripts/restart.sh` — режим `100755`;
скрипт укладывается в 90 с; по журналу записано, прогоняет ли `up`
сервис `migrate` заново.
- [ ] 6.2 Сценарий «Рестарт hook-ом» (`container-run`) и «Прежний
пользователь после рестарта» (`data-storage`): пользователь, чат с
`member_ids` в порядке `[bob, alice]`, сообщения; `StartedAt` до и
после `scripts/restart.sh`. Проверка: после рестарта тот же
`X-User-Id` получает 200, история и порядок участников прежние;
вывод в `evidence/storage/restart.txt`.
## 7. Проверки стенда
- [ ] 7.1 Сценарий «Консоль и контейнер» (`student-tests`): `make
student_test` против `make run_dev` и против `make run_docker`.
Проверка: в обоих прогонах прошли все тесты, кроме
`test_security_scheme_in_openapi` (переход контракта, design, Goals).
Evidence набора против контейнера снимает `session-auth`.
- [ ] 7.2 Миграции с нуля и повторно (`db-migrations`): `make
wipe_data`, `make run_docker`, журнал `migrate`; затем повторный
прогон миграций при данных в базе. Проверка: `migrate` завершился
с кодом 0 раньше старта API; число строк во всех таблицах до и после
повтора одинаково; вывод в `evidence/migrations/from-zero-and-rerun.txt`.
- [ ] 7.3 Сценарий «Другой порт Postgres»: `POSTGRES_PORT=5544`,
`POSTGRES_OUT_PORT=5545` в `.env`, compose не правится. Проверка:
`make run_docker` доходит до `/health/ready` 200, `make run_dev`
подключается к `127.0.0.1:5545`; `.env` возвращён; вывод в
`evidence/storage/postgres-port.txt`.
- [ ] 7.4 Сценарий «Консоль, затем docker» (`service-configuration`) и
«down сохраняет данные» (`container-run`). Проверка: данные,
созданные через `make run_dev`, видны после `make run_docker` и после
`make down` + `make run_docker`, файлы конфигурации не менялись.
- [ ] 7.5 Сценарий «Адрес публикации» (`container-run`). Проверка:
`docker port` для API и Postgres стенда показывает `127.0.0.1`, а не
`0.0.0.0`.
- [ ] 7.6 Механика «Прогон на временной базе» (`student-tests`) при
запущенном рабочем стенде с данными: обычный прогон (до
`session-auth` он заканчивается падением smoke — это сценарий
«Упавшие тесты»); остановка тестового контейнера во время прогона;
Ctrl+C; хвост после `kill -9` скрипта; `KEEP_TEST_DB=1`. Проверка: в
каждом случае код выхода, наличие базы `test_<db>` (`\l` в `psql`) и
тестового контейнера (`docker ps -a`) соответствуют сценарию; число
строк рабочей базы до и после одинаково, рабочий API отвечает; после
разбора `KEEP_TEST_DB` база удалена руками; вывод в
`evidence/tests/test-isolated-mechanics.txt`. Сценарий «Успешный
прогон» и evidence набора против контейнера — задача `session-auth`.
- [ ] 7.7 Перенести дельты в основные спеки (`/opsx:sync`) и в том же
шаге обновить `student-tests/spec_coverage.py`: тексты исключений
«Прежний пользователь после рестарта» и «Хранилище не готово»,
исключения для «Сбой при добавлении участников», «БД остановлена»,
«БД вернулась», «Соединения исчерпаны» со ссылками на evidence и
change `failure-checks`; тест сценария «Порядок участников» в
`test_data_storage.py`. Purpose основного спека `container-run`
переписать руками: в нём «голый `docker run` из README (`make
run_no_compose`)», а дельта Purpose не меняет. Проверка: `make
student_test` против стенда — прошли все тесты, кроме
`test_security_scheme_in_openapi`, в том числе `test_coverage.py`;
`grep -rn run_no_compose openspec/specs` пусто.
## 8. Документы и инструменты
- [ ] 8.1 Правила по решениям 11 и 12: `settings.md`, `infra.md`,
`run-modes.md` (плюс `test_isolated`), `docker.md`, `student-tests.md`
(обычный прогон и evidence — `make test_isolated`, против любого
стенда — `make student_test`). Проверка: `grep -n "POSTGRES_VOLUME\|решает
design change" .claude/rules` — только там, где решение ещё не
принято (`membership-cache`); `grep -rn run_no_compose .claude`
пусто.
- [ ] 8.2 `AGENTS.md`: «Переходное состояние» без закрытых пунктов и с
известным падением `test_security_scheme_in_openapi` до
`session-auth`,
карта кода, команды `start_db`, `stop_db`, `upgrade`, `revision`,
`wipe_data`, `test_isolated`, без `run_no_compose`. Проверка: каждая команда из
таблицы есть в `Makefile` (`make -n <цель>`).
- [ ] 8.3 Скилл `run-mtusi-messenger`: `driver.py start` перед
сервером выполняет `make start_db upgrade`; `SKILL.md` без «рестарт =
пустое состояние» и `MemoryStore`. Проверка: `python3
.claude/skills/run-mtusi-messenger/driver.py all` завершается с кодом
0.
- [ ] 8.4 `REPORT.md`: запуск из чистого clone (`make run_docker`,
`make run_dev`, остановка, `make wipe_data`), проверки (`make
test_isolated`; `make student_test` против любого стенда);
архитектура — схема, транзакционные границы,
источник истины, семантика при конкурентных вставках, ограничение
часов, соответствие переменных `.env.example` skeleton; строки
доказательств уровня «3» по хранению со ссылками на `evidence/`.
Проверка: у каждой строки есть команда, наблюдение и путь к файлу.
- [ ] 8.5 Финальная проверка: `make lint`, `make check`,
`openspec validate postgres-storage --strict`, `graphify update .`.
Проверка: все команды без ошибок.