{"id":16607,"library":"clicksuite","title":"Clicksuite: ClickHouse Migration Tool","description":"Clicksuite is a robust CLI and programmatic tool designed for managing ClickHouse database migrations. It supports environment-specific configurations, allowing for separate SQL definitions across development, test, and production environments. Key features include multi-statement migration support, environment variable interpolation for secure credential management (e.g., `${ENV_VAR}`), automatic `schema.sql` generation for multi-database schema tracking, and a dry-run mode for previewing migrations. The tool also provides verbose logging control and comprehensive migration management commands (apply, rollback, reset, status). It is currently at version 1.7.4, with a steady release cadence addressing fixes and adding features like programmatic usage settings and multi-statement support. It ships with full TypeScript types, making it suitable for modern JavaScript and TypeScript projects.","status":"active","version":"1.7.4","language":"javascript","source_language":"en","source_url":"https://github.com/GamebeastGG/clicksuite","tags":["javascript","clickhouse","migration","database","cli","schema","sql","migration-tool","typescript"],"install":[{"cmd":"npm install clicksuite","lang":"bash","label":"npm"},{"cmd":"yarn add clicksuite","lang":"bash","label":"yarn"},{"cmd":"pnpm add clicksuite","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For programmatic usage, the main class to interact with migrations.","symbol":"ClickHouseMigrator","correct":"import { ClickHouseMigrator } from 'clicksuite';"},{"note":"While primarily a CLI tool, `runCli` can be imported for integrating the CLI functionality into larger Node.js applications programmatically. Most users will interact via the global `clicksuite` command.","symbol":"runCli","correct":"import { runCli } from 'clicksuite/dist/cli';"},{"note":"Import types for programmatic configuration when using TypeScript.","symbol":"MigrationConfig","correct":"import type { MigrationConfig } from 'clicksuite';"}],"quickstart":{"code":"import { ClickHouseMigrator } from 'clicksuite';\nimport path from 'path';\n\n// Load environment variables (e.g., using 'dotenv')\nimport 'dotenv/config';\n\nasync function runMigrations() {\n  const config = {\n    clickhouseUrl: process.env.CLICKHOUSE_URL ?? 'http://default@localhost:8123/my_database',\n    migrationsDir: path.resolve(process.cwd(), 'migrations'),\n    migrationsDatabase: process.env.CLICKSUITE_MIGRATIONS_DATABASE ?? 'default',\n    environment: process.env.CLICKSUITE_ENVIRONMENT ?? 'development',\n    verbose: true,\n    skipSchemaUpdate: false,\n  };\n\n  const migrator = new ClickHouseMigrator(config);\n\n  console.log('Applying migrations...');\n  await migrator.up();\n  console.log('Migrations applied successfully.');\n\n  // Example of generating a new migration (typically done via CLI)\n  // await migrator.generate('create_users_and_products_tables');\n\n  // Example of rolling back the last migration\n  // console.log('Rolling back last migration...');\n  // await migrator.down();\n  // console.log('Last migration rolled back.');\n}\n\nrunMigrations().catch(error => {\n  console.error('Migration failed:', error);\n  process.exit(1);\n});","lang":"typescript","description":"Demonstrates programmatic usage of Clicksuite to apply migrations, configuring connection details and paths using environment variables."},"warnings":[{"fix":"Update your programmatic configuration to use `migrationsDatabase` instead of `database` for specifying the database where migration tracking tables reside.","message":"The `database` setting in programmatic usage has been deprecated. It should be replaced with the new `migrationsDatabase` option.","severity":"deprecated","affected_versions":">=1.7.0"},{"fix":"Upgrade your Node.js environment to version 16 or newer. Use `nvm` or similar tools for managing Node.js versions easily.","message":"When installing Clicksuite globally (`npm install -g clicksuite`), ensure your Node.js version meets the `engines` requirement (>=16.0.0). Older Node.js versions may lead to unexpected behavior or installation failures.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify that `CLICKHOUSE_URL` is correctly set in your `.env` file (e.g., `CLICKHOUSE_URL=http://default@localhost:8123/my_database`) and accessible by the process running Clicksuite.","message":"Environment variables are crucial for Clicksuite's operation. If `CLICKHOUSE_URL` is not properly configured in your `.env` file or environment, Clicksuite will fail to connect to your ClickHouse instance.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Check if your ClickHouse instance is running and accessible from where Clicksuite is executed. Verify the `CLICKHOUSE_URL` environment variable for correct host, port, and credentials. Ensure no firewalls are blocking the connection.","cause":"Clicksuite could not establish a connection to the ClickHouse instance at the specified `CLICKHOUSE_URL`.","error":"Error: ConnectException: Connection refused"},{"fix":"Run `clicksuite init` to create the default migrations directory and the `__clicksuite_migrations` table. If using a custom directory, ensure `CLICKSUITE_MIGRATIONS_DIR` is correctly set and the directory exists.","cause":"The migrations directory specified (or defaulted to `./migrations`) does not exist when Clicksuite attempts to read or write migration files.","error":"Error: ENOENT: no such file or directory, stat './migrations'"},{"fix":"Run `clicksuite init` to initialize the project and create the necessary tracking table. If using a custom database for migrations, ensure `CLICKSUITE_MIGRATIONS_DATABASE` is correctly configured.","cause":"Clicksuite's internal migration tracking table `__clicksuite_migrations` is missing in the specified database.","error":"Error: Table '__clicksuite_migrations' does not exist."}],"ecosystem":"npm"}