document the per-node execution model; concept.md is stale (ON CLUSTER, chschema --auto-approve)
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 15
- Forks
- 2
- Avg merge
- 1h 1m
- Merged PRs (30d)
- 27
Description
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 CLUSTERwhere 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, andchschema --auto-approve, none of which exist inhclexp. - There is no documented path from
diff -sql/plan -format jsonoutput 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 jsonas 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 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).
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with docs/concept.md and the execution policy clarified in #81, then inspect the plan and diff command references. Review createTableSQL in internal/loader/hcl/sqlgen.go:627-630 and compare its ON CLUSTER behavior with ALTER generation. Done means the documentation describes per-node execution and the CREATE/ALTER behavior is made consistent.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- documentation, tooling
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100