Data engineer, Paris · Airflow · ClickHouse · dbt · Kubernetes · Snowflake · Databricks · Spark · AWS · GCPData engineer, Paris · Airflow · ClickHouse · dbt · Kubernetes · Snowflake · Databricks · Spark · AWS · GCP
CLICKHOUSE2026-08-12

Debugger les DDL bloquantes ClickHouse avec ON CLUSTER

Tahirintsoa Mamitiana·3 min de lecture

Le symptôme

Un run de migration ajoutait une colonne sur une table répliquée à trois nœuds, via ALTER TABLE ... ON CLUSTER. La requête ne s'est jamais terminée côté client : timeout après plusieurs minutes. En regardant les métriques, un des trois nœuds affichait un retard de réplication qui grossissait, et les autres attendaient silencieusement.

Comment fonctionne ON CLUSTER

Quand on exécute une DDL avec ON CLUSTER <nom_cluster>, ClickHouse ne l'exécute pas directement : il pousse une entrée dans une file de tâches distribuée, stockée dans ClickHouse Keeper (ou ZooKeeper selon la configuration), sous le chemin /clickhouse/task_queue/ddl (le chemin exact dépend de la config distributed_ddl.path). Chaque nœud du cluster surveille cette file et exécute la DDL localement dès qu'il la voit, puis marque son statut (finished ou error) dans un sous-nœud dédié à ce host.

Le nœud qui a initié la requête attend que tous les hosts du cluster confirment l'exécution, dans la limite de distributed_ddl_task_timeout (180 secondes par défaut avant ClickHouse 22.x, -1 - attente infinie - dans certaines configurations plus anciennes qu'on avait héritées). Si un seul nœud ne répond jamais, toute la requête reste bloquée jusqu'au timeout, voire indéfiniment.

Où regarder pour diagnostiquer

Trois emplacements à vérifier dans l'ordre :

-- 1. État de la tâche DDL elle-même : quels hosts ont répondu, lesquels pas
SELECT host, port, status, exception_code
FROM system.distributed_ddl_queue
WHERE entry = 'query-0000012345'
ORDER BY host;
-- 2. Le nœud "manquant" a-t-il du retard de réplication ?
SELECT database, table, replica_is_active, absolute_delay
FROM system.replicas
WHERE absolute_delay > 60
ORDER BY absolute_delay DESC;

Et en dernier recours, les logs de ClickHouse Keeper (/var/log/clickhouse-keeper/clickhouse-keeper.log sur nos hosts) pour vérifier qu'il n'y a pas de souci de quorum ou de connectivité entre les nœuds : un Keeper qui perd le quorum bloque silencieusement toute la mécanique de coordination.

Cas rencontrés

Comment débloquer

  1. Identifier le nœud bloquant via system.distributed_ddl_queue (statut vide ou absent pour ce host).
  2. Vérifier s'il est simplement en retard ou réellement mort : system.replicas.replica_is_active et absolute_delay. Si le nœud répond aux requêtes normales, patienter généralement suffit la tâche finira par se traiter. S'il est down, il faut le relancer.
  3. Si le nœud ne reviendra pas à temps (panne prolongée, remplacement d'instance), on peut supprimer manuellement l'entrée de tâche correspondant à ce host dans Keeper pour débloquer les autres nœuds - opération à ne faire qu'en dernier recours, et seulement après avoir confirmé que le schéma sur les nœuds restants est cohérent, car ça laisse le nœud fautif désynchronisé jusqu'à son retour (il faudra rejouer la DDL manuellement dessus, ou le laisser se resynchroniser via un DETACH/ATTACH de la table si la divergence est trop grande).
  4. Vérification post-incident : requêter system.distributed_ddl_queue sur l'entrée concernée pour confirmer que tous les hosts affichent status = 'Finished', et comparer le schéma de la table (DESCRIBE TABLE) sur chaque nœud.

Comment l'éviter la prochaine fois