forked from mtusi2026/mtusi2026lab3
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:
@@ -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
|
||||
не трогаются.
|
||||
+35
@@ -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/`
|
||||
Reference in New Issue
Block a user