From c5f39dea2575831933ac29af84708af91a8fd563 Mon Sep 17 00:00:00 2001 From: Artyom Date: Thu, 5 Nov 2026 00:46:59 +0300 Subject: [PATCH] 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 --- .../.openspec.yaml | 3 + .../design.md | 108 ++++++++++++++++++ .../proposal.md | 50 ++++++++ .../specs/lab2-persistent-storage/spec.md | 35 ++++++ .../tasks.md | 30 +++++ 5 files changed, 226 insertions(+) create mode 100644 openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/.openspec.yaml create mode 100644 openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/design.md create mode 100644 openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/proposal.md create mode 100644 openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/specs/lab2-persistent-storage/spec.md create mode 100644 openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/tasks.md diff --git a/openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/.openspec.yaml b/openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/.openspec.yaml new file mode 100644 index 00000000..8e100f47 --- /dev/null +++ b/openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/.openspec.yaml @@ -0,0 +1,3 @@ +schema: spec-driven +created: 2026-11-05 +lab: 3 diff --git a/openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/design.md b/openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/design.md new file mode 100644 index 00000000..5e9bd156 --- /dev/null +++ b/openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/design.md @@ -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`. diff --git a/openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/proposal.md b/openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/proposal.md new file mode 100644 index 00000000..c2d93749 --- /dev/null +++ b/openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/proposal.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 +не трогаются. diff --git a/openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/specs/lab2-persistent-storage/spec.md b/openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/specs/lab2-persistent-storage/spec.md new file mode 100644 index 00000000..a0760db3 --- /dev/null +++ b/openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/specs/lab2-persistent-storage/spec.md @@ -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 пропускает их по одному, и журнал содержит каждую ревизию один раз diff --git a/openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/tasks.md b/openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/tasks.md new file mode 100644 index 00000000..7ac85089 --- /dev/null +++ b/openspec/changes/2026-11-05-adopt-sqlalchemy-alembic/tasks.md @@ -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/`