← Все статьи

Джоба миграций как подброшенная монетка: ClickHouse хранил версию схемы на каждой реплике отдельно

SELECT из alembic_version отдавал разные ревизии в зависимости от того, какая нода ответила. Таблица версий никогда не реплицировалась, а дата её создания предсказала, какие окружения задеты.

Баг-репорт был коротким: SELECT * FROM alembic_version на staging-окружении отдаёт разные ревизии в зависимости от того, какая нода ClickHouse ответила. Автора беспокоило, что однажды джоба миграций сядет на отставшую ноду и переиграет уже применённые миграции.

Сама джоба вела себя как монетка. Одни прогоны были зелёными. Другие падали с Can't locate revision identified by '<rev>'.

Почему таблица версий может жить на каждой ноде своя

В ClickHouse таблица реплицируется, только если у неё движок Replicated* и создана она с ON CLUSTER. Alembic создаёт свою таблицу версий не миграцией. В этом стеке её патчит clickhouse-sqlalchemy, и патч выбирает движок:

if 'cluster' in kwargs:
    version.engine = engines.ReplicatedReplacingMergeTree(...)   # ON CLUSTER, реплицируется
else:
    version.engine = engines.ReplacingMergeTree(...)             # локальная, своя на каждой ноде

Аргумент cluster в окружение миграций добавили в какой-то момент. Свою таблицу версий alembic не мигрирует никогда, поэтому патч влияет только на CREATE. Каждая база, созданная до этого изменения, так и держала отдельную локальную таблицу версий на каждой реплике и сама себя починить не могла.

Мигратор подключается через обычный Kubernetes Service, который балансирует по репликам. Каждый прогон садится на случайную ноду, читает её версию, накатывает миграции от неё и пишет результат туда же. Ноды расходятся, и каждый прогон делает только хуже.

Дата создания предсказала движок

Одна деталь сильно ускорила диагноз. Alembic обновляет версию через ALTER TABLE ... UPDATE version_num. Колонка dt — версионная колонка ReplacingMergeTree, и эта мутация её не трогает. Значит, dt в строке версии — это дата первого INSERT, то есть дата создания таблицы.

На четырёх окружениях правило сработало без исключений. Одна база, созданная до патча, — локальный движок и разные версии. Три, созданные после, — реплицируемый движок и одна версия. Больным оказалось только самое старое окружение.

Читать все реплики, а не Service

Запрос через Service показывает одну случайную ноду, и весь баг прятался именно за этим. Диагностика должна идти через clusterAllReplicas:

SELECT hostName() AS host, engine
FROM clusterAllReplicas('default', system.tables)
WHERE database = '<db>' AND name = 'alembic_version';

SELECT hostName() AS host, version_num, dt
FROM clusterAllReplicas('default', <db>.alembic_version);

Прежде чем трогать версию, я проверил, что реальная схема на всех репликах совпадает, — по отпечатку system.columns:

SELECT hostName() AS host, count() AS cols,
       sum(cityHash64(table, name, type)) AS fingerprint
FROM clusterAllReplicas('default', system.columns)
WHERE database = '<db>' GROUP BY host;

1 147 колонок и одинаковый хеш на каждой ноде. Схема была идентичной. Врала только строка версии.

Был ещё один сюрприз. На отставшей реплике лежала ревизия, которой нигде не было в истории репозитория. Alembic не может построить путь от неизвестной ревизии, поэтому падал до выполнения какого-либо DDL. Это был удачный случай. С валидной старой ревизией alembic молча переиграл бы миграции, а некоторые из них пересоздают materialized view неатомарно.

Ремонт

  1. Создать новую таблицу версий ReplicatedReplacingMergeTree ON CLUSTER с теми же колонками.
  2. Вставить head-ревизию один раз, без ON CLUSTER. Дальше её разнесёт репликация.
  3. Дождаться, пока строка появится на всех репликах. Сразу после вставки она была видна только на одной ноде. Это лаг асинхронной репликации в секунды, а не сломанный путь в Keeper.
  4. EXCHANGE TABLES старой и новой таблиц ON CLUSTER. Движок базы должен быть Atomic.

Старая локальная таблица остаётся под именем новой. Это единственный откат: тот же EXCHANGE ещё раз. Дропать её до двух зелёных деплоев я бы не стал. После ремонта джоба миграций дважды подряд отработала зелёной.

Выводы

  • Состояние миграций проверяйте на каждой реплике. Балансируемое подключение показывает случайную ноду и прячет расхождение.
  • Зелёная джоба миграций не доказывает, что вы на head, пока таблица версий локальная.
  • Таблицы, которые за вас создаёт библиотека, не мигрируются вашими миграциями. Исправление кода чинит только новые окружения. Старым нужен разовый ремонт.
  • Добавьте preflight, который валит джобу до upgrade head, если движок таблицы версий не Replicated* или реплики расходятся в версии.