Skip to content

docs: add a 2-minute hello scaffold to the README #229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
KeKs0r wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: add a 2-minute hello scaffold to the README #229

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 18 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,26 @@ 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.

## Get started in 2 minutes

Scaffold [hello](examples/hello), the default example: two MergeTree tables (`users` and `events`) and one migration. No dataset load.

```sh
bun create chkit@latest my-app --example hello
cd my-app
# claim a free ObsessionDB instance from the prompt, or set CLICKHOUSE_URL
bun run migrate
bunx chkit query "SELECT name FROM system.tables WHERE database = 'default' AND name IN ('users', 'events') ORDER BY name"
```

Bare `bun create chkit@latest` uses the same hello default. The npm, pnpm, and yarn equivalents are `npm create chkit@latest`, `pnpm create chkit@latest`, and `yarn create chkit`.

You can also clone [`examples/hello`](examples/hello) and follow its README. The heavier ClickBench path is `bun create chkit@latest my-app --example clickbench`, or [`examples/clickbench`](examples/clickbench).

Continue in [Getting started](https://chkit.obsessiondb.com/getting-started/).

## Why chkit

- **Define tables and views.** Keep ClickHouse tables, views, materialized views, and dictionaries in code. Import the schema from an existing database.
Expand Down
11 changes: 6 additions & 5 deletions packages/create-chkit/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,18 +14,18 @@ pnpm create chkit@latest
yarn create chkit
```

Pick an example by name:
Pick an example by name. `hello` is the default when `--example` is omitted:

```sh
bun create chkit@latest my-app --example clickbench
bun create chkit@latest my-app --example hello
```

## Options

| Flag | Description |
| --- | --- |
| `[project-directory]` | Target directory. Prompted if omitted. |
| `-e, --example <name>` | Example to scaffold. Bare name (`clickbench`) or full GitHub URL. Prompted with the list of bundled examples if omitted. |
| `-e, --example <name>` | Example to scaffold. Bare name (`hello`, `clickbench`) or full GitHub URL. Prompted with the list of bundled examples if omitted. `hello` is the default. |
| `-m, --package-manager <pm>` | `npm`, `pnpm`, `yarn`, or `bun`. Auto-detected from the invoking package manager. |
| `--skip-install` | Skip installing dependencies after scaffolding. |
| `-v, --version` | Print version. |
Expand All @@ -35,6 +35,7 @@ bun create chkit@latest my-app --example clickbench

| Name | Description |
| --- | --- |
| `clickbench` | Full ClickBench schema and dataset load against ObsessionDB / ClickHouse. |
| `hello` | Default. Two small tables (`users`, `events`) and one migration. No dataset load. Claim a free ObsessionDB instance from the scaffold prompt, or set `CLICKHOUSE_URL`. |
| `clickbench` | Full ClickBench schema and dataset load against ObsessionDB or ClickHouse. |

See the [chkit documentation](https://chkit.obsessiondb.com) for the full list.
See [Getting started](https://chkit.obsessiondb.com/getting-started/).
Loading