Джоба миграций как подброшенная монетка: 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 неатомарно.
Ремонт
- Создать новую таблицу версий
ReplicatedReplacingMergeTreeON CLUSTERс теми же колонками. - Вставить head-ревизию один раз, без
ON CLUSTER. Дальше её разнесёт репликация. - Дождаться, пока строка появится на всех репликах. Сразу после вставки она была видна только на одной ноде. Это лаг асинхронной репликации в секунды, а не сломанный путь в Keeper.
EXCHANGE TABLESстарой и новой таблицON CLUSTER. Движок базы должен бытьAtomic.
Старая локальная таблица остаётся под именем новой. Это единственный откат: тот же EXCHANGE ещё раз. Дропать её до двух зелёных деплоев я бы не стал. После ремонта джоба миграций дважды подряд отработала зелёной.
Выводы
- Состояние миграций проверяйте на каждой реплике. Балансируемое подключение показывает случайную ноду и прячет расхождение.
- Зелёная джоба миграций не доказывает, что вы на head, пока таблица версий локальная.
- Таблицы, которые за вас создаёт библиотека, не мигрируются вашими миграциями. Исправление кода чинит только новые окружения. Старым нужен разовый ремонт.
- Добавьте preflight, который валит джобу до
upgrade head, если движок таблицы версий неReplicated*или реплики расходятся в версии.