Files
mtusi2026lab2/openspec/changes/postgres-storage/tasks.md
T
ricoromaandClaude Opus 5.5 125145df15 fix: hide SQL parameters in database error logs
- hide_parameters=True in the engine, rule in infra.md
- design: 79 of 80 tests, $(PYTHON) for test_isolated
- AGENTS.md: hand off deferred scenarios
- REPORT.md: unknown outcome of a timed-out commit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 16:41:47 +03:00

18 KiB
Raw Blame History

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. Зависимости и настройки

  • 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" без ошибок.
  • 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) его не показывает.
  • 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. Модели и миграции

  • 2.1 src/infra/db/: Base (created_at, to_dict()), модели users, chats, chat_members, messages с ограничениями и индексами из решения 3; фабрика engine и async_sessionmaker (решение 5). Проверка: Base.metadata.sorted_tables — четыре таблицы; у всех ограничений есть имена.
  • 2.2 alembic.ini и асинхронный migrations/env.py (решение 8): URL из settings.database.url, логи через src/infra/logger.py, логгер alembic на INFO. Проверка: при запущенном Postgres uv run alembic current печатает JSON-строки, пароля в выводе нет.
  • 2.3 Первая ревизия: autogenerate, затем руками CHECK и проверка имён ограничений; downgrade зеркалит upgrade. Проверка: на пустом volume make upgrade создаёт таблицы (\d+ в psql), alembic downgrade base и снова upgrade head проходят, повторный make upgrade ничего не меняет.

3. Compose, образ, Makefile

  • 3.1 Выбрать тег Postgres 18.x с патч-версией и digest индекса (docker buildx imagetools inspect), точку монтирования volume взять из Config.Volumes образа (решение 9). Проверка: тег, digest и путь записаны в docker-compose.yml, путь совпадает с метаданными.
  • 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.
  • 3.3 Dockerfile: COPY migrations alembic.ini в runtime, комментарий — лаба 2. Проверка: образ из контекста чистого clone (docker.md) собирается; в /app есть migrations/ и alembic.ini, alembic --help работает, uv не найден.
  • 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 пусто.
  • 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

  • 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 всей выборки.
  • 4.2 Сервисы на db_session, commit в сервисе, создание чата — одна транзакция (решение 4); удалить MemoryStore, get_store и src/infra/memory.py. Проверка: grep -rn MemoryStore src пусто, make lint чистый.
  • 4.3 Engine и фабрика сессий — глобалы src/infra/db/session.py (решение 5), dispose() в lifespan src/main.py; 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

  • 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.md.
  • 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.md.

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.md.

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.md.
  • 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.md.
  • 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.md. Сценарий «Успешный прогон» и 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 upgrade; SKILL.md без «рестарт = пустое состояние» и MemoryStore. Проверка: python3 .claude/skills/run-mtusi-messenger/driver.py all — start сам поднимает Postgres, flow без провалов, падают только smoke lab2 и test_security_scheme_in_openapi (до session-auth, design, Goals), затем stop.
  • 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 .. Проверка: все команды без ошибок.

9. Доработки по /opsx:verify

  • 9.1 hide_parameters=True в engine (решение 5), строка в infra.md. Проверка: messages под ACCESS EXCLUSIVE в psql, POST сообщения получает 503 по statement_timeout (SQLSTATE 57014), а в warning журнала вместо параметров — [SQL parameters hidden due to hide_parameters=True] и нет текста сообщения; вывод в evidence/storage/statement-timeout.md.
  • 9.2 Сценарий «Ошибка миграции» (db-migrations): migrate с несуществующей базой через override-файл compose вне репозитория. Проверка: migrate Exited с ненулевым кодом, api не запущен, ошибка в журнале migrate, пароля в выводе нет; стенд возвращён make run_docker; вывод в evidence/migrations/migration-error.md.
  • 9.3 Свежий git clone после commit: make env_setup, make run_dev (сценарий «Консольный запуск с нуля», db-migrations), затем make run_docker на тех же данных («Консоль, затем docker», service-configuration), make down и снова make run_docker («down сохраняет данные», container-run). Проверка: каждый запуск доходит до /health/ready 200 и видит данные, созданные в консоли; после проверки volume clone удалён и рабочий стенд поднят заново; вывод в evidence/storage/fresh-clone.md.
  • 9.4 Переснять evidence/storage/restart.md с docker compose ps до и после hook (решение 10, docker.md, scripts/restart.sh).
  • 9.5 Текст: design — «79 из 80», $(PYTHON) в решении 12 и причина; docstring engine.py; комментарий .dockerignore; REPORT.md — исход commit на таймауте в «Ограничениях»; AGENTS.md — отложенные сценарии в «Переходном состоянии» с changes, где они закрываются. Проверка: openspec validate postgres-storage --strict.