From aafe8b72d73f2d26741ea56d8f30cba163d6f507 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 28 Sep 2026 08:32:12 +0000 Subject: [PATCH] Add the hello example as the default starter. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A two-table schema newcomers can migrate without the ClickBench load. The examples manifest default is hello; clickbench stays selectable. Co-authored-by: Marc Höffl --- README.md | 2 + apps/docs/src/content/docs/ai-agents.md | 4 +- .../content/docs/getting-started/index.mdx | 4 +- .../docs/getting-started/with-an-example.mdx | 42 +++++++++-- examples/hello/README.md | 73 +++++++++++++++++++ examples/hello/chkit/meta/snapshot.json | 64 ++++++++++++++++ .../20260928082853_create_hello_schema.sql | 31 ++++++++ examples/hello/clickhouse.config.ts | 16 ++++ examples/hello/package.json | 20 +++++ examples/hello/src/db/schema/hello.ts | 30 ++++++++ examples/manifest.json | 6 +- 11 files changed, 281 insertions(+), 11 deletions(-) create mode 100644 examples/hello/README.md create mode 100644 examples/hello/chkit/meta/snapshot.json create mode 100644 examples/hello/chkit/migrations/20260928082853_create_hello_schema.sql create mode 100644 examples/hello/clickhouse.config.ts create mode 100644 examples/hello/package.json create mode 100644 examples/hello/src/db/schema/hello.ts diff --git a/README.md b/README.md index 0d478093..bd6be023 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ chkit is an open-source CLI for ClickHouse. Review migration SQL before applying [Get started](https://chkit.obsessiondb.com/getting-started/) · [Build a data source](https://chkit.obsessiondb.com/api-sync/quickstart/) · [Documentation](https://chkit.obsessiondb.com) +New to chkit? Scaffold the small [hello example](examples/hello) with `bun create chkit@latest my-app --example hello`, or clone that folder and follow its README. The heavier ClickBench load stays at [`examples/clickbench`](examples/clickbench). + > **Beta:** the public API is still evolving. Keep the CLI, core, and plugins on matching versions. ## Why chkit diff --git a/apps/docs/src/content/docs/ai-agents.md b/apps/docs/src/content/docs/ai-agents.md index 4317a93f..3b1f9b18 100644 --- a/apps/docs/src/content/docs/ai-agents.md +++ b/apps/docs/src/content/docs/ai-agents.md @@ -73,9 +73,11 @@ It guides decisions about raw versus shaped data, transformations, pagination, i `create-chkit` downloads a curated example and wires it to the user's package manager. Pass a target directory and an example to skip the prompts: ```sh -bun create chkit@latest my-chkit-app --example clickbench +bun create chkit@latest my-chkit-app --example hello ``` +`hello` is the small default schema (two tables, one migration). Pass `--example clickbench` for the full ClickBench dataset load. + It then runs the same connect flow as `chkit init` (Step 4). Drive it non-interactively with `--connect ` (and `--email` for the claim path), or `--skip-onboarding` to scaffold only. ### 3b. Existing project: `chkit init` diff --git a/apps/docs/src/content/docs/getting-started/index.mdx b/apps/docs/src/content/docs/getting-started/index.mdx index 87e2481c..e5a8bef2 100644 --- a/apps/docs/src/content/docs/getting-started/index.mdx +++ b/apps/docs/src/content/docs/getting-started/index.mdx @@ -29,7 +29,7 @@ For manual setup, start with an example or add chkit to an existing project. -Pass a project directory and pick an example explicitly: +Pass a project directory and select `hello` explicitly: + + + +The scaffold then asks how to connect: + +``` +Claim a free ObsessionDB dev instance email code, ready in seconds +I already have an ObsessionDB account log in and pick a service +I already have a ClickHouse instance connect with env vars +Configure later +``` + +Choose **Claim a free ObsessionDB dev instance** and enter the emailed code. chkit creates a personal organization, provisions a free instance, and selects it. See [Getting Started with ObsessionDB](/obsessiondb/getting-started/) for the other paths, including the non-interactive signup commands. + +For the full ClickBench schema and public dataset load, pass `--example clickbench` instead: @@ -42,23 +57,36 @@ Pass a project directory and pick an example explicitly: | Name | Description | | --- | --- | +| `hello` | Two small tables and one migration. Default. Claim a free ObsessionDB instance or use local ClickHouse. | | `clickbench` | Full ClickBench schema and dataset load against ObsessionDB or ClickHouse. | -More examples will land in the [`examples/` directory](https://github.com/obsessiondb/chkit/tree/main/examples) over time. +The list and default live in [`examples/manifest.json`](https://github.com/obsessiondb/chkit/blob/main/examples/manifest.json). The same `hello` project can be cloned from [`examples/hello`](https://github.com/obsessiondb/chkit/tree/main/examples/hello) without the scaffolder. ## Run your first migration -Once the scaffold completes: +Once the scaffold completes and a database is connected: + +```sh +cd my-chkit-app +bun run migrate +bunx chkit query "SELECT name FROM system.tables WHERE database = 'default' AND name IN ('users', 'events') ORDER BY name" +``` + +Both tables come back, `events` then `users`. They are empty. + +For a local ClickHouse instead of the claimed instance, set the endpoint before migrating: ```sh cd my-chkit-app export CLICKHOUSE_URL=http://localhost:8123 # export CLICKHOUSE_PASSWORD=... bun run migrate +bunx chkit query "SELECT name FROM system.tables WHERE database = 'default' AND name IN ('users', 'events') ORDER BY name" ``` ## Where to next +- [Tutorial: your first schema](/tutorials/first-schema/) — the same loop from `chkit init`, including an insert and a schema change - [CLI reference](/cli/overview/) — every command and flag - [Configuration](/configuration/overview/) — wire up `clickhouse.config.ts` - [Add chkit to an existing project](/getting-started/add-to-existing-project/) — the other path diff --git a/examples/hello/README.md b/examples/hello/README.md new file mode 100644 index 00000000..15a44af2 --- /dev/null +++ b/examples/hello/README.md @@ -0,0 +1,73 @@ +# Hello chkit example + +Two MergeTree tables, `users` and `events`, and one migration that creates them. No dataset load. + +## Scaffold + +```bash +bun create chkit@latest my-chkit-app --example hello +cd my-chkit-app +``` + +The scaffolder asks how to connect. Choose **Claim a free ObsessionDB dev instance** and enter the emailed code. That creates a personal organization, provisions a free instance, and selects it. + +To use an existing ClickHouse instead, choose **I already have a ClickHouse instance** and set `CLICKHOUSE_URL`. + +`clickbench` stays available for the full public dataset: + +```bash +bun create chkit@latest my-chkit-app --example clickbench +``` + +## Or clone this folder + +```bash +cd examples/hello +bun install +``` + +Claim a free ObsessionDB dev instance: + +```bash +bunx chkit obsessiondb signup +bunx chkit obsessiondb service claim +``` + +Or point at a local ClickHouse: + +```bash +export CLICKHOUSE_URL=http://localhost:8123 +# export CLICKHOUSE_USER=default +# export CLICKHOUSE_PASSWORD=... +``` + +## Migrate + +```bash +bun run migrate +``` + +## Confirm + +```bash +bunx chkit query "SELECT name FROM system.tables WHERE database = 'default' AND name IN ('users', 'events') ORDER BY name" +``` + +Both tables come back: + +``` +name +──── +events +users +``` + +Stop there. The tables are empty. + +## Schema + +`src/db/schema/hello.ts` defines both tables. `chkit/migrations/20260928082853_create_hello_schema.sql` creates them. + +## Dependency security + +This example pins published chkit packages. Those releases still depend on vulnerable `@orpc/client` and `@orpc/contract` versions. The `overrides` in `package.json` replace them with `1.15.4`, including when this folder is copied out of the monorepo. diff --git a/examples/hello/chkit/meta/snapshot.json b/examples/hello/chkit/meta/snapshot.json new file mode 100644 index 00000000..7b3a4516 --- /dev/null +++ b/examples/hello/chkit/meta/snapshot.json @@ -0,0 +1,64 @@ +{ + "version": 1, + "generatedAt": "2026-09-28T08:28:53.623Z", + "definitions": [ + { + "database": "default", + "name": "events", + "engine": "MergeTree()", + "columns": [ + { + "name": "id", + "type": "UInt64" + }, + { + "name": "user_id", + "type": "UInt64" + }, + { + "name": "name", + "type": "String" + }, + { + "name": "created_at", + "type": "DateTime64(3)", + "default": "fn:now64(3)" + } + ], + "primaryKey": [ + "id" + ], + "orderBy": [ + "id" + ], + "kind": "table" + }, + { + "database": "default", + "name": "users", + "engine": "MergeTree()", + "columns": [ + { + "name": "id", + "type": "UInt64" + }, + { + "name": "email", + "type": "String" + }, + { + "name": "created_at", + "type": "DateTime64(3)", + "default": "fn:now64(3)" + } + ], + "primaryKey": [ + "id" + ], + "orderBy": [ + "id" + ], + "kind": "table" + } + ] +} diff --git a/examples/hello/chkit/migrations/20260928082853_create_hello_schema.sql b/examples/hello/chkit/migrations/20260928082853_create_hello_schema.sql new file mode 100644 index 00000000..83c6e6e7 --- /dev/null +++ b/examples/hello/chkit/migrations/20260928082853_create_hello_schema.sql @@ -0,0 +1,31 @@ +-- chkit-migration-format: v1 +-- generated-at: 2026-09-28T08:28:53.406Z +-- cli-version: 0.1.2-beta.7 +-- definition-count: 2 +-- operation-count: 3 +-- rename-suggestion-count: 0 +-- risk-summary: safe=3, caution=0, danger=0 + +-- operation: create_database key=database:default risk=safe +CREATE DATABASE IF NOT EXISTS default; + +-- operation: create_table key=table:default.events risk=safe +CREATE TABLE IF NOT EXISTS default.events +( + `id` UInt64, + `user_id` UInt64, + `name` String, + `created_at` DateTime64(3) DEFAULT now64(3) +) ENGINE = MergeTree() +PRIMARY KEY (`id`) +ORDER BY (`id`); + +-- operation: create_table key=table:default.users risk=safe +CREATE TABLE IF NOT EXISTS default.users +( + `id` UInt64, + `email` String, + `created_at` DateTime64(3) DEFAULT now64(3) +) ENGINE = MergeTree() +PRIMARY KEY (`id`) +ORDER BY (`id`); diff --git a/examples/hello/clickhouse.config.ts b/examples/hello/clickhouse.config.ts new file mode 100644 index 00000000..82620144 --- /dev/null +++ b/examples/hello/clickhouse.config.ts @@ -0,0 +1,16 @@ +import { defineConfig } from '@chkit/core' +import { obsessiondb } from '@chkit/plugin-obsessiondb' + +export default defineConfig({ + schema: './src/db/schema/**/*.ts', + outDir: './chkit', + migrationsDir: './chkit/migrations', + metaDir: './chkit/meta', + plugins: [obsessiondb()], + clickhouse: { + url: process.env.CLICKHOUSE_URL ?? 'http://localhost:8123', + username: process.env.CLICKHOUSE_USER ?? 'default', + password: process.env.CLICKHOUSE_PASSWORD ?? '', + database: 'default', + }, +}) diff --git a/examples/hello/package.json b/examples/hello/package.json new file mode 100644 index 00000000..4142bafd --- /dev/null +++ b/examples/hello/package.json @@ -0,0 +1,20 @@ +{ + "name": "chkit-example-hello", + "private": true, + "type": "module", + "packageManager": "bun@1.3.13", + "scripts": { + "migrate": "chkit migrate --apply", + "status": "chkit status", + "check": "chkit check" + }, + "devDependencies": { + "@chkit/core": "0.1.2-beta.7", + "@chkit/plugin-obsessiondb": "0.1.2-beta.7", + "chkit": "0.1.2-beta.7" + }, + "overrides": { + "@orpc/client": "1.15.4", + "@orpc/contract": "1.15.4" + } +} diff --git a/examples/hello/src/db/schema/hello.ts b/examples/hello/src/db/schema/hello.ts new file mode 100644 index 00000000..ecea0936 --- /dev/null +++ b/examples/hello/src/db/schema/hello.ts @@ -0,0 +1,30 @@ +import { schema, table } from '@chkit/core' + +const users = table({ + database: 'default', + name: 'users', + engine: 'MergeTree', + columns: [ + { name: 'id', type: 'UInt64' }, + { name: 'email', type: 'String' }, + { name: 'created_at', type: 'DateTime64(3)', default: 'fn:now64(3)' }, + ], + primaryKey: ['id'], + orderBy: ['id'], +}) + +const events = table({ + database: 'default', + name: 'events', + engine: 'MergeTree', + columns: [ + { name: 'id', type: 'UInt64' }, + { name: 'user_id', type: 'UInt64' }, + { name: 'name', type: 'String' }, + { name: 'created_at', type: 'DateTime64(3)', default: 'fn:now64(3)' }, + ], + primaryKey: ['id'], + orderBy: ['id'], +}) + +export default schema(users, events) diff --git a/examples/manifest.json b/examples/manifest.json index 19f5c638..16ae08c2 100644 --- a/examples/manifest.json +++ b/examples/manifest.json @@ -1,6 +1,10 @@ { - "default": "clickbench", + "default": "hello", "examples": [ + { + "name": "hello", + "description": "Two small tables and one migration. Claim a free ObsessionDB instance or use local ClickHouse." + }, { "name": "clickbench", "description": "Full ClickBench schema and dataset load against ObsessionDB or ClickHouse."