Files
mtusi2026lab2/REPORT.md
T
ricoromaandClaude Opus 5.5 2d0a7c83e9 feat: finish postgres-storage change
- keep engine and session factory in src/infra/db/session.py
- sync delta specs into openspec/specs, add db-migrations spec
- update rules, AGENTS.md and run skill for lab 2 storage
- fill REPORT.md for the storage part

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

19 KiB
Raw Blame History

Отчёт — лабораторная 2

  • Автор, группа: Сафронов Роман Николаевич, БВТ2301
  • Целевая оценка 5; выбранный трек 5: 2 (план запроса и восстановление)
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки и помощь ИИ: раздел «Источники, библиотеки и использование ИИ» в конце отчёта

Отчёт заполняется по мере работы. Готово: хранение в PostgreSQL (change postgres-storage). Впереди: пароли, вход и сессии (session-auth), кэш Redis/Valkey (membership-cache), проверки отказов уровня 4 (failure-checks), EXPLAIN и стенд под Postgres (bench-postgres), трек 2 (track2-query-plans, track2-backup-restore).

Запуск из чистого clone

Версии. Образ API: python:3.12.14-slim-trixie и uv 0.12.17, Postgres: postgres:18.6-trixie; все закреплены тегом и digest индекса (amd64 + arm64) в Dockerfile и docker-compose.yml. Приложение: Python 3.12, FastAPI 0.141.1, SQLAlchemy 2.1.1 (async), asyncpg 0.31.0, alembic 1.20.0 и остальное строго по uv.lock. Проверено на Docker Desktop 29.8.1 (VM linux/arm64), Compose v5.5.1, macOS на Apple M3 Pro.

Нужно на машине: Docker с BuildKit, make, python3 (3.9+) для публичных проверок и make test_isolated, свободные порты 127.0.0.1:8080 (API) и 127.0.0.1:5433 (Postgres). uv на хосте нужен только для запуска сервиса без контейнера (make run_dev).

Подготовка и секреты. make env_setup создаёт .env из .env.example и config.toml из config_example.toml; существующие файлы не трогает. В шаблоне пароль Postgres пустой, в новый .env подставляется случайный (openssl rand -hex 16), так что общего пароля стенда в git нет. Отдельно запускать env_setup не нужно: его вызывают make run_docker, make run_dev и make test_isolated. Пароль задаётся Postgres только при создании volume: после смены POSTGRES_PASSWORD нужен make wipe_data.

git clone <fork> && cd <каталог clone>
git checkout solution/bvt2301-safronov

Способ 1. Всё в compose: make run_docker

make run_docker
# make env_setup (только недостающие .env и config.toml)
# DOCKER_BUILDKIT=1 docker compose build
# docker compose up -d      postgres -> migrate (alembic upgrade head) -> api

Порядок задают depends_on: migrate стартует после healthcheck Postgres (pg_isready по TCP), API — после того, как migrate завершился с кодом 0. Готовность — GET http://127.0.0.1:8080/health/ready → 200 (несколько секунд после команды). Журнал API — make logs, миграций — docker compose logs migrate.

Способ 2. Сервис на хосте: make run_dev

make run_dev
# docker compose up -d --wait postgres
# uv run alembic upgrade head     -> 127.0.0.1:5433
# APP__RUN_MODE=console uv run python -m src

Сервис слушает 127.0.0.1:8080 с reload по src/, Postgres — тот же контейнер и тот же volume, что у способа 1. Переключение между способами не требует правки файлов (раздел «Конфигурация»).

Проверки

make check                                 # структура skeleton
make validate PYTHON=.venv/bin/python      # OpenAPI 3.1 (после uv sync --all-extras)
make test_isolated                         # образ на временной базе: smoke + student-tests, уборка
make student_test                          # собственные тесты против запущенного стенда (BASE_URL)
make test                                  # публичный smoke против запущенного стенда

До change session-auth публичный smoke лабы 2 падает на регистрации с password, а в student-tests падает test_security_scheme_in_openapi (контракт lab2 не содержит схему devUser); остальные 79 тестов проходят.

Остановка и удаление данных

  • make stop — остановить контейнеры; make down — удалить контейнеры, volume postgres_data с данными остаётся;
  • make wipe_data — удалить контейнеры и volume, только после ввода yes; следующий make run_docker поднимает пустую базу со схемой.

Архитектура и решения

клиент --HTTP--> api (FastAPI, 1 процесс) --asyncpg, пул--> postgres (volume postgres_data)
                       ^
           migrate (тот же образ, alembic upgrade head, до старта api)

Источник истины — PostgreSQL. Пользователи, чаты, участники и сообщения хранятся только в нём; память процесса, файлы и SQLite не используются. Подтверждённая запись (201) зафиксирована commit до ответа.

Схема (миграция migrations/versions/…_added_messenger_tables.py):

Таблица Ключи и ограничения Индексы
users PK id; UNIQUE username; CHECK шаблона username и длины display_name uq_users_username
chats PK id; CHECK длины title —
chat_members PK (chat_id, user_id); FK на chats и users; UNIQUE (chat_id, position); position хранит порядок member_ids (user_id, created_at, chat_id) — keyset списка чатов
messages PK id; составной FK (chat_id, sender_id) → chat_members: отправитель обязан быть участником; CHECK длины text (chat_id, created_at, id) — keyset истории

id и created_at назначает сервис (uuid4(), utcnow()), а не БД. chat_members.created_at — копия времени чата, по ней список чатов идёт keyset-ом по индексу без сортировки всех чатов пользователя. CHECK дублируют контракт: первым отвечает API (400), сработавший CHECK — дефект валидации.

Транзакционные границы. Одна AsyncSession на запрос, commit делает сервис, изоляция READ COMMITTED:

Операция Шаги в одной транзакции
регистрация INSERT … ON CONFLICT (username) DO NOTHING RETURNING; конфликт → 409
создание чата проверка существования участников → INSERT chats → INSERT chat_members (одна вставка) → commit; ошибка до commit — откат, не остаётся ни чата, ни участников
сообщение проверка членства → INSERT messages → commit
чтения один SELECT

Явные блокировки не нужны: пользователи и участники не меняются и не удаляются, гонку регистрации закрывает уникальный индекс (тест test_same_username_at_once: из 10 одновременных регистраций одна 201, девять 409).

Пагинация. Курсор — ключ (created_at, id) последнего элемента; запрос — сравнение кортежей по индексу, без OFFSET. Повторов при обходе нет. Сообщение, которое закоммитилось позже, но с created_at меньше уже пройденного курсора, текущий обход пропустит, а новый обход с начала увидит. Время ставит один процесс API с часами хоста; при нескольких репликах лабы 3 часы общие (один Docker-host).

Недоступность БД. Критичная зависимость /health/ready — PostgreSQL (SELECT 1 с таймаутом 2 с). Ошибки соединения и таймауты на бизнес-запросе дают 503 unavailable без деталей, причина пишется в журнал (warning), после возврата Postgres запросы обслуживаются без рестарта API. Таймауты: подключение 3 с, ожидание соединения пула 5 с, серверный statement_timeout 5 с, срок всей работы запроса с БД 6 с; пул 10 + 5 соединений. При замёрзшем сервере ответ приходит через 6 + 2 с: 2 с — ограниченное мягкое закрытие прерванного соединения. Без этого ограничения asyncpg и SQLAlchemy ждали разморозки сервера (169 с в замере); подробности — design change postgres-storage, решение 6.

Конфигурация. Все значения — из .env, переключение консоль ↔ docker без правки файлов. Консольный сервис читает .env с мостами DATABASE__*; в контейнер .env не попадает, адрес и порт Postgres приходят из environment compose. В compose нет литералов адреса и порта Postgres, литерал — только адрес публикации 127.0.0.1.

Переменная skeleton (.env.example) В этом проекте
APP_HOST режим APP__RUN_MODE: console — 127.0.0.1, docker — 0.0.0.0
APP_PORT APP__PORT (внутри), APP_OUT_PORT (публикация на 127.0.0.1)
APP_ENV не используется: окружение одно — учебный стенд
SESSION_TTL_SECONDS TODO, change session-auth
DATABASE_URL_FILE не используется: URL собирает приложение из [database], пароль — мостом из POSTGRES_PASSWORD
SESSION_STORE TODO, change session-auth (сессии в PostgreSQL)
CACHE_URL_FILE TODO, change membership-cache

Что перенесено из лабы 1 и что изменено. HTTP-контракт лабы 1 (X-User-Id) пока сохранён: замену хранилища проверяют перенесённые student-tests без правки тестов поведения. Хранилище MemoryStore заменено PostgreSQL, repo и сервисы переписаны на AsyncSession, цель make run_no_compose удалена: API без Postgres не обслуживает запросы. Согласования с преподавателем из лабы 1 действуют: FastAPI с его расхождениями и конфиг через config.toml (AGENTS.md).

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test, make test_isolated TODO: до session-auth падает на регистрации с password TODO
PostgreSQL содержит пользователей, чаты, участников и сообщения; PK/FK, уникальный username \d в psql, alembic check после миграций 4 таблицы, ограничения и индексы по таблице выше; модели совпадают со схемой evidence/migrations/from-zero-and-rerun.md, migrations/versions/
Миграции с нуля и повторно без дублирования make wipe_data, make run_docker, docker compose run --rm migrate migrate завершился с кодом 0 до старта API; повтор — no-op, число строк не изменилось evidence/migrations/from-zero-and-rerun.md
Данные переживают рестарт API и хранилищ без удаления volumes scripts/restart.sh у API и Postgres новые StartedAt, прежний X-User-Id видит свои данные, порядок участников и истории тот же evidence/storage/restart.md; make test-persistence — после session-auth
Составная операция создания чата атомарна код ChatService.create_chat: один commit автоматическая проверка отката — change failure-checks TODO
Basic, Bearer, срок жизни и отзыв сессии, KDF — TODO, change session-auth TODO
Secrets и volumes не в git .gitignore, make env_setup .env, config.toml игнорируются; пароль Postgres генерируется локально .gitignore
Собственные тесты против контейнера make test_isolated механика проверена: база и контейнер убираются при любом исходе; зелёный прогон — после session-auth evidence/tests/test-isolated-mechanics.md
Конфигурация из .env, без литералов адреса и порта Postgres в compose POSTGRES_PORT и POSTGRES_OUT_PORT изменены в .env, make run_docker, make run_dev оба способа запуска подключились к новому порту, compose не правился evidence/storage/postgres-port.md
Уровень 4: ограниченный пул и таймауты пул из одного соединения, Postgres на паузе второй запрос — 503 через 1 с (pool_timeout), первый — 503 через 6 + 2 с evidence/storage/pool-timeout.md
Уровень 4: недоступность БД docker compose stop и pause postgres 503 unavailable без деталей, /health/live 200, после возврата — без рестарта API evidence/storage/db-unavailable.md
Уровень 4: гонка регистрации одного username test_same_username_at_once одна 201, девять 409 TODO: вывод make test_isolated после session-auth
Уровень 4: параметризованные запросы код repo SQLAlchemy Core/ORM с параметрами, SQL из строк нет src/core/repos/
Остальные пункты уровня 4 — TODO: Redis/Valkey, EXPLAIN на ≥10 000, проверки expiry и отказов TODO
Трек 5 — TODO TODO

Эксперименты и отказы

Стенд: Docker Desktop 29.8.1 на macOS (Apple M3 Pro), ВМ Docker 12 CPU и 7 GiB RAM, лимиты контейнерам не задавались; таймауты — по умолчанию из config_example.toml.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker compose stop postgres 503 вместо 500, ready 503, live 200 503 через 0,1 с; ready 503, live 200 после start — сразу, без рестарта API; подтверждённые данные на месте
docker compose pause postgres (сервер завис) 503 не позже срока запроса 503 через 8,0 с (6 с срок + 2 с закрытие), ready 503 через 2 с после unpause — сразу
пул исчерпан (1 соединение, сервер завис) ожидание не дольше pool_timeout 503 через 1,0 с после unpause — сразу
scripts/restart.sh (API и Postgres) данные и порядок на месте hook 3,7 с, готовность через 1 с после него потерь нет

Ограничения и следующие шаги

  • Сервер, замёрзший при открытом соединении, держит запрос 8 с, а не 6: 2 с уходят на ограниченное закрытие соединения.
  • Время сообщений ставит процесс API: порядок истории зависит от часов хоста; конкурентные вставки могут быть пропущены текущим обходом (раздел «Пагинация»).
  • Один Docker-host: потерю хоста стенд не переживает, Postgres без реплик.
  • Прогоны make student_test и make test против рабочего стенда оставляют данные в рабочей базе; обычный прогон — make test_isolated.
  • Не реализовано: вход и сессии, Redis/Valkey, автоматические проверки отказов, EXPLAIN и трек 2 — следующие changes.

Источники, библиотеки и использование ИИ

  • Документация: PostgreSQL 18 (транзакции, statement_timeout, pg_isready), SQLAlchemy 2.1 (asyncio, пул, обработка разрывов), alembic (async-шаблон env.py), asyncpg (параметры подключения, connection_class), Docker Compose (depends_on, --wait, сети).
  • Библиотеки: FastAPI, pydantic, pydantic-settings, structlog, SQLAlchemy, asyncpg, alembic, uvicorn; в тестах — pytest и httpx.
  • ИИ: Claude (Claude Code) помогал проектировать change postgres-storage (OpenSpec), писать код, правила и отчёт, а также проверял поведение на стенде. Решения и все правки просмотрены автором; поведение подтверждено командами, выводы которых лежат в evidence/.