docs: add first-schema tutorial, reorganize sidebar, and fix reference accuracy#164
Conversation
Walk from an empty folder to a live, version-controlled table using the events table that `chkit init` scaffolds: claim a free ObsessionDB instance, generate + migrate, verify, insert/query rows, then add a column and ship it. Register a new Tutorials section in the docs sidebar. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Move CLI Reference to the last sidebar group. Order the Plugins section explicitly (Overview, Codegen, Pull, Backfill) and flag the backfill plugin as Alpha with a sidebar badge and an in-page caution. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…curacy - Rewrite cli/init.md to match the real command: --connect/--email/--code/ --org-name/--yes flags, dependency bootstrap, and the interactive ObsessionDB connect step. - obsessiondb/overview: chkit backfill -> chkit plugin backfill (no top-level shortcut exists). - getting-started/add-to-existing-project: note that init also offers to connect (incl. claiming a free instance); cross-link the tutorial. - schema/dsl-reference: document SQL-standard type aliases (BIGINT/TEXT/etc.) and standardize authored engine examples on 'MergeTree'.
- Footer: drop placeholder Discord link, point X link at x.com/obsessiondb. - custom.css: re-assert flex layout for the GH-stars badge inside the mobile burger menu so .sidebar-content's anchor rule doesn't collapse it.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 836e3a5658
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| #### SQL-standard aliases | ||
|
|
||
| The type string is passed through to ClickHouse verbatim — chkit does not rewrite it. ClickHouse accepts standard SQL type aliases and normalizes them to its native types when the table is created, so these are all valid `type` values: |
There was a problem hiding this comment.
This section now recommends aliases such as BIGINT/TEXT as valid schema type values, but chkit’s drift/check comparison fingerprints column types literally (compareTableShape → normalizeColumnShape) while live introspection reads the native type that ClickHouse reports after creation. A table declared with BIGINT will therefore be created successfully but then show a changed_column drift against live Int64, so users following this guidance can end up with a perpetually failing chkit check unless they use native types or chkit adds alias normalization.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Good catch — confirmed. normalizeColumnShape fingerprints the type literally (type=BIGINT) while live introspection reports Int64, so aliases produce a permanent changed_column drift. Reframed the section in cedaa81 to warn that aliases fail chkit check --strict and to recommend native ClickHouse types.
| **Claim a free ObsessionDB instance non-interactively:** | ||
|
|
||
| Docs: https://chkit.obsessiondb.com/getting-started/add-to-existing-project/ | ||
| ```sh | ||
| chkit init --connect claim --email you@example.com |
There was a problem hiding this comment.
In a non-TTY run, runSignup returns immediately after sending the email code when no --code is supplied, so this command only sends the OTP and exits without claiming or selecting an ObsessionDB service. Users copying the “Claim ... non-interactively” example will be left with no .chkit/obsessiondb.json and later commands won’t target the promised instance; the example needs the second --code invocation (or should be labeled as step 1).
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Correct — on a no-TTY run runSignup only sends the OTP and returns before runClaim, so nothing is claimed. Fixed in cedaa81: relabeled the example as 'preselect the claim path (still prompts for the emailed code)' and linked the scripted two-step OTP flow on the ObsessionDB page.
| The command is idempotent — running it again on an existing project does nothing. | ||
| Claiming or logging in registers the `@chkit/plugin-obsessiondb` plugin in your config and writes the selected service to `.chkit/obsessiondb.json`. See [Getting Started with ObsessionDB](/obsessiondb/getting-started/) for each path in detail, including the non-interactive and agent-friendly (`--json`) variants. | ||
|
|
||
| Pass `--yes` to skip this step and just write files. In a non-interactive environment (no TTY) without connect flags, `init` writes files, prints the runnable commands for each connect path, and exits. When an explicit connect path is requested but cannot complete — for example `--connect claim` with no email, or a wrong code — `init` exits non-zero so scripts can detect the failure. |
There was a problem hiding this comment.
The implementation in cmdInit does not call onboarding for !interactive && !explicit, so plain chkit init in CI prints only the static next steps after scaffolding; the ObsessionDB runbook is printed only by runOnboarding, which this path skips. This sentence will send non-interactive users looking for connect-path commands that are never emitted unless they pass an explicit connect flag.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Right — cmdInit skips onboarding for !interactive && !explicit, so plain chkit init in CI prints only the static next-steps; the connect runbook is never reached. Corrected the sentence in cedaa81.
- dsl-reference: warn that SQL type aliases (BIGINT/TEXT/etc.) cause permanent changed_column drift since chkit compares types literally; recommend native ClickHouse types. - cli/init: fix no-TTY behavior description (plain init skips onboarding and prints static next steps); correct the claim example to note it still prompts for the emailed code and link the scripted two-step OTP flow.
1 participant
Summary
cli/init.mdto match the real command —--connect/--email/--code/--org-name/--yesflags, dependency bootstrap, and the interactive ObsessionDB connect step.chkit backfill→chkit plugin backfill(no top-level shortcut exists); document SQL-standard type aliases (BIGINT/TEXT/…) in the schema DSL reference; standardize authored engine examples on'MergeTree'; cross-link the tutorial from the "add to existing project" guide.Test plan
cd apps/docs && bun run buildsucceeds (31 pages, no errors)#sql-standard-aliases)🤖 Generated with Claude Code