diff --git a/apps/docs/src/content/docs/getting-started/index.mdx b/apps/docs/src/content/docs/getting-started/index.mdx index e9ab286..fe63c09 100644 --- a/apps/docs/src/content/docs/getting-started/index.mdx +++ b/apps/docs/src/content/docs/getting-started/index.mdx @@ -28,7 +28,7 @@ chkit is a ClickHouse schema and migration toolkit for TypeScript projects. Pick Both paths need the same baseline: - Node.js 20+ or Bun 1.3.5+ -- A ClickHouse endpoint (`CLICKHOUSE_URL`, optionally `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`) +- A ClickHouse endpoint (`CLICKHOUSE_URL`, optionally `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`) — ClickHouse 24.x or newer (see [compatibility](/guides/clickhouse-compatibility/)) ## Where to next @@ -37,3 +37,4 @@ Once either path is working: - [CLI reference](/cli/overview/) — every command, flag, and expected output - [Configuration](/configuration/overview/) — wire up `clickhouse.config.ts` - [Schema DSL](/schema/dsl-reference/) — define tables, views, and materialized views +- [Troubleshooting](/guides/troubleshooting/) — fixes for common errors if a command fails diff --git a/apps/docs/src/content/docs/guides/clickhouse-compatibility.md b/apps/docs/src/content/docs/guides/clickhouse-compatibility.md new file mode 100644 index 0000000..0cae56b --- /dev/null +++ b/apps/docs/src/content/docs/guides/clickhouse-compatibility.md @@ -0,0 +1,30 @@ +--- +title: ClickHouse compatibility +description: Which ClickHouse versions and engines chkit supports, and which features are version-gated. +--- + +chkit is developed and tested against [ObsessionDB](/obsessiondb/overview/) (a managed ClickHouse running the `SharedMergeTree` engine) and recent open-source ClickHouse releases. + +## Supported versions + +chkit targets **ClickHouse 24.x and newer**. It uses standard SQL DDL and the HTTP interface, so it works against any reasonably recent ClickHouse — self-hosted, ClickHouse Cloud, or ObsessionDB. Older versions are not tested and may reject some generated DDL. + +The continuous test suite runs against ObsessionDB, so the `SharedMergeTree`/`Shared*` engine families and ObsessionDB-specific DDL are the most heavily exercised paths. Vanilla single-node ClickHouse is supported for standard `MergeTree`-family engines. + +## Version-gated features + +A few schema features depend on the ClickHouse version of your target: + +| Feature | Requirement | +|---------|-------------| +| [Refreshable materialized views](/schema/refreshable-views/) | Production-ready on **24.10+** (no flag). Experimental and flag-gated on 23.12–24.9. chkit targets 24.10+. | +| `set` data-skipping index | **ClickHouse 26+** requires the `set(0)` form rather than a bare `set`; chkit emits `set(maxRows)` accordingly. See the [DSL reference](/schema/dsl-reference/). | +| `uniqueKey` | Renders `UNIQUE KEY` DDL, which is supported on ObsessionDB / ClickHouse Cloud engines but rejected by vanilla `MergeTree`. | + +If you target a single-node open-source ClickHouse, prefer the standard `MergeTree` engine family and avoid the Cloud/Shared-only features above. + +## Related pages + +- [Configuration overview](/configuration/overview/) — connection and engine settings +- [Refreshable materialized views](/schema/refreshable-views/) — version requirements in detail +- [Troubleshooting](/guides/troubleshooting/) — common errors and fixes diff --git a/apps/docs/src/content/docs/guides/troubleshooting.md b/apps/docs/src/content/docs/guides/troubleshooting.md new file mode 100644 index 0000000..9546b3e --- /dev/null +++ b/apps/docs/src/content/docs/guides/troubleshooting.md @@ -0,0 +1,83 @@ +--- +title: Troubleshooting +description: Common chkit errors mapped to their causes and fixes — missing dependencies, connection and auth failures, rejected migrations, blocked destructive operations, and drift. +--- + +A reference for the errors you are most likely to hit when running chkit, what causes each, and how to fix it. Errors are grouped by the stage where they surface: loading the project, connecting to ClickHouse, and running migrations. + +## Quick reference + +| Error message contains | Cause | Fix | +|------------------------|-------|-----| +| `could not load its dependencies: cannot find "@chkit/core"` | Dependencies not installed yet | Run `bun install` (or `npm`/`pnpm install`) in the project | +| `Unknown file extension ".ts"` | Old chkit that could not load `.ts` configs under Node | Upgrade chkit — recent versions bundle a TypeScript loader | +| `Authentication failed for user "..."` | Wrong `CLICKHOUSE_USER` / `CLICKHOUSE_PASSWORD` | Check the credentials in your environment | +| `Could not connect to ClickHouse at ... (connection refused)` | Nothing listening at the URL | Confirm the server is running and `CLICKHOUSE_URL` host/port are correct | +| `Could not connect to ClickHouse at ... (host not found)` | Typo'd or unresolvable host | Check the host in `CLICKHOUSE_URL` | +| `Unknown data type family: ...` | A migration references an invalid ClickHouse type | Fix the column type in the schema/migration and regenerate | +| `Blocked destructive migration execution` (exit code 3) | A `risk=danger` operation in non-interactive mode | Review, then re-run with `--allow-destructive` | +| `Checksum mismatch detected on applied migrations` (exit code 1) | A migration file was edited after being applied | Restore the original file, or apply a new forward migration | +| `extra_object` entries in `drift` / `check` | Tables chkit does not manage exist in the database | Expected on shared databases; only fails CI if you opt into `check.failOnExtraObjects` | + +## Project loading + +### `could not load its dependencies: cannot find "@chkit/core"` + +The config (`clickhouse.config.ts`) and your schema files import `@chkit/core`, but it is not installed yet. This commonly happens when you run a command immediately after `chkit init`, before installing. + +Install the dependencies in the project directory: + +```sh +bun add -d chkit @chkit/core +``` + +### `Unknown file extension ".ts"` + +Older chkit versions could not load a TypeScript config under plain Node. Recent versions bundle a loader, so the fix is to upgrade: + +```sh +bun add -d chkit@latest +``` + +Under Bun this never occurred; under Node it now works the same way. + +## Connecting to ClickHouse + +### `Authentication failed for user "" at ` + +`CLICKHOUSE_USER` or `CLICKHOUSE_PASSWORD` is wrong. chkit collapses the raw ClickHouse auth blurb (Cloud reset URLs, server file paths) into this single line. Verify the credentials your environment exports. + +### `Could not connect to ClickHouse at ()` + +The endpoint is unreachable. The reason narrows it down: + +- **connection refused** — nothing is listening on that host/port. Confirm the server is up and the port is right. +- **host not found** — the host does not resolve. Check for a typo in `CLICKHOUSE_URL`. +- **connection timed out** / **host unreachable** — a network or firewall issue between you and the server. + +If `CLICKHOUSE_URL` is unset, chkit falls back to `http://localhost:8123`; the message says so when that is what happened. + +## Running migrations + +### `Unknown data type family: ` + +ClickHouse rejected a statement because a column type is not valid (for example a typo like `NotARealType`). Fix the type in the schema definition, regenerate the migration, and re-apply. + +### `Blocked destructive migration execution` (exit code 3) + +A migration contains a destructive operation (`DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `DETACH`, …) and you are running non-interactively without approval. After reviewing the plan, re-run with `--allow-destructive` (or set `safety.allowDestructive: true` in config). See [`chkit migrate`](/cli/migrate/#destructive-operation-safety). + +### `Checksum mismatch detected on applied migrations` (exit code 1) + +A migration file changed on disk after it was already applied — chkit verifies SHA-256 checksums before applying. Restore the original file content, or, if the change is intentional, write a new forward migration instead of editing history. + +### `extra_object` reported by `drift` / `check` + +On a shared or pre-existing database, every table chkit does not manage is reported as an `extra_object`. By default these are informational and do **not** fail `check`. They only flip the gate to failing if you opt in with `check.failOnExtraObjects: true`. See [`chkit drift`](/cli/drift/) and [`chkit check`](/cli/check/). + +## Related pages + +- [Configuration overview](/configuration/overview/) — config fields and environment variables +- [`chkit migrate`](/cli/migrate/) — applying migrations and destructive-operation safety +- [`chkit status`](/cli/status/) — inspecting migration state +- [CI/CD Integration](/guides/ci-cd/) — running chkit unattended diff --git a/packages/cli/README.md b/packages/cli/README.md index 68599fc..54bc75a 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -46,6 +46,11 @@ bunx chkit check All commands support `--json` for machine-readable output and `--config ` to specify a custom config file. +## Requirements + +- **Node 20+** or **Bun** — chkit loads your TypeScript config and schema files on both runtimes. +- **ClickHouse 24.x or newer** — chkit targets recent ClickHouse (self-hosted, ClickHouse Cloud, or ObsessionDB). Some schema features are version-gated; see [ClickHouse compatibility](https://chkit.obsessiondb.com/guides/clickhouse-compatibility/). + ## Plugins | Plugin | Description |