Document SQLAlchemy migration checks and remaining evidence work

This commit is contained in:
Artyom
2026-11-05 21:41:47 +03:00
parent 66c614426c
commit 7fc911c332
6 changed files with 85 additions and 29 deletions
+2 -1
View File
@@ -52,7 +52,8 @@ make down # остановка без удаления д
## Правила работы с репозиторием
- Не менять и не ослаблять `contracts/`, `tests/`, `README.md`, `COURSE.md`, рубрику. Расхождение оформляется вопросом преподавателю.
- Код — `src/messenger/`, миграции — `src/messenger/migrations/NNNN_*.sql`, конфигурация LB и нагрузки — `infra/`, хуки и обвязка стенда — `scripts/`, собственные тесты — `student-tests/`, обезличенные доказательства — `evidence/` (индекс — `evidence/README.md`, первая строка каждого файла — дата и коммит прогона).
- Код — `src/messenger/`, миграции — `alembic/versions/*.py`, конфигурация LB и нагрузки — `infra/`, хуки и обвязка стенда — `scripts/`, собственные тесты — `student-tests/`, обезличенные доказательства — `evidence/` (индекс — `evidence/README.md`, первая строка каждого файла — дата и коммит прогона).
- PostgreSQL — SQLAlchemy 2.0 async (`async_sessionmaker`, `DeclarativeBase`); asyncpg только драйвер. ORM/Core остаются в инфраструктуре, домен — dataclass, pydantic — на HTTP-границе. Миграции — только `alembic upgrade head` в one-shot сервисе `migrate`. Старую схему принимает `alembic/legacy.py` после проверки журнала и каталога PostgreSQL; безусловный `stamp` запрещён. Старый журнал сохраняется, volumes не удаляются.
- Без комментариев в коде; отступы — пробелы (`[tool.ruff.format]`); Python 3.14 без `from __future__ import annotations` и `TYPE_CHECKING`.
- Порты реплик API наружу не публикуются: только LB. Нет `container_name`, `hostname` и общего `INSTANCE_ID` у сервиса `api`.
- `REPORT.md`: команды из чистого clone, архитектура, таблица «критерий → команда → наблюдение → файл», таблица отказов, трек 1, ответы на вопросы защиты. PASS без команды не доказательство; для отказов — какой контейнер реально остановлен (`docker ps -a`). Цифры в отчёте берутся только из файлов `evidence/`.
@@ -6,7 +6,8 @@
получаем — единый декларативный слой запросов (`select`, `join`, `with_for_update`, `returning`), типизированные
ORM-модели сущностей, переносимый пул и механизм сессий, индустриальный мигратор с журналом ревизий и autogenerate
на будущее; платим — лишним слоем трансляции (SQL компилируется в asyncpg-протокол через greenlet), меньшей
прозрачностью низкоуровневых параметров соединения и четырьмя точечными `text()` там, где декларативно не выражается.
прозрачностью низкоуровневых параметров соединения и проверкой старой схемы через PostgreSQL-каталог;
запросы приложения полностью выражены ORM/Core.
Зоны, порты и наблюдаемое поведение API не меняются — меняется только транспорт SQL за портами.
## Порты, адаптеры, сборка
@@ -28,9 +29,9 @@ ORM-модели сущностей, переносимый пул и механ
Типы колонок заданы явно там, где это важно для asyncpg: `DateTime(timezone=True)` у всех `timestamptz`,
`LargeBinary` у `bytea`, `SmallInteger` у `position`. Зоны не импортируют модели друг друга: перекрёстный внешний
ключ `chat_members.user_id → users.id` объявлен только в миграции, а не в ORM, — связь зон остаётся ограничением
целостности схемы, и ни одна зона не получает тип другой зоны; цена связи уже была заплачена на уровне SQL и здесь
не растёт.
ключ `chat_members.user_id → users.id` объявлен строковым `ForeignKey("users.id")`, без импорта модели identity.
Модели описывают также CHECK, UNIQUE и индексы, чтобы autogenerate не предлагал удалить существующие ограничения.
Связь зон остаётся ограничением схемы: SQL одной зоны не читает таблицы другой.
## Пул, сессии, транзакции, отказ
@@ -59,11 +60,13 @@ db_acquire_timeout_seconds`, `pool_recycle = 60`. `session()` — контекс
`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` сообщения,
Отправка сообщения также выражена Core: `select(...).with_for_update(of=chats)` →
`insert(...).from_select(...).on_conflict_do_update(where=...)` → INSERT сообщения → UPDATE времени чата.
Все четыре CTE остаются в одном операторе через `cte()` / `add_cte()`. Блокировка чата предшествует блокировке
квитанции ключа; истёкший ключ заменяется, действующий читается следующим SELECT с новым snapshot READ COMMITTED.
`text()` нужен только для чтения специфического каталога PostgreSQL при принятии старой схемы.
Индексы остаются прежними; планы и производительность необходимо измерить заново:
`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 и сравнивается с прежним.
@@ -71,14 +74,24 @@ evidence и сравнивается с прежним.
## Миграции: Alembic
- Каталог `alembic/` с async `env.py`, `alembic.ini` в корне; ревизии `0001_init`, `0002_idempotency_keys`
воспроизводят прежние SQL-файлы дословно (те же таблицы, ограничения, индексы), `transaction_per_migration` —
сгенерированы из metadata операциями Alembic и выверены против прежнего DDL (те же таблицы, ограничения,
индексы); `transaction_per_migration` —
каждая ревизия в своей транзакции, как раньше. Итоговая схема идентична прежней — проверяется свежим стендом
(`evidence/schema.txt`, `\d+`).
- Журнал — штатная таблица `alembic_version` вместо `schema_migrations`; контрольных сумм Alembic не хранит, поэтому
сценарий «изменённая миграция» из capability `lab2-persistent-storage` уходит; порядок и однократность
- Журнал новых запусков — штатная таблица `alembic_version`; Alembic не хранит контрольные суммы.
Для старого `schema_migrations` проверяются известные SHA-256 и непрерывный префикс ревизий.
Сценарий изменённой Alembic-ревизии заменён проверкой отсутствующей ревизии; порядок и однократность
(`transaction_per_migration`, один одноразовый процесс) сохраняются.
- Сериализация одновременных запусков — прежний session-level advisory lock `20260002`, выполняется в `env.py`
на отдельном соединении (session-level переживает commit), снимается в `finally`.
- Переход существующей БД: `legacy.py` сверяет журнал и структуру схемы (`pg_catalog`: колонки, типы, collation, постоянство таблиц,
NULL/default, PK/UNIQUE/CHECK/FK, валидность ограничений и индексов, триггеры/RLS) с эталоном, создаваемым
историческими ревизиями в отдельной проверочной схеме внутри откатываемого SAVEPOINT. Только после совпадения
вызывается `MigrationContext.stamp` проверенной ревизией. Затем обычный upgrade применяет недостающие ревизии.
Неизвестная/изменённая/неполная история и расхождение схемы прерывают переход без stamp и изменения данных.
Без журнала непустая схема также отклоняется. Старый журнал сохраняется для аудита и возврата старого образа.
Обратный `downgrade` запрещён, так как удалял бы пользовательские таблицы; откат приложения сохраняет схему.
Старые SQL-файлы остаются только неизменяемыми fixtures для тестирования перехода, не runner-ом приложения.
- One-shot сервис `migrate` в compose выполняет `alembic upgrade head`; образ приложения несёт `alembic.ini` и
`alembic/` (правки `Dockerfile`); сервис по-прежнему non-root, одноразовый, до старта реплик. Повторный запуск —
no-op. `scripts/rolling-update.sh` не меняется: миграции применяются один раз перед заменой первой реплики.
@@ -106,3 +119,13 @@ Evidence, зависящее от поведения SQL: схема и мигр
(failover, persistence, faults, retry), серии трека 1 и планы запросов — на новом коде; расхождения (новые
top-операторы SQLAlchemy, разница в RPS/латентности, таблица версий) фиксируются в `REPORT.md` и
`evidence/README.md`.
## Проверки этапа и оставшаяся работа
Зафиксированные версии: SQLAlchemy 2.0.45, Alembic 1.16.5. API сверено через Context7:
[SQLAlchemy CTE/asyncio](https://github.com/sqlalchemy/sqlalchemy/tree/rel_2_0_45/doc/build),
[Alembic async cookbook](https://github.com/sqlalchemy/alembic/blob/rel_1_16_5/docs/build/cookbook.rst).
Миграционные тесты проверяют свежую БД, переход с 0001/0002 с сохранением каждой строки, повреждения схемы,
неизвестную ревизию, повторный и конкурентный запуск. Пул проверяется на rollback, таймаутах и отмене запроса.
Полный стенд уровней 3/4, evidence и измерения трека 1 выполняются следующими этапами; прежние цифры
не подтверждают производительность SQLAlchemy. Change остаётся активным до этих прогонов и обновления отчёта.
@@ -15,13 +15,14 @@ chunked-лимит) сохраняются. Уровни «3» и «4» держ
ограниченное время.
- 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 мигратора.
отправка сообщения также остаётся одной Core-командой из CTE с `FOR UPDATE OF` и `ON CONFLICT … WHERE`.
`sqlalchemy.text()` используется только для специфического каталога PostgreSQL при переходе старой схемы.
- 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`.
@@ -33,3 +33,13 @@
- **WHEN** два процесса миграций запускаются одновременно на одной БД
- **THEN** advisory lock пропускает их по одному, и журнал содержит каждую ревизию один раз
#### Scenario: Принятие существующей схемы
- **WHEN** БД содержит схему прежнего SQL-мигратора и известный непрерывный журнал `schema_migrations`
- **THEN** переход сверяет контрольные суммы и фактическую схему с указанными ревизиями, сохраняет все строки и старый журнал, устанавливает проверенную ревизию Alembic и применяет только недостающие ревизии
#### Scenario: Несогласованная старая схема
- **WHEN** старый журнал неизвестен, изменён или неполон либо фактическая схема расходится с ним
- **THEN** процесс завершается ошибкой без установки версии Alembic и изменения пользовательских данных
@@ -1,25 +1,25 @@
## 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
- [x] 1.1 Закрепить `sqlalchemy==2.0.45` и `alembic==1.16.5` в `pyproject.toml`, прогнать `uv lock`; обновить per-file-ignores ruff (уходят `messenger/migrate.py` и миграции в `AGENTS.md`)
- [x] 1.2 `shared/infrastructure/postgres.py`: `Base(DeclarativeBase)`, `Database` на `create_async_engine(postgresql+asyncpg)` + `async_sessionmaker`, прежние серверные настройки/таймауты/размер пула; `PostgresUnitOfWork` на `AsyncSession`; отображение соединительных отказов в `Unavailable` (503), `IntegrityError` проходит мимо
- [x] 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 не изменилось
- [x] 2.1 `identity/infrastructure/postgres.py`: ORM-модели `UserRow`, `SessionRow`; запросы через `select`/`pg_insert(...).on_conflict_do_nothing(...).returning(...)`/`delete`; порты и сборка не меняются
- [x] 2.2 `messaging/infrastructure/postgres.py`: ORM-модели `ChatRow`, `ChatMemberRow`, `MessageRow`, `IdempotencyKeyRow`; каталоги и история декларативно (`func.array`, keyset `tuple_`), участники — executemany, `IntegrityError` FK → `InvalidChatData`; отправка сообщения остаётся одним оператором Core CTE с прежним `FOR UPDATE OF` и порядком блокировок
- [x] 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+` идентична прежней
- [x] 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`
- [x] 3.2 `Dockerfile` несёт `alembic.ini` и `alembic/`; compose-сервис `migrate` выполняет `alembic upgrade head`; `scripts/evidence-storage.sh` смотрит `alembic_version`
- [x] 3.3 `student-tests/conftest.py` применяет миграции Alembic программно; `test_migrations.py` переписан под Alembic (порядок ревизий, повторный запуск — no-op, FK-сценарии схемы, сохранение данных 0001/0002, повреждённая схема, конкурентные процессы); `test_pool.py` под новый API `Database`
- [x] 3.4 Проверка группы: `make check`, `make lint`, `make student-test`; свежая БД — сравнение metadata/Alembic и каталога PostgreSQL с прежней схемой
## 4. Контекст и стенд
- [ ] 4.1 `AGENTS.md` и `openspec/config.yaml`: стек — SQLAlchemy 2.x async + Alembic (asyncpg — драйвер), описание `migrate`; правило «SQL только параметризованный» сохранено
- [x] 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`
@@ -28,3 +28,24 @@
- [ ] 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/`
## Результат этапа sqlalchemy-alembic — 2026-11-05
Код проверен на `66c614426c9265a03843a9dc39678ac1cd3c1e99`. Выполнено 11 из 16 задач change; задачи 4.2–5.3
остаются для последовательных этапов стенда, evidence и трека. Архивация не выполнялась.
- `make check`, `make validate`, `make lint` — PASS; lint включает `alembic/`.
- `make student-test` — 270 passed, 12 deselected (штатный маркер `stack`), 29.84 с.
Включены 22 теста миграций: свежая БД, старая схема 0001/0002 с сохранением всех строк,
повреждённый журнал/структура/collation/UNLOGGED, rollback неудачной ревизии, повтор и два процесса.
- `uv lock --check` — PASS; SQLAlchemy 2.0.45, Alembic 1.16.5.
- `openspec validate --all --strict` — 15 passed, 0 failed.
- `LB_HTTP_PORT=18083 LB_STATS_PORT=23083 docker compose build api` — PASS.
`alembic history` внутри образа видит обе ревизии. Два `alembic upgrade head` из образа
против отдельного PostgreSQL на tmpfs завершились с 0002_idempotency_keys.
- Начальные `ruff`/`ty` и `student-test` не проходили: исправлены аннотации SQLAlchemy,
проверка ORM-таблиц вместо только SQL-строк, локальная HTTPX-проба с системным прокси
и негативная UNLOGGED-fixture (изменяется листовая таблица sessions, без блокировки FK).
Итоговые проверки выше выполнены после исправлений.
- Одноразовые тестовые контейнеры остановлены; существующие volumes и другие лабораторные
не изменялись. Публикаций и отправок Telegram не было.
+3 -3
View File
@@ -29,7 +29,7 @@ context: |
Python 3.14 (аннотации вычисляются лениво по PEP 649, `TYPE_CHECKING` и
`from __future__ import annotations` не используются), FastAPI, gunicorn с несколькими
`UvicornWorker` (пакет `uvicorn-worker`), dishka (DI), pydantic v2 + pydantic-settings, structlog,
asyncpg (параметризованный SQL без ORM), redis-py (`redis.asyncio`) для Valkey, argon2-cffi,
SQLAlchemy 2.0 async (ORM/Core за портами, asyncpg только драйвер), Alembic, redis-py (`redis.asyncio`) для Valkey, argon2-cffi,
pytest + pytest-asyncio + httpx. Зависимости — uv и `uv.lock`; ruff и ty обязательны на `src/`,
`student-tests/` и Python-обвязке стенда; `scripts/*.py` держат синтаксис Python 3.9 и stdlib.
@@ -48,7 +48,7 @@ context: |
(`openspec/notes/architecture-patterns-python.md`), развёрнутый N одинаковыми репликами:
main.py сборка приложения: собирает вклады зон в один процесс
migrate.py одноразовая точка входа: применяет SQL-миграции под advisory lock
alembic/ ревизии и async env.py: alembic upgrade head под advisory lock
gunicorn_conf.py конфигурация процесса: воркеры, окно вывода из ротации по SIGTERM
(DrainingServer, MessengerWorker; флаг вывода — shared/infrastructure/readiness)
identity/ пользователи, пароли и сессии: ошибки, события, команды, значения, порты,
@@ -137,7 +137,7 @@ operations:
- "Логирование — только через порт `Logger`; второй логгер в приложении не заводится, сообщения сервера и библиотек идут через тот же поток."
- "Код приложения — в `src/`, конфигурация LB и нагрузки — в `infra/`, собственные тесты — в `student-tests/`, обезличенные доказательства — в `evidence/`."
- "Перед коммитом прогоняй `make lint`, `make student-test` и `make check`."
- "SQL только параметризованный (`$1`, `$2`); значения из запроса никогда не склеиваются в текст запроса."
- "SQL только параметризованный (bind-параметры SQLAlchemy); значения из запроса никогда не склеиваются в текст запроса."
- "Реплика не хранит в памяти процесса ничего, от чего зависит корректность ответа другой реплики: сессии, ключи идемпотентности и курсоры проверяются через общее хранилище или общий секрет."
- "Ошибка зависимости (PostgreSQL, Valkey) превращается в `503 unavailable` за ограниченное время; отказ кэша обходится и никогда не превращается в анонимный доступ."
- "Схема меняется только новым файлом миграции; применённую миграцию не редактируют; миграция совместима с работающей предыдущей версией."