fix: keep migration lock timeout below the app statement timeout

With lock_timeout equal to statement_timeout (5 s) every request queued
behind a migration waiting for its lock failed with 503 together with
the migration. A 2 s lock timeout lets the queue proceed once the
migration gives up.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-11 01:38:10 +03:00
co-authored by Claude Opus 5.5
parent 5e102e6d0c
commit 84161c033a
6 changed files with 62 additions and 18 deletions
+7 -1
View File
@@ -44,10 +44,16 @@ paths:
решение 7). решение 7).
- Первой строкой ревизии, которая берёт `ACCESS EXCLUSIVE` на - Первой строкой ревизии, которая берёт `ACCESS EXCLUSIVE` на
рабочую таблицу (`ADD COLUMN`, `ALTER`), — `op.execute("SET LOCAL рабочую таблицу (`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/<domain>.py`. `Base` даёт `created_at` - Модели — `src/infra/db/models/<domain>.py`. `Base` даёт `created_at`
и `to_dict()`. Новая модель экспортируется в `models/__init__.py`, и `to_dict()`. Новая модель экспортируется в `models/__init__.py`,
+11 -4
View File
@@ -289,11 +289,16 @@ contract):
до новых реплик; до новых реплик;
- прежний код её не знает: вставляет свои колонки (NULL), читает свои. - прежний код её не знает: вставляет свои колонки (NULL), читает свои.
Первой строкой ревизии — `SET LOCAL lock_timeout = '5s'`. `ADD COLUMN` Первой строкой ревизии — `SET LOCAL lock_timeout = '2s'`. `ADD COLUMN`
берёт `ACCESS EXCLUSIVE` на миллисекунды, но, пока ждёт блокировку, за берёт `ACCESS EXCLUSIVE` на миллисекунды, но, пока ждёт блокировку, за
ним в очереди стоят все запросы к `messages`. Чужая долгая транзакция ним в очереди стоят все запросы к `messages`. Чужая долгая транзакция
без срока остановила бы запись всех реплик. Со сроком миграция падает без срока остановила бы запись всех реплик. Со сроком миграция падает
без изменений, замена не начинается, повтор проходит. без изменений, замена не начинается, повтор проходит. Срок меньше
`statement_timeout` приложения (5 с): запросы из очереди дожидаются
отказа миграции и выполняются. В apply срок был 5 с, равный
`statement_timeout`, и verify поймал цену: под нагрузкой все 6 запросов,
вставших в очередь, получили 503 вместе с отказом миграции; с 2 с — 0
ошибок, задержка до 2 с (`evidence/rollout/script-failures.md`).
Проверено на рабочем стенде (`evidence/rollout/compatibility.md`): Проверено на рабочем стенде (`evidence/rollout/compatibility.md`):
- реплики образа `c50b721` (до change) на схеме после новой миграции - реплики образа `c50b721` (до change) на схеме после новой миграции
@@ -718,10 +723,12 @@ TODO: какие отказы выдерживаются и какие нет;
колонку можно только отдельной миграцией, когда кода, который её колонку можно только отдельной миграцией, когда кода, который её
пишет, не осталось. `downgrade` новой ревизии удаляет колонку и пишет, не осталось. `downgrade` новой ревизии удаляет колонку и
допустим только тогда же. допустим только тогда же.
- **`lock_timeout` 5 с.** Под тяжёлой записью миграция может не - **`lock_timeout` 2 с.** Под тяжёлой записью или во время `pg_dump`
(он держит `ACCESS SHARE` на все таблицы до конца) миграция может не
дождаться блокировки и упасть. Тогда замена не начинается, повтор дождаться блокировки и упасть. Тогда замена не начинается, повтор
проходит. Это осознанный выбор: иначе очередь всех записей ждала бы проходит. Это осознанный выбор: иначе очередь всех записей ждала бы
за миграцией. за миграцией. Пока миграция ждёт, запросы к `messages` стоят в
очереди до 2 с.
- **Сборка образа идёт на том же хосте, под нагрузкой.** Из кэша слоёв - **Сборка образа идёт на том же хосте, под нагрузкой.** Из кэша слоёв
— секунды CPU ВМ Docker. — секунды CPU ВМ Docker.
- **SIGTERM во время старта реплики теряется** (процесс с PID 1 до - **SIGTERM во время старта реплики теряется** (процесс с PID 1 до
@@ -28,8 +28,12 @@ def upgrade() -> None:
# ACCESS EXCLUSIVE на messages берётся на миллисекунды, но в очереди # 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( op.add_column(
"messages", "messages",
sa.Column("instance_id", sa.Text(), nullable=True), sa.Column("instance_id", sa.Text(), nullable=True),
+23 -5
View File
@@ -299,10 +299,12 @@ tar-контексту. Рабочее дерево, индекс и HEAD не
без перезаписи таблицы. Блокировка `ACCESS EXCLUSIVE` берётся на без перезаписи таблицы. Блокировка `ACCESS EXCLUSIVE` берётся на
миллисекунды, но в очереди за ней ждут все новые запросы к миллисекунды, но в очереди за ней ждут все новые запросы к
`messages`. Поэтому первой строкой ревизии идёт `SET LOCAL `messages`. Поэтому первой строкой ревизии идёт `SET LOCAL
lock_timeout = '5s'`: lock_timeout = '2s'` (в apply было 5 с, решение 12):
- чужая долгая транзакция не заставит миграцию держать очередь; - чужая долгая транзакция не заставит миграцию держать очередь;
- по сроку миграция падает, схема не меняется, и замена не - по сроку миграция падает, схема не меняется, и замена не
начинается (спек `db-migrations`); начинается (спек `db-migrations`);
- запросы, вставшие в очередь за миграцией, дожидаются её отказа и
выполняются: срок меньше `statement_timeout` приложения (5 с);
- повторный запуск проходит. - повторный запуск проходит.
- `downgrade` удаляет колонку. Это шаг contract, допустимый только - `downgrade` удаляет колонку. Это шаг contract, допустимый только
после того, как не осталось нового кода. после того, как не осталось нового кода.
@@ -483,6 +485,19 @@ containerd `docker ps` показывает у реплик digest конфиг
N)`: 0 — graceful, 137 — SIGKILL по сроку (спек `graceful-shutdown`, 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` без - **Откат оставляет тег на прежнем образе.** `docker compose up` без
сборки пересоздал бы `migrate` на прежнем образе, и он упал бы на сборки пересоздал бы `migrate` на прежнем образе, и он упал бы на
новой ревизии. Это ограничение отката без отката схемы, а не дефект новой ревизии. Это ограничение отката без отката схемы, а не дефект
@@ -493,8 +508,9 @@ containerd `docker ps` показывает у реплик digest конфиг
`d2148ac`, до исправления шага миграций), самопроверки быстрых `d2148ac`, до исправления шага миграций), самопроверки быстрых
профилей — на чистом дереве. Замер `baseline` не переснимался: правки профилей — на чистом дереве. Замер `baseline` не переснимался: правки
не меняют порядок замены и то, что видит клиент (одна `docker не меняют порядок замены и то, что видит клиент (одна `docker
inspect` после остановки), а быстрый профиль на итоговом commit это inspect` после остановки; `lock_timeout` действует только при чужой
подтверждает. блокировке, а в замере миграция получает её за миллисекунды), а
быстрый профиль на итоговом commit это подтверждает.
## Risks / Trade-offs ## Risks / Trade-offs
@@ -503,10 +519,12 @@ containerd `docker ps` показывает у реплик digest конфиг
порту 9999 LB из другого контейнера сети (`script-failures.md`). порту 9999 LB из другого контейнера сети (`script-failures.md`).
Доступ через `docker exec` равен доступу к Docker, то есть ко всему Доступ через `docker exec` равен доступу к Docker, то есть ко всему
стенду. стенду.
- **[`lock_timeout` 5 с может не хватить под тяжёлой записью]** → - **[`lock_timeout` 2 с может не хватить под тяжёлой записью]** →
миграция падает без изменений, замена не начинается, повтор проходит. миграция падает без изменений, замена не начинается, повтор проходит.
Это лучше, чем очередь всех записей за миграцией. Без нагрузки Это лучше, чем очередь всех записей за миграцией. Без нагрузки
блокировка берётся за миллисекунды. блокировка берётся за миллисекунды. Больше `statement_timeout`
приложения (5 с) срок брать нельзя, равным — тоже: запросы в очереди
за миграцией получили бы 503 вместе с её отказом (решение 12).
- **[Новый код на старой схеме падает]** → только если миграцию - **[Новый код на старой схеме падает]** → только если миграцию
пропустить при движении вперёд. Скрипт пропускает её лишь по явному пропустить при движении вперёд. Скрипт пропускает её лишь по явному
`MIGRATE=0` (откат). Порядок «миграция → новые реплики» закреплён в `MIGRATE=0` (откат). Порядок «миграция → новые реплики» закреплён в
@@ -22,9 +22,12 @@
Ожидание блокировки таблицы миграцией SHALL быть ограничено сроком. Ожидание блокировки таблицы миграцией SHALL быть ограничено сроком.
Долгая транзакция приложения не должна заставить миграцию держать Долгая транзакция приложения не должна заставить миграцию держать
очередь за собой и остановить запись остальных реплик. По истечении очередь за собой и остановить запись остальных реплик. Срок SHALL быть
срока миграция SHALL завершаться ошибкой без изменения схемы, а её меньше срока запроса приложения к БД (`statement_timeout`): запросы,
повторный запуск SHALL проходить. вставшие в очередь за миграцией, дожидаются её отказа и выполняются, а
не завершаются ошибкой вместе с ним. По истечении срока миграция SHALL
завершаться ошибкой без изменения схемы, а её повторный запуск SHALL
проходить.
#### Scenario: Старый образ на новой схеме #### Scenario: Старый образ на новой схеме
@@ -44,9 +47,9 @@
- **WHEN** таблицу, которую меняет миграция, держит открытая - **WHEN** таблицу, которую меняет миграция, держит открытая
транзакция дольше срока ожидания блокировки транзакция дольше срока ожидания блокировки
- **THEN** миграция завершается ошибкой, схема не меняется, запись - **THEN** миграция завершается ошибкой, схема не меняется, запросы
других клиентов продолжается, а после окончания транзакции повторный других клиентов, ждавшие за миграцией, получают успешный ответ, а
запуск применяет миграцию после окончания транзакции повторный запуск применяет миграцию
### Requirement: Однократные миграции при замене реплик ### Requirement: Однократные миграции при замене реплик
+6
View File
@@ -189,6 +189,12 @@ Evidence снимается с закоммиченного кода: комми
а не `run --rm`), `bench.md` (отказ профиля без `UP`), дельта а не `run --rm`), `bench.md` (отказ профиля без `UP`), дельта
`load-balancing`, `REPORT.md`, скилл. Проверка: `make lint`, `dash -n`, `load-balancing`, `REPORT.md`, скилл. Проверка: `make lint`, `dash -n`,
`openspec validate rolling-update --strict`, коммит кода. `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 кода: - [ ] 7.2 Evidence на итоговом commit кода:
- `compatibility.md` — шаги A–G заново, с журналом остановки старых - `compatibility.md` — шаги A–G заново, с журналом остановки старых
реплик, `--dry-run` после отката и жизненным циклом стенда после реплик, `--dry-run` после отката и жизненным циклом стенда после