diff --git a/.claude/rules/migrations.md b/.claude/rules/migrations.md index 2f731130..0c5fa7da 100644 --- a/.claude/rules/migrations.md +++ b/.claude/rules/migrations.md @@ -44,10 +44,16 @@ paths: решение 7). - Первой строкой ревизии, которая берёт `ACCESS EXCLUSIVE` на рабочую таблицу (`ADD COLUMN`, `ALTER`), — `op.execute("SET LOCAL - lock_timeout = '5s'")`: в очереди за ожидающей блокировкой стоят + lock_timeout = '2s'")`: в очереди за ожидающей блокировкой стоят все новые запросы к таблице, и чужая долгая транзакция остановила бы запись всех реплик. По сроку миграция падает без изменений, замена не начинается, повтор проходит. + - `lock_timeout` миграции меньше `[database] statement_timeout_ms` + приложения (5 с) с запасом. Запросы в очереди за миграцией ждут + её отказа, и при равных сроках все они получали 503 вместе с ним: + 6 из 6 запросов в полёте (verify change `rolling-update`, + `evidence/rollout/script-failures.md`). С 2 с они дожидаются отказа + миграции и выполняются, цена — задержка до 2 с. - Модели — `src/infra/db/models/.py`. `Base` даёт `created_at` и `to_dict()`. Новая модель экспортируется в `models/__init__.py`, diff --git a/REPORT.md b/REPORT.md index 731cace6..c22923ec 100644 --- a/REPORT.md +++ b/REPORT.md @@ -289,11 +289,16 @@ contract): до новых реплик; - прежний код её не знает: вставляет свои колонки (NULL), читает свои. -Первой строкой ревизии — `SET LOCAL lock_timeout = '5s'`. `ADD COLUMN` +Первой строкой ревизии — `SET LOCAL lock_timeout = '2s'`. `ADD COLUMN` берёт `ACCESS EXCLUSIVE` на миллисекунды, но, пока ждёт блокировку, за ним в очереди стоят все запросы к `messages`. Чужая долгая транзакция без срока остановила бы запись всех реплик. Со сроком миграция падает -без изменений, замена не начинается, повтор проходит. +без изменений, замена не начинается, повтор проходит. Срок меньше +`statement_timeout` приложения (5 с): запросы из очереди дожидаются +отказа миграции и выполняются. В apply срок был 5 с, равный +`statement_timeout`, и verify поймал цену: под нагрузкой все 6 запросов, +вставших в очередь, получили 503 вместе с отказом миграции; с 2 с — 0 +ошибок, задержка до 2 с (`evidence/rollout/script-failures.md`). Проверено на рабочем стенде (`evidence/rollout/compatibility.md`): - реплики образа `c50b721` (до change) на схеме после новой миграции @@ -718,10 +723,12 @@ TODO: какие отказы выдерживаются и какие нет; колонку можно только отдельной миграцией, когда кода, который её пишет, не осталось. `downgrade` новой ревизии удаляет колонку и допустим только тогда же. -- **`lock_timeout` 5 с.** Под тяжёлой записью миграция может не +- **`lock_timeout` 2 с.** Под тяжёлой записью или во время `pg_dump` + (он держит `ACCESS SHARE` на все таблицы до конца) миграция может не дождаться блокировки и упасть. Тогда замена не начинается, повтор проходит. Это осознанный выбор: иначе очередь всех записей ждала бы - за миграцией. + за миграцией. Пока миграция ждёт, запросы к `messages` стоят в + очереди до 2 с. - **Сборка образа идёт на том же хосте, под нагрузкой.** Из кэша слоёв — секунды CPU ВМ Docker. - **SIGTERM во время старта реплики теряется** (процесс с PID 1 до diff --git a/migrations/versions/2026_10_11_0026-e656d6bbe1a4_added_message_instance_id.py b/migrations/versions/2026_10_11_0026-e656d6bbe1a4_added_message_instance_id.py index b055ecb9..fde99352 100644 --- a/migrations/versions/2026_10_11_0026-e656d6bbe1a4_added_message_instance_id.py +++ b/migrations/versions/2026_10_11_0026-e656d6bbe1a4_added_message_instance_id.py @@ -28,8 +28,12 @@ def upgrade() -> None: # ACCESS EXCLUSIVE на messages берётся на миллисекунды, но в очереди # за ним ждут все новые запросы к таблице: чужая долгая транзакция не # должна заставить миграцию держать эту очередь. По сроку — ошибка без - # изменений схемы, замена не начинается, повтор проходит - op.execute("SET LOCAL lock_timeout = '5s'") + # изменений схемы, замена не начинается, повтор проходит. + # Срок меньше statement_timeout приложения (5 с) с запасом: запросы, + # вставшие в очередь, дожидаются отказа миграции и выполняются. При + # равных сроках они получали 503 вместе с её отказом (verify change + # rolling-update, решение 12) + op.execute("SET LOCAL lock_timeout = '2s'") op.add_column( "messages", sa.Column("instance_id", sa.Text(), nullable=True), diff --git a/openspec/changes/rolling-update/design.md b/openspec/changes/rolling-update/design.md index 8647fe12..54efe316 100644 --- a/openspec/changes/rolling-update/design.md +++ b/openspec/changes/rolling-update/design.md @@ -299,10 +299,12 @@ tar-контексту. Рабочее дерево, индекс и HEAD не без перезаписи таблицы. Блокировка `ACCESS EXCLUSIVE` берётся на миллисекунды, но в очереди за ней ждут все новые запросы к `messages`. Поэтому первой строкой ревизии идёт `SET LOCAL - lock_timeout = '5s'`: + lock_timeout = '2s'` (в apply было 5 с, решение 12): - чужая долгая транзакция не заставит миграцию держать очередь; - по сроку миграция падает, схема не меняется, и замена не начинается (спек `db-migrations`); + - запросы, вставшие в очередь за миграцией, дожидаются её отказа и + выполняются: срок меньше `statement_timeout` приложения (5 с); - повторный запуск проходит. - `downgrade` удаляет колонку. Это шаг contract, допустимый только после того, как не осталось нового кода. @@ -483,6 +485,19 @@ containerd `docker ps` показывает у реплик digest конфиг N)`: 0 — graceful, 137 — SIGKILL по сроку (спек `graceful-shutdown`, «Остановка за заявленный срок после дренажа»). Контейнер удаляется сразу, без строки код выхода не восстановить. +- **`lock_timeout` 5 с равнялся `statement_timeout` приложения (5 с).** + Повтор случая «миграция не получила блокировку» под нагрузкой (4 + записи и 2 чтения подряд через LB): все 6 запросов, вставших в очередь + за `ALTER`, через 5,03 с получили 503 — `canceling statement due to + statement timeout` в журнале реплик. Их срок истекал одновременно с + отказом миграции. Теперь `lock_timeout` 2 с: очередь ждёт до 2 с и + выполняется после отказа миграции. Ревизия `e656d6bbe1a4` правится на + месте, а не новой ревизией поверх: новая ревизия не изменила бы, как + выполняется уже записанный `ALTER`. Правка меняет только срок + ожидания, а не итоговую схему, и ревизия ещё не применена ни к одной + долгоживущей базе: рабочий стенд пересоздан на `7652184b7016` для + повтора совместимости, стенды `bench/`, `test_isolated` и проверок + отказов временные. - **Откат оставляет тег на прежнем образе.** `docker compose up` без сборки пересоздал бы `migrate` на прежнем образе, и он упал бы на новой ревизии. Это ограничение отката без отката схемы, а не дефект @@ -493,8 +508,9 @@ containerd `docker ps` показывает у реплик digest конфиг `d2148ac`, до исправления шага миграций), самопроверки быстрых профилей — на чистом дереве. Замер `baseline` не переснимался: правки не меняют порядок замены и то, что видит клиент (одна `docker - inspect` после остановки), а быстрый профиль на итоговом commit это - подтверждает. + inspect` после остановки; `lock_timeout` действует только при чужой + блокировке, а в замере миграция получает её за миллисекунды), а + быстрый профиль на итоговом commit это подтверждает. ## Risks / Trade-offs @@ -503,10 +519,12 @@ containerd `docker ps` показывает у реплик digest конфиг порту 9999 LB из другого контейнера сети (`script-failures.md`). Доступ через `docker exec` равен доступу к Docker, то есть ко всему стенду. -- **[`lock_timeout` 5 с может не хватить под тяжёлой записью]** → +- **[`lock_timeout` 2 с может не хватить под тяжёлой записью]** → миграция падает без изменений, замена не начинается, повтор проходит. Это лучше, чем очередь всех записей за миграцией. Без нагрузки - блокировка берётся за миллисекунды. + блокировка берётся за миллисекунды. Больше `statement_timeout` + приложения (5 с) срок брать нельзя, равным — тоже: запросы в очереди + за миграцией получили бы 503 вместе с её отказом (решение 12). - **[Новый код на старой схеме падает]** → только если миграцию пропустить при движении вперёд. Скрипт пропускает её лишь по явному `MIGRATE=0` (откат). Порядок «миграция → новые реплики» закреплён в diff --git a/openspec/changes/rolling-update/specs/db-migrations/spec.md b/openspec/changes/rolling-update/specs/db-migrations/spec.md index 73ed3b79..61a2d6aa 100644 --- a/openspec/changes/rolling-update/specs/db-migrations/spec.md +++ b/openspec/changes/rolling-update/specs/db-migrations/spec.md @@ -22,9 +22,12 @@ Ожидание блокировки таблицы миграцией SHALL быть ограничено сроком. Долгая транзакция приложения не должна заставить миграцию держать -очередь за собой и остановить запись остальных реплик. По истечении -срока миграция SHALL завершаться ошибкой без изменения схемы, а её -повторный запуск SHALL проходить. +очередь за собой и остановить запись остальных реплик. Срок SHALL быть +меньше срока запроса приложения к БД (`statement_timeout`): запросы, +вставшие в очередь за миграцией, дожидаются её отказа и выполняются, а +не завершаются ошибкой вместе с ним. По истечении срока миграция SHALL +завершаться ошибкой без изменения схемы, а её повторный запуск SHALL +проходить. #### Scenario: Старый образ на новой схеме @@ -44,9 +47,9 @@ - **WHEN** таблицу, которую меняет миграция, держит открытая транзакция дольше срока ожидания блокировки -- **THEN** миграция завершается ошибкой, схема не меняется, запись - других клиентов продолжается, а после окончания транзакции повторный - запуск применяет миграцию +- **THEN** миграция завершается ошибкой, схема не меняется, запросы + других клиентов, ждавшие за миграцией, получают успешный ответ, а + после окончания транзакции повторный запуск применяет миграцию ### Requirement: Однократные миграции при замене реплик diff --git a/openspec/changes/rolling-update/tasks.md b/openspec/changes/rolling-update/tasks.md index 08b037ab..d1660627 100644 --- a/openspec/changes/rolling-update/tasks.md +++ b/openspec/changes/rolling-update/tasks.md @@ -189,6 +189,12 @@ Evidence снимается с закоммиченного кода: комми а не `run --rm`), `bench.md` (отказ профиля без `UP`), дельта `load-balancing`, `REPORT.md`, скилл. Проверка: `make lint`, `dash -n`, `openspec validate rolling-update --strict`, коммит кода. +- [x] 7.1a `lock_timeout` ревизии `e656d6bbe1a4` — 2 с вместо 5 с (меньше + `statement_timeout` приложения): при 5 с запросы в очереди за + миграцией получали 503 вместе с её отказом. Дельта `db-migrations`, + `migrations.md`, design (решения 7 и 12), `REPORT.md`. Проверка: + случай «миграция не получила блокировку» под нагрузкой — 0 ошибок, + коммит кода. - [ ] 7.2 Evidence на итоговом commit кода: - `compatibility.md` — шаги A–G заново, с журналом остановки старых реплик, `--dry-run` после отката и жизненным циклом стенда после