# Design ## Context Мотивация — `proposal.md`, «Why». Требования — дельты в `specs/`. Стенд, LB и цепочка таймаутов — `.claude/rules/balancer.md`, миграции — `migrations.md`, стенд `bench/` — `bench.md`. Текущее состояние (commit `c50b721`, change `graceful-failover` в архиве): - **Стенд.** Сервис `api` × `API_REPLICAS` без имени контейнера. HAProxy находит реплики через DNS Docker: 8 слотов `server-template`, `init-state down`, `rise 2`, `inter 1s`, `fastinter 500ms`, `http-reuse never`, `timeout server 10s`. Сервис `migrate` — одноразовый контейнер на образе API, реплики ждут его завершения. - **Миграции.** Три ревизии, все только добавляют. Ревизия ключей идемпотентности `7652184b7016` уже писалась как expand. - **Остановка реплики** (`stop-one.sh`, профиль `failover`) — `docker stop` без вывода из LB. Под нагрузкой это даёт одиночный 502 в части фаз `stop`: гонка keep-alive при SIGTERM (`graceful-failover`, решения 3 и 10). - **Обновление кода.** Сейчас — только `make down` + `make run_docker`. `KNOWN_ISSUES.md` говорит, что `make run_docker` после пересборки не пересоздаёт работающие `api`. - **Хранилище образов Docker Desktop 29.8 — containerd** (`docker info`: `io.containerd.snapshotter.v1`). У тега три разных digest: индекс (`docker image inspect`), манифест платформы (метка `com.docker.compose.image` контейнера) и конфигурация (поле `.Image` контейнера; его показывает `docker ps` вместо имени тега). Разведка 2026-10-11: реплики рабочего стенда работают на текущем теге `mtusi-messenger:lab3`. Метка контейнера совпадает с манифестом платформы тега, хотя `docker ps` показывает `04f700d0d939`, а не имя. Разведка runtime API HAProxy (2026-10-11). Временный HAProxy того же образа и с копией `haproxy.cfg` плюс `stats socket ipv4@127.0.0.1:9999 level admin` стоял перед репликами рабочего стенда, команды шли через `bash` `/dev/tcp` изнутри контейнера: - `show stat` по CLI отдаёт адрес слота (`172.30.0.5:8080`); - `set server api/api-1 state drain` — слот `DRAIN`, 6 из 6 новых запросов ушли на вторую реплику; - `state maint` — `MAINT`, запросов на неё тоже нет; - `state ready` при живом адресе — слот сначала `DOWN 1/2`, затем `UP` через проверки. Возврат из ручного состояния проходит обычный `rise`, а не мгновенный `UP`. ## Goals / Non-Goals **Goals:** - Замена реплик на новый образ одной командой, без ошибок клиента под нагрузкой и без потери записей. Плановая остановка — с дренажём, поэтому без 502 гонки keep-alive. - Миграция при замене: одна, до новых реплик, совместима со старым кодом. Это проверено старым образом на новой схеме. - Предсказуемое поведение при сбое: `API_REPLICAS` готовых реплик и чистые слоты LB в любом исходе. - Профиль `rollout` воспроизводим одной командой и использует тот же скрипт, что рабочий стенд. **Non-Goals:** - Автоматический откат при сбое. Скрипт останавливается, а смешанные версии допустимы: миграция только расширяет схему. Откат — тот же скрипт с образом прежнего commit (решение 6). - Дренаж в `stop-one.sh` и в профиле `failover`. Hook имитирует отказ, а его срок возврата (< 10 с) не вмещает дренаж и graceful. - Contract-миграция (удаление, переименование). В этой поставке её нет, правило и порядок описаны. - Swarm и сторонние плагины (`docker rollout`). Выбор Compose + HAProxy подтверждён 2026-10-07 (`PLAN.md`); незакреплённых зависимостей не прибавляется (`balancer.md`). - Изменение HTTP API и контракта. ## Decisions ### 1. Порядок `scripts/rolling-update.sh` `#!/bin/sh`, `set -eu`, как `stop-one.sh`. Скрипт вызывает `docker compose` без `-p` и `-f`. Проект, файлы и файл подстановок берутся из окружения (`COMPOSE_PROJECT_NAME`, `COMPOSE_FILE`, `COMPOSE_ENV_FILES`) или из каталога репозитория. Поэтому один и тот же скрипт работает с рабочим стендом и со стендом `bench/` (решение 8). Разведка подтвердила: Compose 5.5.1 берёт `COMPOSE_ENV_FILES`, а `COMPOSE_PROJECT_NAME` перекрывает `name:` файла. 0. **Предусловия** (ничего не меняют): - работает ровно `API_REPLICAS` реплик (по умолчанию 2); - остановленных реплик сервиса нет. Иначе `up --scale` запустил бы остановленную старую вместо новой; - все реплики `UP` в LB; - `API_REPLICAS` + 1 ≤ числа слотов LB. Нарушение — код 2 и подсказка `make replicas`. 1. **Сборка.** По умолчанию `docker compose build api` из рабочего дерева. С `ROLLOUT_COMMIT=` образ собирается из файлов commit (решение 6) под тем же тегом сервиса (`docker compose config --images api`). 2. **Миграции один раз:** `docker compose run --rm --no-deps migrate` на только что собранном образе. Ошибка — код 1 до замены. Скрипт миграций не запускает при `ROLLOUT_MIGRATE=0` (откат, решение 6). Порядок «сборка → миграции», а не наоборот, как в `balancer.md`: новые ревизии лежат в новом образе. Правило исправляется. 3. **Новая реплика:** `docker compose up -d --no-deps --no-recreate --no-build --scale api=N+1 api`. Новая — та, ID которой не было до команды. 4. **Ожидание готовности** (решение 4). 5. **Вывод и удаление старой** (решение 3). 6. Шаги 3–5 — для каждой реплики, которая работала до шага 1. В конце — те же проверки, что в шаге 0: `N` работающих реплик, все `UP`, ни одной из прежнего списка. Каждый шаг пишет строку `HH:MM:SS rolling-update: …` с контейнером, слотом и адресом. Эти строки разбирает профиль `rollout`. Вывод сборки и миграции идёт следом, в нём нет секретов. ### 2. Дренаж — runtime API HAProxy на loopback В `global` `haproxy.cfg`: `stats socket ipv4@127.0.0.1:9999 level admin`. Скрипт отправляет команды так: `docker compose exec -T haproxy bash -c 'exec 3<>/dev/tcp/127.0.0.1/9999 …'`, как `make lb_stats` читает статистику. Слот реплики находится по её адресу в `show stat`: имя слота с именем контейнера не связано (`balancer.md`). Почему так: - Снаружи контейнера LB канал не виден: loopback другого контейнера недоступен, на хост порт не публикуется. Кто может выполнить `docker exec`, и так управляет всем стендом. - Приложение и цепочка таймаутов не меняются, поведение по SIGTERM (спек `graceful-shutdown`) остаётся прежним. Решение принимает оркестратор замены — он знает, что остановка плановая. - Действует мгновенно, а не через 1,5 с проверок. Альтернативы: - **Readiness 503 по SIGTERM.** Реплика после сигнала отвечает на `/health/ready` 503 и ещё ≥ 1,5 с принимает запросы, пока LB её не исключит. Минусы: - меняется спек `graceful-shutdown` («после SIGTERM новые соединения не принимаются»); - нужен свой обработчик сигнала поверх uvicorn; - остановка удлиняется до 1,5 + 8 с — впритык к `stop_grace_period` 10 с; - срок `stop-one.sh` (< 10 с) перестаёт выполняться. Отвергнуто. - **`stats admin` на странице `:8404`.** Порт открыт всей сети compose: любой контейнер стенда, включая реплику, мог бы вывести реплики из LB. Отвергнуто. - **Unix-сокет.** Нужен `socat` или `nc -U`, а в образе HAProxy их нет; bash с unix-сокетом не работает. Добавлять инструмент в закреплённый образ — свой образ LB. Отвергнуто. - **`set weight 0`** — то же, что `drain`, но состояние не видно в статистике явно. `drain` нагляднее (`make lb_stats` показывает `DRAIN`). ### 3. Состояния слота старой реплики 1. `set server api/<слот> state drain`. Новых запросов нет, начатые дорабатывают (разведка). 2. Ожидание `scur` = 0 (запросов в полёте) не дольше `ROLLOUT_DRAIN_TIMEOUT` = 12 с. Это больше `timeout server` 10 с: дольше запрос через LB не живёт. По сроку — предупреждение и остановка: оставшееся доработает graceful uvicorn (8 с). 3. `state maint` — проверки слота остановлены. Гибель процесса не пишет в журнал `DOWN` с ошибкой соединения, и слот не может вернуться в распределение по проверкам, пока процесс ещё отвечает. 4. `docker stop --timeout 10` (= `stop_grace_period`), `docker rm`. Простаивающие соединения LB с репликой uvicorn закрывает при SIGTERM. LB их больше не выбирает: слот выведен. Поэтому гонки keep-alive нет. 5. Ожидание, пока адрес уйдёт из слота: DNS `hold` 1 с, не дольше 10 с. Затем `state ready`. Почему `ready` нужен и почему после ухода адреса. Ручное состояние — свойство слота, а не реплики. Если слот останется в `drain` или `maint`, следующая реплика, которой DNS отдаст этот слот, не получит ни одного запроса. А `ready` при ещё живом адресе вернул бы проверки к мёртвому адресу: слот был бы `DOWN`, запросов бы не получил (разведка: `ready` → `DOWN 1/2` → проверки), но журнал LB шумел бы. Почему `drain`, а потом `maint`, а не сразу `maint`. Исход для новых запросов одинаков. Но `drain` — штатное «не давать новых, доработать текущие», а ожидание `scur` = 0 видно в статистике и журнале LB как отдельный шаг. `maint` нужен только на время гибели процесса. ### 4. Новая реплика готова — `UP` в статистике LB Ожидание, срок `ROLLOUT_READY_TIMEOUT` = 60 с: 1. Контейнер `healthy`, если у него есть healthcheck (рабочий стенд: healthcheck образа, `start_interval` 1 с), иначе `running`. На стенде `bench/` healthcheck выключен. 2. Слот с адресом новой реплики в состоянии `UP`. Только `healthy` мало. Слот получает адрес из DNS и начинает в `DOWN` (`init-state down`). В распределение он попадает после двух успешных проверок, то есть до 1,5 с после готовности (`downinter` + `fastinter`, `graceful-failover`). Вывести старую раньше — на время до 1,5 с остаться с N − 1 репликами. ### 5. Сбой на середине Автоматического отката нет (Non-Goals). Скрипт держит инвариант «`API_REPLICAS` готовых реплик и чистые слоты». Состояние текущей замены — в переменных, `trap` на `EXIT`, `INT`, `TERM`: | Где оборвалось | Что делает скрипт | Итог | |---|---|---| | предусловия, сборка, миграция | ничего не трогал | N старых, код 2 / 1 | | новая реплика не `UP` за срок, или прерывание до `UP` | `docker rm -f` новой; её слот уходит по DNS, ручного состояния у него не было | N реплик (k − 1 новых, остальные старые), код 1 | | новая `UP`, старая в дренаже или останавливается | довести шаг 3 решения 3: `maint`, `stop`, `rm`, `ready`. Повторный Ctrl+C на время уборки игнорируется | N реплик, код 1 или 130 | | уборка сама не удалась | печатает команды для ручного завершения (`docker rm …`, `set server … state ready`) | код 1 | Почему «довести», а не «вернуть» старую. Новая реплика уже готова и получает запросы. Вернуть старую — значит N + 1 реплик или ещё один вывод из LB. Довести шаг — не больше ~25 с: 12 с дренажа, 10 с остановки, 2 с DNS. - Смешанные версии после сбоя безопасны: схема совместима с обеими (решение 7, спек `db-migrations`). - Повторный запуск заменяет все работающие реплики. Уже новые заменяются на тот же образ: это лишняя, но безопасная работа. Образы скрипт не сравнивает, решение 9. - Слоты не переполняются: одновременно не больше N + 1 реплик, а N + 1 ≤ 8 проверяется в предусловиях. Проверка сбоя — `ROLLOUT_READY_TIMEOUT=1`: реплика стартует ~3 с и за 1 с готовой не станет. Плюс Ctrl+C во время дренажа и остановленная реплика перед запуском (`evidence/rollout/script-failures.md`). ### 6. Образ другого commit без изменения рабочего дерева `git archive --format=tar | docker build -t <тег> -`. Контекст — ровно файлы commit, `.dockerignore` commit применяется к tar-контексту. Рабочее дерево, индекс и HEAD не меняются, лишних каталогов нет. Где используется: - **Профиль `rollout`.** Старт на образе `Profile.rollout_from` (решение 8). - **Демонстрация на рабочем стенде.** Реплики на образе прежнего commit: `git archive c50b721 | docker build -t mtusi-messenger:lab3 -` и `docker compose up -d --no-build`. - **Откат кода скриптом.** `make rolling_update COMMIT= MIGRATE=0`. Миграции прежнего образа не знают новой ревизии, и `alembic upgrade head` упал бы на «Can't locate revision». Поэтому при откате миграции пропускаются явно. Схема остаётся новой, прежний код на ней работает (решение 7). Автоопределения нет: явный флаг надёжнее разбора текста ошибки alembic. Альтернативы: - `git worktree add` в scratchpad — тоже не трогает рабочее дерево, но оставляет метаданные в `.git/worktrees` и требует уборки; - `checkout` и `stash` запрещены (бриф) и сломали бы незакоммиченную работу; - `docker build` с git-URL контекста — нужен доступ к удалённому репозиторию и push. ### 7. Новая версия для демонстрации — `messages.instance_id` Колонка `instance_id text NULL` в `messages`: `X-Instance-Id` реплики, которая записала сообщение. Новый код пишет `settings.app.instance_id` при вставке (параметр `insert_message`, DTO не меняется). Старый код колонку не знает: - вставка перечисляет колонки, и в новой колонке остаётся NULL; - чтение выбирает `MESSAGE_COLUMNS`, то есть те же колонки. Контракт и ответы API не меняются: колонка наружу не отдаётся. Почему так: - Новый код **зависит** от новой схемы: без миграции его вставка упала бы. Значит, порядок «миграция до новых реплик» проверяется по-настоящему. Старый код **терпит** новую схему. Это и есть expand/contract в миниатюре. - По данным видно, какая версия записала сообщение (NULL — прежняя). Это доказательство замены в БД, а не только по заголовкам. - Ревизия — `op.add_column(..., nullable=True)`. В PostgreSQL ≥ 11 колонка без значения по умолчанию добавляется изменением каталога, без перезаписи таблицы. Блокировка `ACCESS EXCLUSIVE` берётся на миллисекунды, но в очереди за ней ждут все новые запросы к `messages`. Поэтому первой строкой ревизии идёт `SET LOCAL lock_timeout = '5s'`: - чужая долгая транзакция не заставит миграцию держать очередь; - по сроку миграция падает, схема не меняется, и замена не начинается (спек `db-migrations`); - повторный запуск проходит. - `downgrade` удаляет колонку. Это шаг contract, допустимый только после того, как не осталось нового кода. Альтернативы: - **Индекс `CONCURRENTLY`.** Код от схемы не зависит, демонстрация совместимости пустая. Кроме того, `CONCURRENTLY` не выполняется внутри транзакции alembic. - **Переименование колонки.** Это не expand: старый код ломается. Годится только как пример того, чего нельзя. - **Только правка кода без схемы.** Совместимость миграций не проверяется вовсе. Цена: +~13 байт на строку `messages` (12 символов ID и заголовок varlena). Трек 1 снимает базовый замер после change, поэтому меток для сравнения «до» нет. ### 8. Профиль `rollout` стенда `bench/` | Поле | `rollout` | `rollout_quick` | |---|---|---| | реплик, лимиты | 2; как рабочий стенд (как `failover`) | те же | | интенсивность | 100 записей с ключом + 100 чтений в секунду | та же | | `rollout_from` | `c50b721` — последний commit до change | тот же | | окна: до замены / бюджет замены / после | 15 / 90 / 15 с | 5 / 60 / 8 с | | порог доли успешных | 99 % | 99 % | | читаемый чат | 1 000 сообщений | тот же | - **Старт.** `run.py` собирает образ текущего checkout (паспорт, как всегда) и образ `rollout_from` через `git archive` под тегом `mtusi-messenger:bench-from`. Затем `docker tag` на `mtusi-messenger:bench`, `Stand.start()`. Миграции прежнего образа дают его последнюю ревизию, реплики стартуют прежнего образа. Подготовка — как у `failover`: фикстура, читаемый чат, курсоры (общий хелпер). - **Нагрузка** — тот же `k6/failover.js`, `DURATION` = до + бюджет + после, `PHASE` 1. Через «до» секунд `run.py` запускает `scripts/rolling-update.sh`. Окружение — `Stand.env` (пароли, `BENCH_*`), плюс `COMPOSE_PROJECT_NAME=mtusi-bench`, `COMPOSE_FILE` (оба файла), `COMPOSE_ENV_FILES=bench/bench.env`, `API_REPLICAS`. `docker compose build api` пересобирает текущий checkout под тег `mtusi-messenger:bench`, слои из кэша. Правило `bench.md` «`-p`, оба `-f`, `--env-file`» выполняется переменными окружения. - **Время — часы ВМ.** Начало замены `t0` — событие `create` контейнера миграции. События — поток `docker events` с меткой проекта, запущенный до нагрузки, а не `docker events --since` после прогона. Демон хранит только последние 256 событий, а каждый `docker exec` (скрипт опрашивает LB, оркестратор — статистику) даёт три. В первой самопроверке событий миграции и старых реплик к концу прогона уже не было. Шаги каждой реплики берутся из трёх источников: - события Docker: `create`/`start` новой, `kill` с сигналом 15, `die`, `destroy` старой; - журнал LB: `UP` слота новой, `drain`/`maint` слота старой; - строки скрипта: какие слот и адрес у какой реплики. Сборка до `t0` измеряется по строкам скрипта (секунды). - **Окна ошибок.** «До» — запросы, завершённые до `t0`. «Замена» — отправленные от `t0` до `destroy` последней старой. «После» — всё остальное. - **Шкала.** Посекундно от `t0`, по образцу `failover`. Добавлены `old_ok` и `new_ok`: успешные ответы с `X-Instance-Id` прежних и новых контейнеров. Новые столбцы — в конце (`bench.md`). - **Повтор и сверка** — `k6/retry.js` и `psql` стенда, как в `failover`. Плюс: - ревизия `alembic_version` до и после — измерение, а не изменение схемы; - контейнеры и `.Image` до и после; - тег образа после замены. - **Результаты** — `evidence/rollout/<метка>/`: - `meta.json` (паспорт и раздел `rollout`); - `rollout.csv` (строка прогона); - `replicas.csv` (строка на заменённую реплику); - `timeline.csv`, `summary.md`; - `raw/rollout-k6.json`, `raw/rollout-lb.log`, `raw/rollout-script.log` (только строки `rolling-update:`). Пробные `quick-rollout-*` — в `.gitignore`. - **Отказ команды** — по списку спека `load-benchmark`. Ошибки клиента — пометка (`errors`), а не отказ. - **Код:** - `bench/rollout.py` — чистые функции разбора и сводки на stdlib поверх парсеров `failover.py`; - `run.py` — профили, `--from ` для отладки (в `overrides`), оркестрация. Тег `bench-from` снимается при уборке. ### 9. `make run_docker` и пересборка Гипотеза: пункт `KNOWN_ISSUES.md` — ошибка диагностики. В хранилище containerd `docker ps` показывает у реплик digest конфигурации, а не имя тега, и это выглядит как «старый образ» (Context). Compose сравнивает метку `com.docker.compose.image` с манифестом платформы тега и должен пересоздавать реплики после пересборки. Проверка в apply. Реплики работают на образе прежнего commit, затем: 1. `docker compose build api` (новый образ); 2. `docker compose --dry-run up -d`; 3. метки контейнеров против `docker image inspect --platform`. Исход: - **Compose пересоздаёт** (`Recreate`). Пункт закрывается в `KNOWN_ISSUES.md` с объяснением. В комментарии `run_docker` и в `REPORT.md`: `run_docker` пересоздаёт все реплики разом, с простоем; без простоя — `make rolling_update`. - **Не пересоздаёт.** `run_docker` получает явное пересоздание `api` после сборки, пункт закрывается исправлением. Скрипт замены от этого не зависит: он определяет новую реплику по ID, а не по образу. ### 10. Evidence и отчёт | Файл | Что показывает | |---|---| | `evidence/rollout/<метка>/` | полный профиль `rollout` с commit change: шкала, шаги по репликам, контейнеры и образы до и после, сверка; хост по брифу | | `evidence/rollout/compatibility.md` | рабочий стенд: реплики прежнего образа → новая миграция → `make test` и `make student_test` на прежнем образе и новой схеме → `make rolling_update` под `tests/load.py` → откат `COMMIT=c50b721 MIGRATE=0` под нагрузкой → снова вперёд; `docker compose ps` и образы до и после, `instance_id` сообщений по версиям, ревизия схемы; проверка `--dry-run` из решения 9 | | `evidence/rollout/script-failures.md` | предусловия (остановленная реплика, не то число реплик), новая реплика не готова (`ROLLOUT_READY_TIMEOUT=1`), Ctrl+C во время дренажа, миграция не получила блокировку (`lock_timeout`), канал управления LB недоступен из сети | | `evidence/tests/rolling-update-checks.md` | регрессия на commit кода: `make lint`, `check`, `test`, `student_test`, `test_isolated`, `failure_checks`, `test-persistence`, `test-failover` (`stop` и `kill`), `bench_quick`, `bench_failover_quick`, `bench_rollout_quick` | `REPORT.md`: - строки таблицы доказательств уровня «4» — замена под нагрузкой, миграции однократно и совместимы, вместо строки TODO; - процедура замены и состояния слота; - раздел профиля `rollout` в «Эксперименты и отказы»; - ограничения: нет автоотката, contract отдельной поставкой, одиночный 502 остаётся только у незапланированного `docker stop`; - ответ на вопрос защиты о `depends_on` и healthcheck дополняется ожиданием `UP` в LB при замене; - раздел «Обновление без простоя и миграции» в ответах на вопросы защиты. ## Risks / Trade-offs - **[Канал управления LB — admin-уровень]** → слушает только `127.0.0.1` внутри контейнера LB. Проверка — попытка подключиться к порту 9999 LB из другого контейнера сети (`script-failures.md`). Доступ через `docker exec` равен доступу к Docker, то есть ко всему стенду. - **[`lock_timeout` 5 с может не хватить под тяжёлой записью]** → миграция падает без изменений, замена не начинается, повтор проходит. Это лучше, чем очередь всех записей за миграцией. Без нагрузки блокировка берётся за миллисекунды. - **[Новый код на старой схеме падает]** → только если миграцию пропустить при движении вперёд. Скрипт пропускает её лишь по явному `MIGRATE=0` (откат). Порядок «миграция → новые реплики» закреплён в скрипте и спеке. - **[`git archive` берёт только закоммиченное]** → это и нужно: «прежняя версия» — commit, а не рабочее дерево. Commit записывается в паспорт. - **[Профиль `rollout` собирает образ под нагрузкой]** → сборка из кэша слоёв — секунды CPU ВМ, видны в шкале до `t0`. Так и при реальной замене на том же хосте; длительность — в результатах. - **[`docker compose exec` на каждую команду LB]** → ~0,1–0,2 с на вызов, опрос каждые 0,25–0,5 с. Замена двух реплик — десятки вызовов, секунды. - **[Повторный запуск после сбоя заменяет и уже новые реплики]** → это лишняя работа, но безопасная и проще, чем сравнивать digest в хранилище containerd (Context). - **[DNS отдал адрес удалённой реплики новой раньше, чем слот вернулся в `ready`]** → IPAM Docker переиспользует адрес сразу. В apply новая реплика второго шага получила адрес и слот только что удалённой старой. Поэтому `ready` выставляется после ухода адреса и до следующего `--scale`. Слот новой реплики проверяется в шаге ожидания по её адресу: если он застрял в ручном состоянии, замена падает по сроку с понятной причиной, а не тихо. - **[SIGTERM новой реплике во время её старта теряется]** → найдено в apply. Процесс с PID 1 без обработчика сигнала SIGTERM игнорирует, а обработчики uvicorn ставит только на старте сервера. Поэтому `docker stop` неготовой реплики ждал все 10 с. За это время реплика успела стать `UP` и получала запросы, пока её не убил SIGKILL. Убирает неготовую новую реплику функция `remove_new`: - слот уже есть — сначала `maint`; - реплика не `UP` — `docker rm -f` без SIGTERM; - реплика `UP` — graceful stop. Сама потеря сигнала до старта — в `KNOWN_ISSUES.md`. - **[Один хост]** → профиль показывает поведение замены и порядок величин, а не распределение. Генератор, LB, реплики, сборка и PostgreSQL делят ВМ Docker. ## Migration Plan 1. Код, ревизия, скрипт и конфиг LB коммитятся. Рабочий стенд получает их одной командой `make rolling_update`: новая ревизия применяется, реплики заменяются. `haproxy.cfg` с runtime API подхватывается пересозданием LB (`docker compose up -d haproxy`). Это короткий перерыв точки входа, а не реплик. Делается один раз, до первой замены: без канала управления скрипт останавливается в предусловиях. 2. Откат кода — `make rolling_update COMMIT=<прежний> MIGRATE=0`. Схема остаётся новой, прежний код на ней работает. Колонку удаляет только отдельная contract-миграция, когда прежнего кода точно нет.