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
- Nœud injoignable pendant l'exécution. Le cas le plus fréquent : un nœud en cours de restart (déploiement, mise à jour) au moment où la DDL est lancée. Il ne voit jamais l'entrée dans la queue tant qu'il n'est pas reconnecté à Keeper.
- Timeout de réplication. Un nœud vivant mais très en retard sur la réplication (souvent après une purge de partitions volumineuse) met un temps disproportionné à traiter la DDL, car elle est mise en file après les opérations de réplication déjà en cours.
Comment débloquer
- Identifier le nœud bloquant via
system.distributed_ddl_queue(statut vide ou absent pour ce host). - Vérifier s'il est simplement en retard ou réellement mort :
system.replicas.replica_is_activeetabsolute_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. - 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/ATTACHde la table si la divergence est trop grande). - Vérification post-incident : requêter
system.distributed_ddl_queuesur l'entrée concernée pour confirmer que tous les hosts affichentstatus = 'Finished', et comparer le schéma de la table (DESCRIBE TABLE) sur chaque nœud.
Comment l'éviter la prochaine fois
- Ne jamais lancer de DDL
ON CLUSTERpendant une fenêtre de déploiement ou de restart planifié on a ajouté un check de santé du cluster (tous les nœudsreplica_is_active = 1etabsolute_delayproche de zéro) avant toute migration de schéma dans notre pipeline CI. - Réduire
distributed_ddl_task_timeoutà une valeur raisonnable (on est passés à 300s) plutôt que de laisser une attente infinie qui masque le problème au lieu de le faire échouer proprement. - Surveiller
system.distributed_ddl_queueavec une alerte sur les entrées dont le statut reste incomplet plus de quelques minutes : ça permet de réagir avant que ça ne bloque un déploiement en aval.