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

466 lines
32 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.
# Design
## Context
Мотивация — `proposal.md`, раздел Why. Требования — `specs/`.
Сейчас всё состояние — `MemoryStore` (`src/infra/memory.py`): dict-ы и
отсортированные списки, атомарность держится на отсутствии `await`
внутри repo-функций. Сервисы получают `store` в конструкторе, repo —
первым параметром. Правила слоёв уже описывают целевое состояние
лабы 2 (`.claude/rules/`, commit `93b699a`), их здесь не пересказываем.
Решения обсуждены в `/opsx:explore` перед этим change: трек «5» — 2,
сессии — Postgres без кэша (change `session-auth`), Redis/Valkey — кэш
состава чатов (change `membership-cache`), конфиг без комментирования,
литерал только у адреса публикации `127.0.0.1`.
Проверено на версиях этого change пробными скриптами:
- SQLAlchemy 2.1.1 ставит greenlet только через extra `asyncio`
(`Requires-Dist: greenlet>=1; extra == "asyncio"`); без него
асинхронный engine не работает.
- В SQLAlchemy 2.1.1 флага `async_fallback` нет (в 2.0 он устарел).
Синхронный `env.py` bp_proxies с asyncpg на 2.1 не заработает.
- FastAPI 0.141.1: исключение из ручки попадает в `except` зависимости
с `yield`, а исключение, брошенное оттуда, обрабатывает
зарегистрированный обработчик (получен 503 из своего обработчика).
## Goals / Non-Goals
**Goals:**
- `student-tests/` проходят против `make run_dev` и `make run_docker`
без правки тестов поведения: 78 из 79. Исключение —
`test_security_scheme_in_openapi`. Он сверяет схему `devUser` на
сервере со схемой в `contracts/openapi.json`, а в контракте lab2 её
нет (переход 1 → 2). Тест падал с момента переноса кода, чинится
вместе со спеком `identification` в `session-auth`.
- `make test_isolated` проверяет образ и связку compose и не оставляет
данных в рабочей базе. Здесь проверяется его механика: база,
контейнер, уборка при любом исходе. Зелёный прогон и evidence набора
против контейнера возможны только после `session-auth`: smoke lab2
требует вход и Bearer, а тест выше падает до тех пор.
- Консоль и docker работают от одного `.env` без переключений.
- Каждая мутация — одна транзакция, уникальность и связи держит БД.
**Non-Goals:**
- Аутентификация, пароли, сессии, `WWW-Authenticate` — `session-auth`.
Здесь `X-User-Id` и `devUser` остаются как есть.
- Redis/Valkey и кэш — `membership-cache`.
- Автоматические проверки отказов (остановка БД, откат составной
операции) — `failure-checks`; здесь поведение реализуется и
проверяется вручную с записью в `evidence/`.
- `bench/` под Postgres, EXPLAIN на ≥10 000 — `bench-postgres`.
- Производительность сверх индекса истории и keyset без `OFFSET`.
## Decisions
### 1. Хранилище меняется раньше аутентификации
Change не трогает HTTP-контракт лабы 1. Тогда `student-tests` —
готовая регрессия: красный тест поведения значит дефект хранилища.
Меняются только записи исключений в `spec_coverage.py`, которые
следуют за дельтами `data-storage` и `health`.
*Альтернатива:* хранилище и вход одним change. Отвергнута: красный
тест не отличал бы дефект БД от дефекта аутентификации.
### 2. Стек доступа к данным
`sqlalchemy[asyncio]` 2.1 + `asyncpg` + `alembic`, все три в основной
группе зависимостей: сервис миграций работает в runtime-образе, а он
собирается с `--no-dev`.
*Альтернативы:* psycopg 3 (второй знакомый вариант, но bp_proxies и
правила уже на asyncpg); голый asyncpg без SQLAlchemy (правила слоёв
опираются на `AsyncSession`, `pg_insert`, `tuple_`, а параметризация
через SQLAlchemy закрывает требование уровня 4 без самодельного SQL).
### 3. Схема
```
users chats
id uuid PK id uuid PK
username text UQ title text
display_name text created_at timestamptz
created_at timestamptz
^ ^
| |
chat_members messages
chat_id uuid FK -> chats --+ id uuid PK
user_id uuid FK -> users | PK chat_id --+ FK (chat_id, sender_id)
position smallint | sender_id --+ -> chat_members
created_at timestamptz (= chats.created_at) text text
PK (chat_id, user_id) created_at timestamptz
UQ (chat_id, position)
IX (user_id, created_at, chat_id) IX (chat_id, created_at, id)
```
- Все ограничения именованные (`migrations.md`). `CHECK` дублируют
контракт как защиту в глубину: шаблон `username`, длины
`display_name`, `title` и `text` в code points (`char_length`).
Первым всё равно отвечает API (400); сработавший `CHECK` — это дефект
валидации, и он даст 500, а не тихую запись.
- `position` хранит порядок `member_ids` из запроса: `test_chats.py`
сверяет его дословно. `member_ids` чата собирается
`array_agg(user_id ORDER BY position)`.
- Внешний ключ сообщения — составной, на `chat_members (chat_id,
user_id)`: сообщение от не участника невозможно на уровне БД, а не
только проверкой в сервисе.
- `chat_members.created_at` — копия `chats.created_at` (у `Base` это
поле есть у всех моделей, `migrations.md`). Благодаря ей список чатов
пользователя идёт keyset-ом по индексу
`(user_id, created_at, chat_id)` без сортировки всех его чатов.
Значение неизменяемо, рассинхрону неоткуда взяться.
- `id` и `created_at` назначает сервис (`uuid4()`, `utcnow()`), БД
их не генерирует: иначе порядок, который видит клиент, зависел бы от
двух часов.
*Альтернатива для списка чатов:* `JOIN` без копии даты и сортировка
всех чатов пользователя. Проще, но это полный просмотр чатов
пользователя на каждую страницу — ровно то, что рубрика уровня 4
запрещает для истории.
### 4. Транзакции и repo
Одна `AsyncSession` на запрос, commit — только в сервисе
(`service-layer.md`). Уровень изоляции — `READ COMMITTED`, явных
блокировок нет.
| Операция | Шаги в одной транзакции |
|---|---|
| регистрация | `INSERT ... ON CONFLICT (username) DO NOTHING RETURNING` → `None` = 409 → commit |
| создание чата | `SELECT id FROM users WHERE id = ANY(...)` → `INSERT chats` → `INSERT chat_members` (одна многострочная вставка) → commit |
| сообщение | чат с участниками → проверка членства → `INSERT messages` → commit |
| чтения | один `SELECT`; commit не нужен, сессия закрывается откатом |
Блокировки не нужны: пользователи и участники не удаляются и не
меняются, значит проверка перед вставкой не устаревает, а гонку
регистрации закрывает уникальный индекс. Составной внешний ключ и
внешние ключи участников — страховка на случай ошибки в сервисе.
Keyset: `tuple_(created_at, id) > tuple_(:t, :id)`, `ORDER BY
created_at, id`, `LIMIT limit + 1`. `uuid` Postgres сравнивает
побайтно — тот же порядок, что `UUID.int` у smoke. Формат курсора
(`src/utils/cursor.py`) не меняется.
Семантика при конкурентных вставках (в `REPORT.md`): повторов при
обходе нет. Сообщение, которое закоммитилось позже, но с `created_at`
меньше уже пройденного курсора, текущий обход пропустит; новый обход
с начала его увидит. Время ставит один процесс API с часами хоста.
### 5. Engine, пул и таймауты
`create_async_engine` в lifespan, `engine.dispose()` в shutdown.
Параметры — секция `[database]`, значения по умолчанию:
| Параметр | По умолчанию | Зачем |
|---|---|---|
| `pool_size` / `max_overflow` | 10 / 5 | ограниченный пул (уровень 4) |
| `pool_timeout_seconds` | 5 | ожидание соединения → 503, а не очередь без конца |
| `connect_timeout_seconds` | 3 | недоступный хост не держит запрос |
| `statement_timeout_ms` | 5000 | серверный `statement_timeout` через `server_settings` |
| `request_timeout_seconds` | 6 | срок всей работы запроса с БД (`asyncio.timeout` в `get_db_session`): зависший сервер или обрыв сети, где серверный таймаут не сработает |
`command_timeout` asyncpg не используется: задача 5.1 показала, что
зависший сервер он не ограничивает (решение 6).
`pool_pre_ping=True`: после рестарта Postgres соединения пула мертвы, и
без проверки первый запрос после `scripts/restart.sh` получил бы 503.
Цена — один короткий round trip на выдачу соединения из пула.
`application_name=mtusi-messenger` — чтобы соединения были видны в
`pg_stat_activity`. URL — `sqlalchemy.engine.URL.create(...)` в
`Database.url`: пароль со спецсимволами экранируется, строку никто не
собирает руками.
### 6. Недоступность БД → 503
Зависимость `get_db_session` (с `yield`) ставит срок
`request_timeout_seconds` на всю работу запроса с БД, ловит ошибки
недоступности (`src/infra/db/errors.py`), закрывает сессию с
`invalidate()`, пишет `warning` и бросает `ServiceUnavailable`; таблица
`errors.py` отдаёт 503 `unavailable`. Так перевод в одном месте, с
логом, и ни один сервис не оборачивает каждый вызов.
Классы исключений сняты задачей 5.1 на SQLAlchemy 2.1.1 и asyncpg 0.31:
| Отказ | Исключение | Время до ответа |
|---|---|---|
| Postgres остановлен | `ConnectionRefusedError` (SQLAlchemy не оборачивает) | сразу |
| сервер не отвечает на подключение | `TimeoutError` (`connect_timeout_seconds`) | 3 с |
| сработал `statement_timeout` | `DBAPIError`, SQLSTATE `57014` | по таймауту |
| пул исчерпан | `sqlalchemy.exc.TimeoutError` | `pool_timeout_seconds` |
| соединение оборвано | `DBAPIError` с `connection_invalidated` | сразу |
| сервер завис, соединение из пула | `TimeoutError` срока запроса | 6 + 2 с |
Перехватываются `OSError` (сюда входит `TimeoutError`),
`sqlalchemy.exc.TimeoutError` и `DBAPIError` с `connection_invalidated`
или SQLSTATE класса `08`, `57014`, `57P01`–`57P03`. Остальные
`DBAPIError` (ограничения, синтаксис) — дефект, им положен 500.
Зависший сервер (`docker compose pause`) нашёл дефект в связке
библиотек. На отмене запроса asyncpg шлёт серверу CancelRequest через
новое соединение без срока, а SQLAlchemy закрывает прерванное
соединение мягко и ждёт этой отмены. Без поправки запрос висел до
разморозки сервера (169 с в замере), и `command_timeout` asyncpg его не
ограничивал. Поправка — `BoundedCloseConnection` (публичный
`connection_class` asyncpg): мягкое закрытие ограничено 2 с, после чего
asyncpg обрывает соединение. Отсюда «6 + 2 с» в таблице.
`/health/ready` не ходит через эту зависимость: отдельная проверка
`SELECT 1` с таймаутом через engine из `app.state`.
*Альтернативы:* обработчик исключений SQLAlchemy в `errors.py` —
отвергнут, `errors.py` не логирует (`logging.md`), а потеря БД в логе
нужна; `try/except` в каждом методе сервиса — шум без пользы.
### 7. Конфигурация: консоль и docker из одного `.env`
```
.env (шаблон .env.example)
POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB <- их читает и образ postgres
POSTGRES_HOST=postgres адрес Postgres в сети compose (docker)
POSTGRES_PORT=5432 порт, который слушает сервер (PGPORT)
POSTGRES_OUT_PORT=5433 порт публикации на 127.0.0.1 (console)
DATABASE__HOST=127.0.0.1 \
DATABASE__PORT=${POSTGRES_OUT_PORT} мосты для console:
DATABASE__USER=${POSTGRES_USER} приложение на хосте читает .env
DATABASE__PASSWORD=${POSTGRES_PASSWORD}
DATABASE__NAME=${POSTGRES_DB} /
docker-compose.yml
x-app-env: &app-env api и migrate — одно окружение
APP__RUN_MODE: docker литерал: это определение режима
DATABASE__HOST: ${POSTGRES_HOST:-postgres}
DATABASE__PORT: ${POSTGRES_PORT:-5432}
DATABASE__USER / __PASSWORD / __NAME: ${POSTGRES_*}
postgres:
environment: POSTGRES_USER / _PASSWORD / _DB, PGPORT: ${POSTGRES_PORT:-5432}
ports: "127.0.0.1:${POSTGRES_OUT_PORT:-5433}:${POSTGRES_PORT:-5432}"
networks.default.aliases: ["${POSTGRES_HOST:-postgres}"]
```
- `.env` в контейнер не попадает, поэтому консольные `DATABASE__*` из
него не конфликтуют с docker-значениями из `environment`.
- Алиас в сети делает любое значение `POSTGRES_HOST` рабочим для
Postgres стенда; внешний адрес уводит API во внешнюю БД.
- `PGPORT` меняет порт самого сервера (так его читает `postgres`) и
`pg_isready` в healthcheck; иначе смена `POSTGRES_PORT` сломала бы
стенд. Проверяется сценарием «Другой порт Postgres».
- `127.0.0.1` — литерал: требование безопасности, а не параметр.
- В `.env.example` пароль пустой. `make env_setup` при создании `.env`
подставляет случайный (`openssl rand -hex 16`), существующий `.env`
не трогает. С пустым паролем образ postgres не стартует — забытый
шаг проявится сразу, а в git не лежит общий пароль стенда.
- В `config_example.toml` — только то, что читает одно приложение:
пул и таймауты `[database]`. Адрес и учётные данные там не
дублируются (`settings.md`).
*Альтернатива:* блоки `[database]` для консоли и docker с
комментированием, как в bp_proxies. Отвергнута: ручное переключение,
пароль в двух местах, `config.toml` здесь не запекается в образ.
### 8. Миграции
- `alembic.ini`: `script_location = migrations`, `file_template` из
`migrations.md`, `prepend_sys_path = .`, без `sqlalchemy.url`.
- `env.py` — асинхронный шаблон alembic: `create_async_engine(
settings.database.url)`, затем `await conn.run_sync(do_run_migrations)`.
Ревизии остаются синхронным кодом `op.*`. URL не проходит через
ConfigParser alembic, поэтому `%` в пароле ничего не ломает.
- Логи миграций — через `src/infra/logger.py` (JSON), а не `fileConfig`
из `alembic.ini`: у сервиса миграций тот же формат журнала, что у API.
Логгер `alembic` — уровень `INFO`, чтобы строки «Running upgrade»
были видны.
- Первая ревизия пишется autogenerate и дописывается руками:
autogenerate не видит `CHECK` (`migrations.md`).
Запуск:
```
console make run_dev
start_db docker compose up -d --wait postgres
upgrade uv run alembic upgrade head --> 127.0.0.1:${POSTGRES_OUT_PORT}
APP__RUN_MODE=console uv run python -m src
docker make run_docker
postgres --healthy--> migrate --exit 0--> api
(образ API, depends_on:
alembic upgrade migrate: service_completed_successfully
head, restart: no)
```
`make revision` зависит от `upgrade`: autogenerate сравнивает модели с
базой на `head`.
### 9. Compose и образ
- Postgres — последняя 18.x, тег с патч-версией и digest индекса
(`docker.md`). Точку монтирования volume берём из метаданных образа
(`docker image inspect` → `Config.Volumes`): у 18.x она изменилась
относительно 17.x.
- Именованный volume `postgres_data`; верхнеуровневое `name:` проекта,
чтобы имена volume и контейнеров не зависели от имени каталога.
- `Dockerfile`: в runtime дополнительно `COPY migrations alembic.ini`.
- `make run_no_compose` удаляется вместе с переменными `DOCKER_IMAGE` и
`DOCKER_CONTAINER` в `Makefile`: без Postgres один контейнер API не
обслуживает запросы, а мосты `${...}` из `.env` голый `docker run
--env-file` не раскрывает. Образ собирает `make run_docker`, сборку из
чистого clone проверяет команда из `docker.md`. Healthcheck остаётся
в образе: его берут compose и стенд `bench/`.
*Альтернатива:* оставить цель как проверку образа (live 200, ready
503). Отвергнута: цель, которая по построению поднимает неготовый
сервис, — лишнее, что нужно поддерживать и описывать.
### 10. `scripts/restart.sh`
`docker compose stop api` → `docker compose restart postgres` →
`docker compose up -d --wait postgres` (тот же контейнер, ожидание
healthcheck) → `docker compose start api`. Volume не трогается.
`start api` запускает и зависимость `migrate` (задача 6.1 увидела это
по `StartedAt`): повторный прогон миграций — no-op (`db-migrations`).
Hook отрабатывает за ~4 с. Готовность API он не ждёт — это делает тест.
В `evidence/` — `docker compose ps` и `StartedAt` из `docker inspect`
до и после.
### 11. Что ещё меняется вокруг кода
- `MemoryStore` и `get_store` удаляются, `health.py` зависит от проверки
БД. DTO остаются frozen; `ChatFullDTO.member_ids` собирается из
`array_agg`.
- Скилл `run-mtusi-messenger`: `driver.py start` перед сервером
выполняет `make start_db upgrade`; в `SKILL.md` убираются «рестарт =
пустое состояние» и примеры с `MemoryStore`.
- Правила: `settings.md` — консольный адрес Postgres в `.env`, а не в
`config.toml`; `infra.md` — перевод ошибок драйвера в
`get_db_session`; `run-modes.md` — именованный volume вместо
`POSTGRES_VOLUME`, `run_dev` с миграциями; `docker.md` — переменные
Postgres в compose. Из `settings.md`, `run-modes.md`, `docker.md` и
`AGENTS.md` уходят упоминания `make run_no_compose`.
- `AGENTS.md`: из «Переходного состояния» уходят пункты про
`MemoryStore`, `migrations/`, `scripts/restart.sh`; `X-User-Id`
остаётся до `session-auth`.
### 12. `make test_isolated`: образ на временной базе
Тесты ходят в API по HTTP, поэтому временной базе нужен свой API. Им
становится отдельный контейнер из того же определения сервиса compose,
что и рабочий: так один прогон проверяет код, образ и связку compose, а
рабочий стенд и рабочая база не трогаются.
```
make test_isolated (зависит от env_setup и start_db)
uv run python student-tests/run_isolated.py
0. docker rm -f <тестовый контейнер> хвост прошлого прогона
DROP DATABASE IF EXISTS "test_<db>" WITH (FORCE)
1. docker compose build api
2. CREATE DATABASE "test_<db>"
3. docker compose run --rm --no-deps -e DATABASE__NAME=test_<db> migrate
4. docker compose run -d --no-deps --name <тестовый контейнер>
-e DATABASE__NAME=test_<db>
-p 127.0.0.1:$TEST_APP_PORT:$APP__PORT api
5. ждать GET http://127.0.0.1:$TEST_APP_PORT/health/ready = 200 (не дольше 60 с)
6. make test BASE_URL=http://127.0.0.1:$TEST_APP_PORT
make student_test BASE_URL=http://127.0.0.1:$TEST_APP_PORT
finally (и по Ctrl+C):
при неудаче: docker logs --tail 50 <тестовый контейнер>
docker stop -> docker rm <тестовый контейнер>
DROP DATABASE "test_<db>" WITH (FORCE) (кроме KEEP_TEST_DB=1)
код выхода: первый ненулевой из smoke, набора, уборки
```
- **`docker compose run` берёт определение сервиса целиком:** образ,
`x-app-env`, монтирование `config.toml`, сеть и алиас Postgres.
Подменяется только `DATABASE__NAME`, поэтому ошибки в якоре окружения,
в `PGPORT`, в алиасе или в составе образа роняют и этот прогон.
- **`--no-deps`**, чтобы `run` не прогнал `migrate` по рабочей базе и
не пересоздал рабочие контейнеры. Postgres уже поднят `start_db`.
- **Публикация — явным `-p` на `127.0.0.1`.** `compose run` без
`--service-ports` порты сервиса не публикует, поэтому с рабочим API
на `APP_OUT_PORT` конфликта нет. Порт внутри контейнера тот же
`APP__PORT`, healthcheck образа работает как обычно.
- **Сборка перед прогоном.** Проверяется образ ровно из рабочего дерева,
а не устаревший. `migrate` использует тот же тег образа, что и `api`,
поэтому одна сборка покрывает оба. С кэшем слоя зависимостей это
секунды.
- **`CREATE` и `DROP` — через `docker compose exec -T postgres psql`**
под `POSTGRES_USER` по локальному сокету контейнера. Скрипту не нужны
ни `psql` на хосте, ни драйвер БД, он остаётся на stdlib, как
`bench/`. Имя базы проверяется по `^[a-z0-9_]+$` и берётся в кавычки.
- **`WITH (FORCE)`** (Postgres 13+) рвёт оставшиеся соединения. Базу
можно удалить, даже если контейнер не остановился штатно.
- **`TEST_APP_PORT`** в `.env`, по умолчанию 18088. Не пересекается с
рабочим API (8080) и портами драйвера скилла `run-mtusi-messenger`
(18080, 18090). Имя без секции: приложение его не читает.
- **Имя тестового контейнера фиксировано** (`<проект>-test-api`):
хвост прошлого прогона находится и удаляется без поиска.
- **Evidence.** Вывод `make test_isolated` — это прогон набора против
контейнера, которого требует спек `student-tests`, «Результат прогона
сохраняется». Отдельный прогон против `make run_docker` для evidence
не нужен. `make student_test` не меняется и работает против любого
`BASE_URL`. Успешный прогон снимает `session-auth`: в этом change
smoke lab2 и `test_security_scheme_in_openapi` ещё падают (Goals).
*Альтернативы:* сервис на хосте (`uv run python -m src` с временной
базой) — быстрее, но не проверяет образ и compose и требует настройки,
выключающей reload в режиме console; оба режима сразу — больше кода в
скрипте ради цикла, который и так даёт `make run_dev` +
`make student_test`; отдельный контейнер Postgres на tmpfs — второй
сервис в compose ради мусора тестов; чистка через `DELETE` из тестов —
ломает black-box и правило `student-tests.md`.
## Risks / Trade-offs
- [Два `make test_isolated` одновременно удалят базу друг друга] →
Параллельный запуск не поддерживается (спек `student-tests`); прогон
занимает секунды, одному разработчику этого хватает.
- [Каждый `make test_isolated` пересобирает образ: цикл «поправил →
проверил» медленнее, чем на хосте] → Быстрая итерация — `make run_dev`
и `make student_test`; `test_isolated` — итоговая проверка перед
коммитом и evidence.
- [Проверки отказов из `failure-checks` с остановкой Postgres положат и
рабочую базу: сервер общий] → Временная база решает проблему мусора,
а не изоляцию отказов; `failure-checks` выберет для них отдельный
контейнер.
- [До `session-auth` ни один прогон не зелёный: падают smoke lab2 и
`test_security_scheme_in_openapi`] → Регрессию хранилища видно по
остальным 78 тестам; известное падение записано в «Переходном
состоянии» `AGENTS.md`, успешный `test_isolated` — задача
`session-auth`.
- [Пользователи из этого change без пароля, а `session-auth` добавит
`password_hash`] → Данные стенда синтетические. `session-auth` решает
сам: колонка `NOT NULL` после `make wipe_data` или nullable с отказом
во входе. Отмечено здесь, чтобы не стало сюрпризом.
- [`pool_pre_ping` — лишний round trip на выдачу соединения] →
Приемлемо для учебного стенда; альтернатива `pool_recycle` не спасает
от рестарта БД между выдачами.
- [Время ставит приложение, а не БД] → Одна реплика API на одном хосте;
при репликах лабы 3 часы общие (один Docker-host). Ограничение в
`REPORT.md`.
- [`CHECK` на `text` 1–4000 помешает lab4, где разрешён пустой текст с
вложениями] → Новая миграция в lab4, применённую не трогаем.
- [SQLAlchemy 2.1 — свежая ветка] → Асинхронный `env.py` и код repo
работают и на 2.0; при дефекте 2.1 откат на `<2.1` без правок кода.
- [Прогоны против рабочего стенда (`make student_test`, `make test`)
копят данные в volume] → Обычный прогон — `make test_isolated`
(решение 12); для чистого рабочего стенда — `make wipe_data`.
- [Точный набор исключений драйвера для 503 неизвестен заранее] →
Задача с остановленным Postgres фиксирует его до написания
перехвата.
## Migration Plan
Данных для переноса нет: лаба 1 хранила всё в памяти. Порядок:
зависимости и настройки → модели и первая ревизия → repo и сервисы →
lifespan, health, 503 → compose, Makefile, restart hook → тесты и
evidence → документы. Откат: `git revert` коммитов change и
`make wipe_data`.
## Open Questions
- Значения пула и таймаутов по умолчанию могут уточниться по замерам
`bench-postgres`: это настройки, спеки и план от них не зависят.