clisma

library0.3.1jsnpmunverified

A ClickHouse migrations CLI with templated SQL and environment-aware configuration. Current stable version is 0.3.1, released as an npm package with a VS Code extension companion. Key differentiators from alternatives like Atlas or clickhouse-migrations include support for Handlebars templates in migration files, multi-statement migration files (no need to split SQL), declarative environment blocks in HCL config, built-in replication-aware tracking table configuration, and TLS/mTLS support for secure connections. It also supports environment variable interpolation, custom variables, and checksum validation.

database devops

npm install clisma

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CLISMA

clisma

databasejavascriptv0.3.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

clisma

✓ import { clisma } from 'clisma'

✗ const clisma = require('clisma')

ESM-only; no default export. Use named import for CLI programmatic usage, but typically used via CLI directly.

CLI usage

✓ npx clisma run --env local

✗ clisma run --env=local

Flags use space separation, not equals signs. Config must be in current directory or specified with --config.

Config file

✓ env "local" { url = "http://default:password@localhost:8123/mydb" }

✗ env local { url = "http://default:password@localhost:8123/mydb" }

Environment names must be quoted in the HCL config file.

Shows full setup: install, config file with environment, migration creation, and run/status commands.

// Initialize project mkdir my-clickhouse-migrations && cd my-clickhouse-migrations npm init -y npm install --save-dev clisma // Create config file: clisma.hcl cat > clisma.hcl << 'EOF' env "local" { url = "http://default:password@localhost:8123/mydb" migrations { dir = "migrations" } } EOF // Create first migration mkdir migrations cat > migrations/20240101123045_create_events.sql << 'EOF' CREATE TABLE IF NOT EXISTS events ( id UUID, event_type String, created_at DateTime DEFAULT now() ) ENGINE = MergeTree() ORDER BY id; EOF // Run migration npx clisma run --env local // Check status npx clisma status --env local

Debug

Known issues

gotchaConfig file must be named 'clisma.hcl' or specified with --config. No other config formats supported.

fix

Rename your config to clisma.hcl or use --config <path>.

affects: >=0.1.0

breakingMigration file names must follow timestamp format: YYYYMMDDHHMMSS_description.sql. Other patterns may be ignored or cause errors.

fix

Rename migration files to match the pattern, e.g., 20240101123045_create_table.sql.

affects: >=0.2.0

deprecatedThe 'table' block in config previously allowed 'cluster' property; it was renamed to 'cluster_name' in 0.3.0.

fix

Replace 'cluster' with 'cluster_name' in the migrations.table block.

affects: >=0.3.0

breakingEnvironment variable interpolation changed syntax: ${VAR} no longer works; use env("VAR") instead.

fix

Replace ${VAR} with env("VAR") in config HCL files.

affects: >=0.2.5

gotchaMulti-statement migrations split on semicolons, but semicolons inside strings or comments are not handled correctly in all edge cases.

fix

Avoid using semicolons inside literal strings in SQL; consider single-statement files if issues arise.

affects: >=0.1.0

Errors

Common errors & fixes

Error: ENOENT: no such file or directory, open 'clisma.hcl'

Config file not found; clisma looks for clisma.hcl in current directory.

fix

Ensure clisma.hcl exists or use --config <path>.

Error: Invalid environment: 'local' not defined in config

The environment name must match exactly a block in the config file.

fix

Check config file for env block name; use --env with correct name.

Error: Migration file 'migrations/foo.sql' does not match expected naming pattern. Expected format: YYYYMMDDHHMMSS_description.sql

Migration filenames must follow timestamp prefix format.

fix

Rename file to include timestamp, e.g., 20240101123045_foo.sql.

Error: Failed to parse config: expected a top-level block

Config HCL syntax error, likely a missing 'env' block.

fix

Verify config structure: at minimum an env block with url and migrations.dir.

Error: Connection refused (localhost:8123)

ClickHouse server not running or wrong URL.

fix

Check that ClickHouse is running on port 8123 and URL is correct in config.

Upgrade

Version history

0.3.1latest on npm

Audit

Dependencies

clickhouserequiredHTTP client for ClickHouse operations

handlebarsrequiredSQL template engine

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/StopMakingThatBigFace/clisma ↗

packageclisma ↗

homepagehttps://github.com/StopMakingThatBigFace/clisma ↗