Symptom
The execution model is per-node: generated DDL is deliberately run on each node of a cluster individually, never with ON CLUSTER. But this model is documented nowhere, and the existing docs say the opposite or reference commands that don't exist:
- docs/concept.md:20 — "Cluster-aware execution. Generated DDL uses
ON CLUSTER where appropriate." (stale; the project moved away from ON CLUSTER because it caused too many problems)
- docs/concept.md:36-41 — workflow references
chschema validate ... live ClickHouse apply, chschema --dry-run, and chschema --auto-approve, none of which exist in hclexp.
- There is no documented path from
diff -sql / plan -format json output to actual per-node execution (who runs it, how nodes are enumerated, ordering guarantees).
Related inconsistency in code: createTableSQL still emits ON CLUSTER when a table has cluster set (internal/loader/hcl/sqlgen.go:627-630) while ALTERs never do — if per-node execution is the rule, the CREATE-side emission is the leftover to remove or gate.
Fix direction
- Rewrite docs/concept.md to describe the actual model: per-node execution, no ON CLUSTER,
plan/diff -format json as the hand-off to the executor.
- Document the end-to-end apply workflow (even if execution lives in external tooling).
- Decide the fate of the
ON CLUSTER emission in createTableSQL and make CREATE/ALTER consistent.
Found in the 2026-07-02 deep-dive audit (docs/plans/2026-07-02-deep-dive-improvement-areas.md, C1); reframed after maintainer clarified the per-node execution policy (see #81).
Symptom
The execution model is per-node: generated DDL is deliberately run on each node of a cluster individually, never with
ON CLUSTER. But this model is documented nowhere, and the existing docs say the opposite or reference commands that don't exist:ON CLUSTERwhere appropriate." (stale; the project moved away from ON CLUSTER because it caused too many problems)chschema validate ... live ClickHouse apply,chschema --dry-run, andchschema --auto-approve, none of which exist inhclexp.diff -sql/plan -format jsonoutput to actual per-node execution (who runs it, how nodes are enumerated, ordering guarantees).Related inconsistency in code:
createTableSQLstill emitsON CLUSTERwhen a table hasclusterset (internal/loader/hcl/sqlgen.go:627-630) while ALTERs never do — if per-node execution is the rule, the CREATE-side emission is the leftover to remove or gate.Fix direction
plan/diff -format jsonas the hand-off to the executor.ON CLUSTERemission in createTableSQL and make CREATE/ALTER consistent.Found in the 2026-07-02 deep-dive audit (docs/plans/2026-07-02-deep-dive-improvement-areas.md, C1); reframed after maintainer clarified the per-node execution policy (see #81).