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:
@@ -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`,
|
||||||
|
|||||||
@@ -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),
|
||||||
|
|||||||
@@ -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: Однократные миграции при замене реплик
|
||||||
|
|
||||||
|
|||||||
@@ -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` после отката и жизненным циклом стенда после
|
||||||
|
|||||||
Reference in New Issue
Block a user