clisma 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,138 @@
+# 💊 clisma
+
+**A ClickHouse migrations CLI with templated SQL and environment-aware config.**
+
+<small>_"clisma" is a mashup of ClickHouse + Prisma. A dumb pun, but it stuck._</small>
+
+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.
+
+### So why it exists?
+
+- **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.
+- **Declarative environments** — keep local/staging/prod configs in one place.
+
+## 📦 How to use it
+
+### Global installation
+
+```bash
+npm install -g clisma
+```
+
+### NPM
+
+```bash
+npm install --save-dev clisma
+```
+
+### NPX
+
+```bash
+npx clisma
+```
+
+## 🚀 Quickstart
+
+Create `clisma.hcl`:
+
+```hcl
+env "local" {
+  url = "http://default:password@localhost:8123/mydb"
+
+  migrations {
+    dir = "migrations"
+  }
+}
+```
+
+Run migrations:
+
+```bash
+clisma run --env local
+clisma status --env local
+```
+
+## 🧩 Config basics
+
+- `env "name"` defines an environment.
+- `migrations` holds migration settings.
+- `variable "name"` defines inputs for `var.*`.
+- `env("NAME")` reads environment variables.
+
+### Example with variables and templates
+
+```hcl
+variable "ttl_days" {
+  type = string
+  default = "30"
+}
+
+env "production" {
+  url = env("CLICKHOUSE_PROD_URL")
+  cluster_name = "prod-cluster"
+
+  migrations {
+    dir = "migrations"
+    vars = {
+      is_replicated = true
+      create_table_options = "ON CLUSTER prod-cluster"
+      ttl_days = var.ttl_days
+    }
+  }
+}
+```
+
+**`cluster_name`** affects how the migrations tracking table is created (replicated or not). And the CLI will warn if the actual cluster does not match the config.
+
+#### If your ClickHouse server has clusters configured, `cluster_name` is required
+
+## 🧪 Templates
+
+Templates are [Handlebars](https://handlebarsjs.com/guide/expressions.html). Variables come from `migrations.vars` (and
+`cluster_name` is available as `{{cluster_name}}`).
+
+```sql
+CREATE TABLE IF NOT EXISTS events {{create_table_options}} (
+  id UUID,
+  created_at DateTime DEFAULT now()
+)
+{{#if is_replicated}}
+ENGINE = ReplicatedMergeTree('/clickhouse/tables/{cluster}/events', '{replica}')
+{{else}}
+ENGINE = MergeTree()
+{{/if}}
+ORDER BY id;
+```
+
+Multi-statement migrations are supported (split on semicolons outside strings/comments).
+
+## 🛠️ CLI
+
+Common commands:
+
+```bash
+clisma run --env local
+clisma status --env local
+clisma create --name create_events
+clisma checksum ./migrations/20240101123045_create_events.sql
+```
+
+### Additional flags
+
+- `--config <path>`
+- `--env <name>`
+- `--env-file <path>`
+- `--var <key=value>` (repeatable)
+
+The CLI requires a config file. Use `--config` or place `clisma.hcl` in the current directory.
+
+Example with variables and env file:
+
+```bash
+clisma run --env local --var ttl_days=30 --env-file .env
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clisma",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "ClickHouse migration CLI",
   "author": "github.com/will-work-for-meal",
   "license": "MIT",

package/dist/tests/integration.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=integration.test.d.ts.map

package/dist/tests/integration.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"integration.test.d.ts","sourceRoot":"","sources":["../../src/tests/integration.test.ts"],"names":[],"mappings":""}

package/dist/tests/integration.test.js

@@ -1,80 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-const exec = promisify(execFile);
-const isDockerAvailable = async () => {
-    try {
-        await exec("docker", ["--version"]);
-        await exec("docker", ["compose", "version"]);
-        return true;
-    }
-    catch {
-        return false;
-    }
-};
-const waitForClickHouse = async (baseUrl) => {
-    const deadline = Date.now() + 30_000;
-    while (Date.now() < deadline) {
-        try {
-            const response = await fetch(`${baseUrl}/ping`);
-            if (response.ok) {
-                return;
-            }
-        }
-        catch {
-            // Ignore until ready.
-        }
-        await new Promise((resolve) => setTimeout(resolve, 500));
-    }
-    throw new Error("ClickHouse did not become ready in time");
-};
-const runCli = async (repoRoot, args) => {
-    const cliPath = path.join(repoRoot, "packages/cli/src/cli.ts");
-    await exec("node", ["--import", "tsx", cliPath, ...args], { cwd: repoRoot });
-};
-const queryClickHouse = async (baseUrl, query) => {
-    const response = await fetch(`${baseUrl}/?query=${encodeURIComponent(query)}`);
-    if (!response.ok) {
-        const text = await response.text();
-        throw new Error(`ClickHouse query failed: ${text}`);
-    }
-    return response.text();
-};
-test("cli applies migrations against ClickHouse", async (t) => {
-    if (!(await isDockerAvailable())) {
-        t.skip("Docker not available");
-        return;
-    }
-    const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../..");
-    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "clisma-it-"));
-    const migrationsDir = path.join(tempDir, "migrations");
-    await fs.mkdir(migrationsDir, { recursive: true });
-    const baseUrl = "http://localhost:8123";
-    const dbName = `clisma_it_${Date.now()}`;
-    await exec("docker", ["compose", "up", "-d"], { cwd: repoRoot });
-    t.after(async () => {
-        try {
-            await exec("docker", ["compose", "down", "-v"], { cwd: repoRoot });
-        }
-        catch {
-            // Ignore cleanup failures.
-        }
-    });
-    await waitForClickHouse(baseUrl);
-    await queryClickHouse(baseUrl, `CREATE DATABASE IF NOT EXISTS ${dbName}`);
-    const configPath = path.join(tempDir, "clisma.hcl");
-    await fs.writeFile(configPath, `env "local" {\n  url = "http://default:@localhost:8123/${dbName}"\n\n  migrations {\n    dir = "migrations"\n  }\n}\n`, "utf8");
-    const migrationFile = path.join(migrationsDir, "20240101120000_create_table.sql");
-    await fs.writeFile(migrationFile, "CREATE TABLE IF NOT EXISTS test_table (id UInt64) ENGINE = MergeTree() ORDER BY id;", "utf8");
-    await runCli(repoRoot, ["run", "--config", configPath, "--env", "local"]);
-    const tableExists = await queryClickHouse(baseUrl, `EXISTS TABLE ${dbName}.test_table`);
-    assert.equal(tableExists.trim(), "1");
-    const migrationsCount = await queryClickHouse(baseUrl, `SELECT count() FROM ${dbName}.schema_migrations`);
-    assert.equal(migrationsCount.trim(), "1");
-    await queryClickHouse(baseUrl, `DROP DATABASE IF EXISTS ${dbName}`);
-});