Propose adopting SQLAlchemy and Alembic for the lab 3 storage

User requirement (2026-11-05, labs 3+): all PostgreSQL access goes through
SQLAlchemy 2.x async and migrations run through Alembic. The proposal keeps
every port, zone boundary and observable API behavior in place, moves the
checksum-based migration journal scenario to Alembic revision semantics and
pins the evidence that depends on SQL behavior for regeneration.

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
Artyom
2026-11-05 00:46:59 +03:00
co-authored by Claude Code
parent 72a1e57467
commit c5f39dea25
5 changed files with 226 additions and 0 deletions
@@ -0,0 +1,3 @@
schema: spec-driven
created: 2026-11-05
lab: 3
@@ -0,0 +1,108 @@
# Дизайн: SQLAlchemy 2.x async + Alembic для лабы 3
## Решение и цена
Требование пользователя переводит весь SQL лаб 3+ на SQLAlchemy 2.x async, а миграции — на Alembic. По формуле книги:
получаем — единый декларативный слой запросов (`select`, `join`, `with_for_update`, `returning`), типизированные
ORM-модели сущностей, переносимый пул и механизм сессий, индустриальный мигратор с журналом ревизий и autogenerate
на будущее; платим — лишним слоем трансляции (SQL компилируется в asyncpg-протокол через greenlet), меньшей
прозрачностью низкоуровневых параметров соединения и четырьмя точечными `text()` там, где декларативно не выражается.
Зоны, порты и наблюдаемое поведение API не меняются — меняется только транспорт SQL за портами.
## Порты, адаптеры, сборка
Порты прежние: `IdentityUnitOfWork` (`users`, `sessions`), `MessagingUnitOfWork` (`chats`),
`MessageLog`, `UserDirectory`, `SessionDirectory`, `ChatDirectory`, `Readiness`. Адаптеры прежние
(`Postgres*` в `infrastructure` зон), точки сборки прежние (`entrypoints/ioc.py` зон и `PlatformProvider`):
`Database` конструируется из `PlatformSettings` и раздаётся тем же провайдером. Домен и приложение по-прежнему не
импортируют инфраструктуру (правило проверяет ruff `banned-api` и тест состава модулей); pydantic-схемы остаются
на HTTP-границе, ORM-модели не выходят за `infrastructure`.
## ORM-модели и зоны
- `shared/infrastructure/postgres.py` — платформа: `Base(DeclarativeBase)`, `Database` (движок + фабрика сессий),
`PostgresUnitOfWork`. В `shared/` оказывается только механизм (базовый класс и пул), ни одного доменного понятия.
- `identity/infrastructure/postgres.py` — `UserRow` (`users`), `SessionRow` (`sessions`).
- `messaging/infrastructure/postgres.py` — `ChatRow` (`chats`), `ChatMemberRow` (`chat_members`), `MessageRow`
(`messages`), `IdempotencyKeyRow` (`idempotency_keys`).
Типы колонок заданы явно там, где это важно для asyncpg: `DateTime(timezone=True)` у всех `timestamptz`,
`LargeBinary` у `bytea`, `SmallInteger` у `position`. Зоны не импортируют модели друг друга: перекрёстный внешний
ключ `chat_members.user_id → users.id` объявлен только в миграции, а не в ORM, — связь зон остаётся ограничением
целостности схемы, и ни одна зона не получает тип другой зоны; цена связи уже была заплачена на уровне SQL и здесь
не растёт.
## Пул, сессии, транзакции, отказ
`Database` создаёт `create_async_engine` с `postgresql+asyncpg` и теми же серверными настройками, что были у
asyncpg-пула (`statement_timeout`, `lock_timeout`, `idle_in_transaction_session_timeout` из
`db_command_timeout_seconds`), `pool_size = db_pool_max_size`, `max_overflow = 0`, `pool_timeout =
db_acquire_timeout_seconds`, `pool_recycle = 60`. `session()` — контекст с `async_sessionmaker(expire_on_commit=False)`;
истощение пула даёт `sqlalchemy.exc.TimeoutError`, соединительные сбои — `OperationalError`/`InterfaceError`;
все они, как и прежде, сворачиваются в `Unavailable` → `503 unavailable` за ограниченное время
(`test_pool` сохраняет смысл: одна занятая связь и таймаут 0,3 с → 503 в пределах секунды). `IntegrityError`
(FK, UNIQUE) сквозь это отображение не проходит — нарушение целостности остаётся нарушением, а не «недоступностью».
`PostgresUnitOfWork.transaction()` открывает сессию, даёт репозиториям работать в её автотранзакции, `commit()`
фиксирует и затем собирает события агрегатов (как раньше), при выходе без фиксации — откат. Направление зависимостей
и семантика событий не меняются. Издержки и отличие от asyncpg: связь приобретается лениво, на первом операторе,
поэтому занятость пула наблюдается на первом запросе, а не при взятии сессии; при отмене задачи SQLAlchemy
инвалидирует и закрывает соединение, серверную сторону запроса гасит `statement_timeout`/`lock_timeout` — поведение
`make retry-check` (потерянный ответ и повтор тем же ключом) сохраняется, путь записи тот же.
## SQL: что декларативно, что в text()
Декларативно: регистрация (`pg_insert(UserRow).on_conflict_do_nothing(...).returning(literal(True))`),
поиск пользователя/сессии (`select`), вставка и удаление сессий, вставка чата, участники — executemany
`insert(ChatMemberRow)` с `position` из `enumerate` (замена `unnest … WITH ORDINALITY`; атомарность та же —
внутри одной транзакции UoW), каталоги чатов и истории (`select` + `func.array(scalar_subquery)` для `member_ids`,
`order_by`, `limit`, keyset через `tuple_(created_at, id) > tuple_(…)` — row comparison, как раньше),
квитанция ключа (`select(...).join(MessageRow)`).
Точечно в `text()` остаётся одна команда отправки сообщения: CTE-цепочка с `FOR UPDATE OF c` (блокировка строки чата
перед квитанцией ключа — прежний порядок блокировок), частичным `ON CONFLICT … DO UPDATE … WHERE created_at <= …`
и `RETURNING` из двух CTE. Декларативно это выражается развязкой на несколько операторов и теряет атомарность
одного оператора, поэтому остаётся SQL-текстом с именованными bind-параметрами (без склейки значений). Индексы и
планы не меняются: `messages_history_idx (chat_id, created_at, id)` обслуживает историю и `ORDER BY` сообщения,
`chat_members_user_idx (user_id, chat_created_at, chat_id)` — каталог и keyset, PK `idempotency_keys (chat_id,
user_id, key)` — вставку-конфликт, `users_username_key` — регистрацию; `EXPLAIN` на новом коде перегенерируется в
evidence и сравнивается с прежним.
## Миграции: Alembic
- Каталог `alembic/` с async `env.py`, `alembic.ini` в корне; ревизии `0001_init`, `0002_idempotency_keys`
воспроизводят прежние SQL-файлы дословно (те же таблицы, ограничения, индексы), `transaction_per_migration` —
каждая ревизия в своей транзакции, как раньше. Итоговая схема идентична прежней — проверяется свежим стендом
(`evidence/schema.txt`, `\d+`).
- Журнал — штатная таблица `alembic_version` вместо `schema_migrations`; контрольных сумм Alembic не хранит, поэтому
сценарий «изменённая миграция» из capability `lab2-persistent-storage` уходит; порядок и однократность
(`transaction_per_migration`, один одноразовый процесс) сохраняются.
- Сериализация одновременных запусков — прежний session-level advisory lock `20260002`, выполняется в `env.py`
на отдельном соединении (session-level переживает commit), снимается в `finally`.
- One-shot сервис `migrate` в compose выполняет `alembic upgrade head`; образ приложения несёт `alembic.ini` и
`alembic/` (правки `Dockerfile`); сервис по-прежнему non-root, одноразовый, до старта реплик. Повторный запуск —
no-op. `scripts/rolling-update.sh` не меняется: миграции применяются один раз перед заменой первой реплики.
- DSN собирается из тех же настроек/секретов (`DATABASE_URL`/`DATABASE_URL_FILE` через `PlatformSettings`), секрет
не логируется и не попадает в артефакты.
## Хранилища: истина, expiry, недоступность
PostgreSQL — источник истины для пользователей, сессий, чатов, сообщений и ключей идемпотентности; Valkey — только
общий кэш сессий с прежним TTL/инвалидацией и обходом при отказе. Границы транзакций прежние: чат + участники —
одна транзакция; сообщение + квитанция ключа — один оператор; истечение ключа и сессий — по времени, TTL задан
настройками. Переживает рестарт всё то же: persistent volume PostgreSQL. Секреты — compose secrets, в Git и образе
их нет.
## Поведение при сигналах и конфигурация контейнера
Graceful shutdown, readiness за портом `Readiness` и `SIGTERM`-окно не меняются: `DatabaseReadiness` пингует
через ту же `Database` (`SELECT 1` под таймаутом 0,4 с). Пул закрывается при остановке приложения
(`await database.close()` → `engine.dispose()`). Требования к контейнеру прежние: non-root, read-only корень,
лимиты CPU/RAM, healthcheck, `SIGTERM` в пределах `stop_grace_period`.
## Что перегенерируется и где описаны расхождения
Evidence, зависящее от поведения SQL: схема и миграции (`evidence-storage.sh`), smoke, отказы уровня «3»/«4»
(failover, persistence, faults, retry), серии трека 1 и планы запросов — на новом коде; расхождения (новые
top-операторы SQLAlchemy, разница в RPS/латентности, таблица версий) фиксируются в `REPORT.md` и
`evidence/README.md`.
@@ -0,0 +1,50 @@
## Why
Обязательное требование пользователя (2026-11-05, действует с лабы 3): вся работа с PostgreSQL — только через
SQLAlchemy 2.x async (`postgresql+asyncpg`, `async_sessionmaker`, `DeclarativeBase`), миграции — только Alembic.
Сырой asyncpg в адаптерах и собственный SQL-миграционный runner с журналом `schema_migrations` уходят. Поведение API
не меняется: решение остаётся заявленным на «5» с треком 1, исправления прежних ревью (порядок блокировок, `FOR UPDATE`,
chunked-лимит) сохраняются. Уровни «3» и «4» держатся прежними наблюдаемыми проверками; закрывает инфраструктурные
строки таблицы доказательств `REPORT.md` (миграции, схема, SQL-слой) и требование пользователя, выходящее за рубрику.
## What Changes
- Пул и UoW `shared/infrastructure/postgres.py` переведены с asyncpg на SQLAlchemy: `create_async_engine`
(`postgresql+asyncpg`), `async_sessionmaker`, `DeclarativeBase`; те же `statement_timeout` / `lock_timeout` /
`idle_in_transaction_session_timeout`, размер пула и таймауты; отказ БД по-прежнему `503 unavailable` за
ограниченное время.
- ORM-модели сущностей зон: `identity` (`users`, `sessions`) и `messaging` (`chats`, `chat_members`, `messages`,
`idempotency_keys`); запросы — ORM/Core API (`select`, `join`, `with_for_update`, `returning`, `tuple_`, `on_conflict_do_nothing`);
`sqlalchemy.text()` — точечно, где декларативно нельзя: одна команда отправки сообщения (CTE c `FOR UPDATE OF` и
частичным `ON CONFLICT … WHERE`) и advisory lock мигратора.
- pydantic-схемы остаются на границе API, ORM-модели — внутри адаптеров; порты (`IdentityUnitOfWork`,
`ChatRepository`, `MessageLog`, каталоги) и сборка в `ioc.py` не меняются.
- Собственный runner `messenger/migrate.py` и `messenger/migrations/*.sql` удаляются. Миграции — Alembic:
async `env.py`, каталог `alembic/`, журнал `alembic_version`, advisory lock сохранён; one-shot сервис `migrate`
в compose выполняет `alembic upgrade head`. Итоговая схема идентична прежней (те же таблицы, ограничения, индексы).
- Версии SQLAlchemy/Alembic закреплены в `pyproject.toml` (`uv lock`).
- Evidence, зависящее от поведения SQL (схема и миграции, отказы, нагрузки трека 1), перегенерировано на новом коде;
расхождения описаны в `REPORT.md` и `evidence/README.md`.
## Capabilities
### Modified Capabilities
- `lab2-persistent-storage`: миграции — ревизии Alembic с журналом `alembic_version` вместо SQL-файлов с контрольными
суммами; сценарий «изменённая миграция» уходит вместе с checksum-семантикой runner'а.
## Impact
- Код: `src/messenger/shared/infrastructure/postgres.py`, `src/messenger/{identity,messaging}/infrastructure/postgres.py`,
удаление `src/messenger/{migrate.py,migrations/}`; новый `alembic/` и `alembic.ini`.
- Стенд: `Dockerfile` (образ несёт `alembic/`), `compose.yaml` (команда сервиса `migrate`), `pyproject.toml`, `uv.lock`.
- Тесты: `student-tests/api/test_migrations.py`, `student-tests/conftest.py` (применение миграций), `test_pool.py`.
- Обвязка: `scripts/evidence-storage.sh` (журнал версий), `AGENTS.md`, `openspec/config.yaml`.
- Доказательства: `evidence/{schema,migrations,kdf,secrets}.txt`, `evidence/smoke.txt`, `evidence/track1/*`,
`REPORT.md`, `evidence/README.md`.
## Non-goals
Контракт, публичные тесты, `README.md`, `COURSE.md`, профиль нагрузки k6 и параметры LB не меняются. ORM не
расползается за адаптеры: домен, приложение и pydantic-граница не импортируют SQLAlchemy-модели. Схема не меняется:
те же таблицы, ограничения и индексы, только инструмент миграций. Out of scope из `config.yaml` в силе; лабы 1–2
не трогаются.
@@ -0,0 +1,35 @@
## MODIFIED Requirements
### Requirement: Версионируемые миграции
Схема SHALL создаваться только миграциями Alembic: упорядоченными файлами ревизий, каждая из которых применяется в своей транзакции и записывается в журнал `alembic_version`. Миграции SHALL применяться одним одноразовым процессом (`alembic upgrade head`) до старта реплик API, а не каждой репликой; одновременный запуск двух процессов SHALL сериализоваться advisory lock. Повторный запуск SHALL NOT менять схему и данные. Журнал SHALL ссылаться на существующие ревизии каталога миграций; ссылка на отсутствующую ревизию SHALL останавливать запуск с ошибкой. Итоговая схема SHALL совпадать со схемой прежнего мигратора: те же таблицы, ограничения и индексы. Новая миграция SHALL быть аддитивной: работающая предыдущая версия API SHALL продолжать работать на схеме после неё.
#### Scenario: Миграции с пустого volume
- **WHEN** стенд поднимается на пустом volume PostgreSQL
- **THEN** one-shot сервис `migrate` применяет все ревизии по порядку и завершается кодом 0, после чего стартуют реплики API
#### Scenario: Повторный запуск
- **WHEN** процесс миграций запускается повторно на той же БД
- **THEN** он завершается кодом 0, таблица `alembic_version` и число строк во всех таблицах не меняются
#### Scenario: Схема идентична прежней
- **WHEN** миграции применены на чистой БД
- **THEN** `\d+` показывает те же таблицы (`users`, `sessions`, `chats`, `chat_members`, `messages`, `idempotency_keys`), те же первичные ключи, `UNIQUE (username)`, внешние ключи, `CHECK` и индексы, что и до перевода на Alembic
#### Scenario: Применённая ревизия исчезла из каталога
- **WHEN** ревизия, записанная в `alembic_version`, отсутствует в каталоге миграций, и процесс миграций запущен
- **THEN** он завершается ненулевым кодом, не применяя других ревизий
#### Scenario: Реплики не мигрируют схему
- **WHEN** стартует или перезапускается реплика API
- **THEN** она не применяет миграции; таблицу `alembic_version` меняет только one-shot сервис `migrate`
#### Scenario: Одновременный запуск сериализуется
- **WHEN** два процесса миграций запускаются одновременно на одной БД
- **THEN** advisory lock пропускает их по одному, и журнал содержит каждую ревизию один раз
@@ -0,0 +1,30 @@
## 1. Зависимости и платформа
- [ ] 1.1 Закрепить `sqlalchemy>=2.0` и `alembic>=1.16` в `pyproject.toml`, прогнать `uv lock`; обновить per-file-ignores ruff (уходят `messenger/migrate.py` и миграции в `AGENTS.md`)
- [ ] 1.2 `shared/infrastructure/postgres.py`: `Base(DeclarativeBase)`, `Database` на `create_async_engine(postgresql+asyncpg)` + `async_sessionmaker`, прежние серверные настройки/таймауты/размер пула; `PostgresUnitOfWork` на `AsyncSession`; отображение соединительных отказов в `Unavailable` (503), `IntegrityError` проходит мимо
- [ ] 1.3 Проверка группы: `make lint`, `make student-test` (частично, до миграции адаптеров — падение ожидаемо), затем повторно после 2.x
## 2. Адаптеры зон
- [ ] 2.1 `identity/infrastructure/postgres.py`: ORM-модели `UserRow`, `SessionRow`; запросы через `select`/`pg_insert(...).on_conflict_do_nothing(...).returning(...)`/`delete`; порты и сборка не меняются
- [ ] 2.2 `messaging/infrastructure/postgres.py`: ORM-модели `ChatRow`, `ChatMemberRow`, `MessageRow`, `IdempotencyKeyRow`; каталоги и история декларативно (`func.array`, keyset `tuple_`), участники — executemany, `IntegrityError` FK → `InvalidChatData`; отправка сообщения остаётся одним оператором `text()` с прежним `FOR UPDATE OF` и порядком блокировок
- [ ] 2.3 Проверка группы: `make lint`, `make student-test` — все собственные тесты зелёные, поведение идемпотентности/гонок/503 не изменилось
## 3. Миграции Alembic
- [ ] 3.1 `alembic.ini` + `alembic/env.py` (async, DSN из `PlatformSettings`, advisory lock `20260002` на отдельном соединении, `transaction_per_migration`), ревизии `0001_init`, `0002_idempotency_keys` с дословным DDL прежних SQL-файлов; удалить `src/messenger/migrations/` и старый `messenger/migrate.py`
- [ ] 3.2 `Dockerfile` несёт `alembic.ini` и `alembic/`; compose-сервис `migrate` выполняет `alembic upgrade head`; `scripts/evidence-storage.sh` смотрит `alembic_version`
- [ ] 3.3 `student-tests/conftest.py` применяет миграции Alembic программно; `test_migrations.py` переписан под Alembic (порядок ревизий, повторный запуск — no-op, FK-сценарии схемы); `test_pool.py` под новый API `Database`
- [ ] 3.4 Проверка группы: `make check`, `make lint`, `make student-test`; свежая БД — схема `\d+` идентична прежней
## 4. Контекст и стенд
- [ ] 4.1 `AGENTS.md` и `openspec/config.yaml`: стек — SQLAlchemy 2.x async + Alembic (asyncpg — драйвер), описание `migrate`; правило «SQL только параметризованный» сохранено
- [ ] 4.2 Стенд из чистого состояния: `make up` (миграции один раз), `make test`, `make lb-check`, `make retry-check`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-faults`, `make restore`; `make level4` под нагрузкой
- [ ] 4.3 `evidence-storage.sh` прогон: `evidence/{schema,migrations,kdf,secrets}.txt` на новом коде; свежие `smoke.txt`, `student-tests.txt`, `checks.txt`
## 5. Трек 1 и отчёт
- [ ] 5.1 `make track1` на новом коде: снимок хоста, серии A/B, до/после, контроль, графики; расхождения против прежних серий описать
- [ ] 5.2 `REPORT.md` и `evidence/README.md`: новый SQL-слой, таблица версий `alembic_version`, расхождения измерений, номера коммитов прогонов
- [ ] 5.3 Проверка группы: `make check`, `make validate`, `make lint`, `make student-test`, `openspec validate --all --strict`; числа отчёта сверены с файлами `evidence/`