{"id":47261,"library":"clisma","title":"clisma","description":"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.","status":"active","version":"0.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/StopMakingThatBigFace/clisma","tags":["javascript","cli","clickhouse","migrations","clickhouse-migrations","clickhouse-migration","clickhouse-migrate","atlas","atlasgo"],"install":[{"cmd":"npm install clisma","lang":"bash","label":"npm"},{"cmd":"yarn add clisma","lang":"bash","label":"yarn"},{"cmd":"pnpm add clisma","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"HTTP client for ClickHouse operations","package":"clickhouse","optional":false},{"reason":"SQL template engine","package":"handlebars","optional":false}],"imports":[{"note":"ESM-only; no default export. Use named import for CLI programmatic usage, but typically used via CLI directly.","wrong":"const clisma = require('clisma')","symbol":"clisma","correct":"import { clisma } from 'clisma'"},{"note":"Flags use space separation, not equals signs. Config must be in current directory or specified with --config.","wrong":"clisma run --env=local","symbol":"CLI usage","correct":"npx clisma run --env local"},{"note":"Environment names must be quoted in the HCL config file.","wrong":"env local { url = \"http://default:password@localhost:8123/mydb\" }","symbol":"Config file","correct":"env \"local\" { url = \"http://default:password@localhost:8123/mydb\" }"}],"quickstart":{"code":"// Initialize project\nmkdir my-clickhouse-migrations && cd my-clickhouse-migrations\nnpm init -y\nnpm install --save-dev clisma\n\n// Create config file: clisma.hcl\ncat > clisma.hcl << 'EOF'\nenv \"local\" {\n  url = \"http://default:password@localhost:8123/mydb\"\n  migrations {\n    dir = \"migrations\"\n  }\n}\nEOF\n\n// Create first migration\nmkdir migrations\ncat > migrations/20240101123045_create_events.sql << 'EOF'\nCREATE TABLE IF NOT EXISTS events\n(\n  id UUID,\n  event_type String,\n  created_at DateTime DEFAULT now()\n)\nENGINE = MergeTree()\nORDER BY id;\nEOF\n\n// Run migration\nnpx clisma run --env local\n\n// Check status\nnpx clisma status --env local","lang":"typescript","description":"Shows full setup: install, config file with environment, migration creation, and run/status commands."},"warnings":[{"fix":"Rename your config to clisma.hcl or use --config <path>.","message":"Config file must be named 'clisma.hcl' or specified with --config. No other config formats supported.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Rename migration files to match the pattern, e.g., 20240101123045_create_table.sql.","message":"Migration file names must follow timestamp format: YYYYMMDDHHMMSS_description.sql. Other patterns may be ignored or cause errors.","severity":"breaking","affected_versions":">=0.2.0"},{"fix":"Replace 'cluster' with 'cluster_name' in the migrations.table block.","message":"The 'table' block in config previously allowed 'cluster' property; it was renamed to 'cluster_name' in 0.3.0.","severity":"deprecated","affected_versions":">=0.3.0"},{"fix":"Replace ${VAR} with env(\"VAR\") in config HCL files.","message":"Environment variable interpolation changed syntax: ${VAR} no longer works; use env(\"VAR\") instead.","severity":"breaking","affected_versions":">=0.2.5"},{"fix":"Avoid using semicolons inside literal strings in SQL; consider single-statement files if issues arise.","message":"Multi-statement migrations split on semicolons, but semicolons inside strings or comments are not handled correctly in all edge cases.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"search_vec":"'0.3.1':18 'also':80 'altern':33 'atlas':35,103 'atlasgo':104 'awar':12,69 'block':60 'built':65 'built-in':64 'checksum':88 'cli':5,91 'clickhous':3,38,92,95,98,101 'clickhouse-migr':37,94,97,100 'clisma':1 'code':27 'companion':29 'config':63 'configur':13,72 'connect':78 'current':14 'custom':85 'declar':58 'differenti':31 'environ':11,59,82 'environment-awar':10 'extens':28 'file':47,52 'handlebar':43 'hcl':62 'includ':40 'interpol':84 'javascript':90 'key':30 'like':34 'migrat':4,39,46,51,93,96,99,102 'multi':49 'multi-stat':48 'need':54 'npm':22 'packag':23 'releas':19 'replic':68 'replication-awar':67 'secur':77 'split':56 'sql':8,57 'stabl':15 'statement':50 'support':41,75,81 'tabl':71 'templat':7,44 'tls/mtls':74 'track':70 'valid':89 'variabl':83,86 'version':16 'vs':26","created_at":"2026-06-07T16:50:36.867300+00:00","updated_at":"2026-06-07T16:50:36.867300+00:00","problems":[{"fix":"Ensure clisma.hcl exists or use --config <path>.","cause":"Config file not found; clisma looks for clisma.hcl in current directory.","error":"Error: ENOENT: no such file or directory, open 'clisma.hcl'"},{"fix":"Check config file for env block name; use --env with correct name.","cause":"The environment name must match exactly a block in the config file.","error":"Error: Invalid environment: 'local' not defined in config"},{"fix":"Rename file to include timestamp, e.g., 20240101123045_foo.sql.","cause":"Migration filenames must follow timestamp prefix format.","error":"Error: Migration file 'migrations/foo.sql' does not match expected naming pattern. Expected format: YYYYMMDDHHMMSS_description.sql"},{"fix":"Verify config structure: at minimum an env block with url and migrations.dir.","cause":"Config HCL syntax error, likely a missing 'env' block.","error":"Error: Failed to parse config: expected a top-level block"},{"fix":"Check that ClickHouse is running on port 8123 and URL is correct in config.","cause":"ClickHouse server not running or wrong URL.","error":"Error: Connection refused (localhost:8123)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/StopMakingThatBigFace/clisma","github":"https://github.com/StopMakingThatBigFace/clisma","docs":null,"changelog":null,"pypi":null,"npm":"clisma","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}