- migrations from zero, schema and rerun on 2d0a7c8
- restart hook, database outage, pool timeout, postgres port
- make test_isolated mechanics: failure, stop, Ctrl+C, kill -9, keep db
- align REPORT.md numbers with the new evidence
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
19 KiB
Отчёт — лабораторная 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— удалить контейнеры, volumepostgres_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,01 с; ready 503, live 200 | после start — сразу, без рестарта API; подтверждённые данные на месте |
docker compose pause postgres (сервер завис) |
503 не позже срока запроса и закрытия соединения (6 + 2 с) | 503 через 8,0 с, ready 503 через 2 с | после unpause — сразу |
| пул исчерпан (1 соединение, сервер завис) | ожидание не дольше pool_timeout |
503 через 1,0 с | после unpause — сразу |
scripts/restart.sh (API и Postgres) |
данные и порядок на месте | hook 3,6 с, готовность через 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/.