docs: README sections for dump-cluster/plan/web/sql2hcl, dump-sql reference, FAQ recipes#157
Merged
Conversation
…erence, FAQ recipes Closes the remaining items of #97 (the stale-CLAUDE.md and operational-policy items were fixed earlier; this is the rest): - README gains a dedicated section per previously-undocumented command: dump-cluster (fleet dumps, out-dir reset, non-fatal per-node failures), cross-role planning (globally-ordered operation list, node matching, provenance), the web UI (auto-reload, manifest mode), and sql2hcl (supported statements, schema-only boundary, diff -sql pairing). The intro command list gains locate and links examples/manifest, which no top-level doc referenced. - docs/README.hcl.md gains the missing dump-sql section (apply-ordered replayable DDL, beautified view CREATEs, round-trip role). - FAQ gains three operational recipes: capturing an existing cluster as HCL (introspect/dump-cluster with -allow-raw and -exclude), seeding a fresh ClickHouse (dump-sql vs diff-from-empty -sql), and applying a hand-written SQL migration via sql2hcl. Every recipe and claim was verified against the built binary, including web -manifest serving all six compositions of examples/manifest. Closes #97
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Finishes #97. The issue's CLAUDE.md-staleness and operational-policy items were fixed in earlier hygiene work; this lands everything its status comment still listed as open:
dump-cluster,plan(cross-role planning),web, andsql2hcl— a paragraph + runnable example each, linked to their full reference sections. The intro command list also gainslocate(it post-dates the list) and now linksexamples/manifest/, the flagship worked example that no top-level doc referenced.dump-sqlin the reference — it was absent fromdocs/README.hcl.mdentirely; the new section documents the apply ordering, the-- database:header, beautified view CREATEs, and its round-trip-fidelity role.-allow-raw+-excludeexplained), seeding a fresh ClickHouse (server-faithfuldump-sqlvs source-of-truthdiff-from-empty-sql), and applying a hand-written SQL migration with thesql2hcl→diff -sqlverification loop.Every recipe was executed against the built binary before being written down — including
web -manifestserving all six compositions ofexamples/manifest/and thesql2hclstdin pipeline.Docs-only; no code changes. (concept.md rewrite remains tracked separately, per the issue.)
Closes #97