diff --git a/README.md b/README.md index bebc406..3a74f9e 100644 --- a/README.md +++ b/README.md @@ -2,15 +2,11 @@ **A ClickHouse migrations CLI with templated SQL and environment-aware config.** -_"clisma" is a mashup of ClickHouse + Prisma. A dumb pun, but it stuck._ +_"clisma" is a mashup of ClickHouse + Prisma. A dumb pun, but it stuck._ 👉👈 -This project borrows ideas from tools we like: - -- **[Atlas](https://atlasgo.io/)** for the idea of [templated migrations](https://atlasgo.io/concepts/migrations#template) and [config-driven environments](https://atlasgo.io/concepts/dev-database). +

💅 More Docs →

-- **[Prisma](https://www.prisma.io/)** for the simple, friendly CLI experience. - -### So why it exists? +## What is for? - **Templates in migrations** — Atlas has this, but it is paid; clisma keeps it simple and open. - **Multi-statement migrations** — write real SQL without splitting into tiny files. @@ -136,3 +132,11 @@ Example with variables and env file: ```bash clisma run --env local --var ttl_days=30 --env-file .env ``` + +## So What is this + +This project borrows ideas from tools we like: + +- **[Atlas](https://atlasgo.io/)** for the idea of [templated migrations](https://atlasgo.io/concepts/migrations#template) and [config-driven environments](https://atlasgo.io/concepts/dev-database). + +- **[Prisma](https://www.prisma.io/)** for the simple, friendly CLI experience. diff --git a/docs/cli.md b/docs/cli.mdx similarity index 54% rename from docs/cli.md rename to docs/cli.mdx index 5289127..7ed5397 100644 --- a/docs/cli.md +++ b/docs/cli.mdx @@ -1,10 +1,16 @@ --- -title: CLI +title: "Commands" +description: "Run, inspect, and create migrations from the command line" +icon: "terminal" --- -Clisma ships a CLI for applying and inspecting migrations. + + **Prerequisites**: + + - A `clisma.hcl` config file in the current directory, or pass `--config` + -The CLI requires a config file. Use `--config` or place `clisma.hcl` in the current directory. +Clisma ships a CLI for applying and inspecting migrations. ## Commands @@ -46,18 +52,23 @@ clisma checksum ./migrations/20240101123045_create_users.sql ## Flags -- **`--env ` — environment from config file.** +- **`--env — environment from config file.`** Example: `--env production` - -- **`--config ` — path to config file.** +- **`--config — path to config file.`** Example: `--config ./clisma.hcl` - -- **`--var ` — set variable value (repeatable).** +- **`--var — set variable value (repeatable).`** Example: `--var ttl_days=30 --var replication_factor=3` +- **`--env-file — load env vars from file.`** -- **`--env-file ` — load env vars from file.** - Example: `--env-file .env` + +## Advanced usage + +Run with a custom config path and multiple variables: + +```bash +clisma run --config ./infra/clisma.hcl --env staging --var ttl_days=30 --var replication_factor=2 +``` \ No newline at end of file diff --git a/docs/configuration/env-and-vars.md b/docs/configuration/env-and-vars.mdx similarity index 75% rename from docs/configuration/env-and-vars.md rename to docs/configuration/env-and-vars.mdx index 2dd44bf..5d09417 100644 --- a/docs/configuration/env-and-vars.md +++ b/docs/configuration/env-and-vars.mdx @@ -1,5 +1,7 @@ --- -title: env() and Variables +title: "env() and variables" +description: "Use environment variables and config variables in clisma.hcl" +icon: "book-open-cover" --- ## env() @@ -40,7 +42,7 @@ env "local" { ## Cluster name -If you want migrations_table to be replicated and use cluster-aware templates, set +If you want the migrations table to be replicated and use cluster-aware templates, set `cluster_name` in the environment: ```hcl diff --git a/docs/configuration/examples.md b/docs/configuration/examples.mdx similarity index 86% rename from docs/configuration/examples.md rename to docs/configuration/examples.mdx index 7f827b9..f5ab7a9 100644 --- a/docs/configuration/examples.md +++ b/docs/configuration/examples.mdx @@ -1,5 +1,7 @@ --- -title: Examples +title: "Examples" +description: "Common clisma.hcl configurations for local and production" +icon: "notes-medical" --- ## Local @@ -52,4 +54,4 @@ variable "replication_factor" { type = string default = "3" } -``` +``` \ No newline at end of file diff --git a/docs/configuration/overview.md b/docs/configuration/overview.mdx similarity index 92% rename from docs/configuration/overview.md rename to docs/configuration/overview.mdx index f1c49fd..a2829c8 100644 --- a/docs/configuration/overview.md +++ b/docs/configuration/overview.mdx @@ -1,5 +1,7 @@ --- -title: Configuration Overview +title: "clisma.hcl" +description: "Define environments and migration settings in clisma.hcl" +icon: "file-pen" --- Clisma uses an HCL config file to define environments and migration settings. @@ -61,4 +63,4 @@ variable "ttl_days" { default = "30" description = "Default TTL" } -``` +``` \ No newline at end of file diff --git a/docs/docs.json b/docs/docs.json new file mode 100644 index 0000000..77851f9 --- /dev/null +++ b/docs/docs.json @@ -0,0 +1,69 @@ +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "aspen", + "name": "clisma", + "colors": { + "primary": "#16A34A", + "light": "#07C983", + "dark": "#15803D" + }, + "favicon": "/favicon.svg", + "navigation": { + "tabs": [ + { + "tab": "Guides", + "groups": [ + { + "group": "Getting started", + "icon": "rocket-launch", + "pages": [ + "index", + "installation" + ] + }, + { + "group": "Configuration", + "icon": "database", + "pages": [ + "configuration/overview", + "configuration/env-and-vars", + "configuration/examples" + ] + }, + { + "group": "Migrations", + "pages": [ + "migrations/how-it-works", + "migrations/templates", + "migrations/naming", + "migrations/faq" + ] + }, + { + "group": "CLI", + "icon": "game-console-handheld", + "pages": [ + "cli" + ] + } + ] + } + ] + }, + "logo": { + "light": "/logo/light.svg", + "dark": "/logo/dark.svg" + }, + "contextual": { + "options": [ + "copy", + "view", + "chatgpt", + "claude", + "perplexity", + "mcp", + "cursor", + "vscode" + ] + } +} diff --git a/docs/favicon.svg b/docs/favicon.svg new file mode 100644 index 0000000..b785c73 --- /dev/null +++ b/docs/favicon.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index 12de2c8..0000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Getting Started ---- - -clisma is a ClickHouse migration tool with templating support and environment configuration. - -## Installation - -```bash -npm install --save-dev clisma -``` - -Or install it globally: - -```bash -npm install -g clisma -``` - -## Quickstart - -### 1. Create a config - -Create `clisma.hcl` in your project root: - -```hcl -env "local" { - url = "http://default:password@localhost:8123/mydb" - - migrations { - dir = "migrations/clickhouse" - } -} -``` - -### 2. Create your first migration - -```bash -clisma create -``` - -### 3. Run it - -```bash -clisma run --env local -``` - -### 4. Check status - -```bash -clisma status --env local -``` - -You can also pass config variables and load environment files: - -```bash -clisma run --env local --var ttl_days=30 --env-file .env -``` diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 44cebdc..0000000 --- a/docs/index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: clisma ---- - -Clisma is a ClickHouse migration tool with templating support and environment configuration. -Think of it as a tiny, pragmatic CLI for migrations with a bit of templating sugar. - -Use the CLI for day-to-day workflows, or the core package for programmatic control. - -## What it does - -- Applies SQL migrations in order and tracks them in ClickHouse. -- Supports Handlebars templating with auto-detected cluster context. -- Reads environment-specific configuration from `clisma.hcl`. - -## Inspiration - -This project borrows ideas from tools we like: - -- [Prisma](https://www.prisma.io/) for the simple, friendly CLI experience. -- [Atlas](https://atlasgo.io/) for the idea of templated migrations and config-driven environments. - -For Atlas, the inspiration is templated migrations and environment config: - -- [Templated migrations](https://atlasgo.io/concepts/migrations#template) -- [Environment configuration](https://atlasgo.io/concepts/dev-database) - -> Why the weird name? -> -> It is a little joke: ClickHouse + Prisma -> clisma. There is no full schema -> management here (yet), but the vibe is similar. - -## Next steps - -- Install the CLI and run your first migration. -- Set up `clisma.hcl` with `migrations` and variables. diff --git a/docs/index.mdx b/docs/index.mdx new file mode 100644 index 0000000..eef3d94 --- /dev/null +++ b/docs/index.mdx @@ -0,0 +1,35 @@ +--- +title: "What is clisma" +description: "Overview of the ClickHouse migration tool and how you use it" +icon: "hand-wave" +--- + +Clisma is a ClickHouse migration tool with templating support and environment configuration. You use the CLI for day-to-day workflows, or the core package for programmatic control. + +## What it does + +- Applies SQL migrations in order and tracks them in ClickHouse. +- Supports Handlebars templating with auto-detected cluster context. +- Reads environment-specific configuration from `clisma.hcl`. + +## Inspiration + +This project borrows ideas from tools you may already know: + +- [Prisma](https://www.prisma.io/) for the simple, friendly CLI experience. +- [Atlas](https://atlasgo.io/) for templated migrations and config-driven environments. + +Related Atlas concepts: + +- [Templated migrations](https://atlasgo.io/concepts/migrations#template) +- [Environment configuration](https://atlasgo.io/concepts/dev-database) + +> Why the weird name? +> +> It is a little joke: ClickHouse + Prisma -\> clisma. There is no full schema management here (yet), but the vibe is similar. + +## Next steps + +- Follow the [Getting started](./getting-started) guide. +- Define your environments in [Configuration](./configuration/overview). +- Learn about [Templates](./migrations/templates) for advanced SQL. \ No newline at end of file diff --git a/docs/installation.mdx b/docs/installation.mdx new file mode 100644 index 0000000..c1096dc --- /dev/null +++ b/docs/installation.mdx @@ -0,0 +1,67 @@ +--- +title: "Installation and Quickstart" +description: "Install clisma and run your first ClickHouse migration" +icon: "play" +--- + + + **Prerequisites**: + + - Access to a ClickHouse instance and credentials + - A project directory where you can add `clisma.hcl` + + +clisma is a ClickHouse migration tool with templating support and environment configuration. + +## Installation + +```bash +npm install --save-dev clisma +``` + +Or install it globally: + +```bash +npm install -g clisma +``` + +## Quickstart + + + + Create `clisma.hcl` in your project root: + + ```hcl + env "local" { + url = "http://default:password@localhost:8123/mydb" + + migrations { + dir = "migrations/clickhouse" + } + } + ``` + + + ```bash + clisma create + ``` + + + ```bash + clisma run --env local + ``` + + + ```bash + clisma status --env local + ``` + + + +## Advanced usage + +You can pass variables and load environment files when you run migrations: + +```bash +clisma run --env local --var ttl_days=30 --env-file .env +``` \ No newline at end of file diff --git a/docs/migrations/faq.md b/docs/migrations/faq.mdx similarity index 52% rename from docs/migrations/faq.md rename to docs/migrations/faq.mdx index 2ec00b5..f25382d 100644 --- a/docs/migrations/faq.md +++ b/docs/migrations/faq.mdx @@ -1,8 +1,9 @@ --- -title: FAQ +title: "FAQ" +description: "Answers to common questions about clisma migrations" +icon: "question" --- - ## Custom table name You can override the table name in config: @@ -20,8 +21,7 @@ env "local" { ## Custom replication path -In clustered setups you can override the migrations table replication path used by -`ReplicatedReplacingMergeTree(...)`: +In clustered setups you can override the migrations table replication path used by `ReplicatedReplacingMergeTree(...)`: ```hcl env "production" { @@ -38,40 +38,27 @@ env "production" { Default replication path: -```sh +```text /clickhouse/tables/cluster-{cluster}/shard-{shard}/{database}/${migrations.table_name} ``` ### Summary -If `env.cluster_name` is set, clisma treats the environment as clustered and -creates the migrations table using `ReplicatedReplacingMergeTree(...)` with -`ON CLUSTER ""`. +If `env.cluster_name` is set, clisma treats the environment as clustered and creates the migrations table using `ReplicatedReplacingMergeTree(...)` with `ON CLUSTER ""`. -If `cluster_name` is not set in config and ClickHouse reports configured clusters, clisma -stops and asks you to set `cluster_name`. If there are no clusters, it uses -`ReplacingMergeTree()` in standalone mode. +If `cluster_name` is not set in config and ClickHouse reports configured clusters, clisma stops and asks you to set `cluster_name`. If there are no clusters, it uses `ReplacingMergeTree()` in standalone mode. -## Does clisma support Down migrations? +## Does clisma support down migrations? -No. This is intentional. ClickHouse DDL and data changes are often -non-transactional and may be irreversible. Reliable rollbacks are hard to -guarantee and can introduce more risk than they remove. The expected workflow -is to apply new forward migrations that correct or compensate for previous -changes. +No. This is intentional. ClickHouse DDL and data changes are often non-transactional and may be irreversible. Reliable rollbacks are hard to guarantee and can introduce more risk than they remove. The expected workflow is to apply new forward migrations that correct or compensate for previous changes. -## Does clisma support Multi-statement migrations? +## Does clisma support multi-statement migrations? -Yes. You can include multiple SQL statements in one file. Separate statements with -semicolons; clisma splits them outside of strings and comments. +Yes. You can include multiple SQL statements in one file. Separate statements with semicolons; clisma splits them outside of strings and comments. ## Checksum mismatch -If a migration file changes after being applied, clisma will fail with a -checksum mismatch. You have two options: +If a migration file changes after being applied, clisma will fail with a checksum mismatch. You have two options: -- Revert the migration file back to the applied version and create a new - forward migration. -- If you really need to override the checksum, update the stored checksum in - the migrations table (use `clisma checksum `). This is risky - and should only be done if you fully understand the consequences. +- Revert the migration file back to the applied version and create a new forward migration. +- If you really need to override the checksum, update the stored checksum in the migrations table (use `clisma checksum `). This is risky and should only be done if you fully understand the consequences. \ No newline at end of file diff --git a/docs/migrations/how-it-works.md b/docs/migrations/how-it-works.mdx similarity index 82% rename from docs/migrations/how-it-works.md rename to docs/migrations/how-it-works.mdx index c33156d..7bdf6fd 100644 --- a/docs/migrations/how-it-works.md +++ b/docs/migrations/how-it-works.mdx @@ -1,5 +1,7 @@ --- -title: How Migrations Work +title: "How migrations work" +description: "Understand how clisma tracks and validates migrations" +icon: "diagram-subtask" --- ## Migrations table diff --git a/docs/migrations/naming.md b/docs/migrations/naming.mdx similarity index 50% rename from docs/migrations/naming.md rename to docs/migrations/naming.mdx index 65d44d8..6f4df4f 100644 --- a/docs/migrations/naming.md +++ b/docs/migrations/naming.mdx @@ -1,5 +1,7 @@ --- -title: Naming and Ordering +title: "Naming and ordering" +description: "Follow the required migration filename format" +icon: "tag" --- Migration files must follow this pattern: @@ -11,4 +13,4 @@ YYYYMMDDhhmmss_.sql Examples: - `20240101123045_create_users.sql` -- `20240214104500_add_index.sql` +- `20240214104500_add_index.sql` \ No newline at end of file diff --git a/docs/migrations/templates.md b/docs/migrations/templates.mdx similarity index 93% rename from docs/migrations/templates.md rename to docs/migrations/templates.mdx index e66459d..d6bfe93 100644 --- a/docs/migrations/templates.md +++ b/docs/migrations/templates.mdx @@ -1,5 +1,7 @@ --- -title: Templates +title: "Templates" +description: "Use Handlebars variables in migrations to adapt across environments" +icon: "notes-medical" --- Template variables come from `migrations.vars` in your config. If you set diff --git a/docs/mint.json b/docs/mint.json deleted file mode 100644 index f449973..0000000 --- a/docs/mint.json +++ /dev/null @@ -1,37 +0,0 @@ -{ - "name": "clisma", - "logo": "/logo.svg", - "favicon": "/favicon.svg", - "navigation": [ - { - "group": "Getting Started", - "pages": [ - "index", - "getting-started" - ] - }, - { - "group": "Configuration", - "pages": [ - "configuration/overview", - "configuration/env-and-vars", - "configuration/examples" - ] - }, - { - "group": "Migrations", - "pages": [ - "migrations/how-it-works", - "migrations/templates", - "migrations/naming", - "migrations/faq" - ] - }, - { - "group": "CLI", - "pages": [ - "cli" - ] - } - ] -} diff --git a/packages/cli/package.json b/packages/cli/package.json index 8764729..38fd5e7 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -1,6 +1,6 @@ { "name": "clisma", - "version": "0.1.1", + "version": "0.1.2", "description": "ClickHouse migration CLI", "author": "github.com/will-work-for-meal", "license": "MIT", diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts index 019406f..56bace2 100644 --- a/packages/cli/src/cli.ts +++ b/packages/cli/src/cli.ts @@ -1,3 +1,5 @@ +#!/usr/bin/env node + import path from "node:path"; import fs from "node:fs/promises"; import crypto from "node:crypto"; @@ -49,7 +51,6 @@ const parseEnvFile = async ( return parseDotenv(contents); }; - const resolveEnvName = async ( configPath: string, envName?: string, @@ -109,7 +110,10 @@ const runCommand = async ( ); connectionString = envConfig.url; - migrationsDir = path.resolve(path.dirname(configPath), envConfig.migrations.dir); + migrationsDir = path.resolve( + path.dirname(configPath), + envConfig.migrations.dir, + ); // Extract table_name, cluster_name, and replication_path from config tableName = envConfig.migrations.table_name; @@ -184,7 +188,10 @@ program envOverrides, ); - migrationsDir = path.resolve(path.dirname(configPath), envConfig.migrations.dir); + migrationsDir = path.resolve( + path.dirname(configPath), + envConfig.migrations.dir, + ); // Get migration name from flag or prompt let migrationName = options.name;