PostHog / PostHog/chschema

document the per-node execution model; concept.md is stale (ON CLUSTER, chschema --auto-approve)

Open
#93 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
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 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).

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.