Clicksuite: ClickHouse Migration Tool

Common errors

• Error: ConnectException: Connection refused

  cause Clicksuite could not establish a connection to the ClickHouse instance at the specified `CLICKHOUSE_URL`.
  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.

• Error: ENOENT: no such file or directory, stat './migrations'

  cause The migrations directory specified (or defaulted to `./migrations`) does not exist when Clicksuite attempts to read or write migration files.
  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.

• Error: Table '__clicksuite_migrations' does not exist.

  cause Clicksuite's internal migration tracking table `__clicksuite_migrations` is missing in the specified database.
  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.

Warnings

• deprecated The `database` setting in programmatic usage has been deprecated. It should be replaced with the new `migrationsDatabase` option.
  Fix: Update your programmatic configuration to use `migrationsDatabase` instead of `database` for specifying the database where migration tracking tables reside.
• gotcha 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.
  Fix: Upgrade your Node.js environment to version 16 or newer. Use `nvm` or similar tools for managing Node.js versions easily.
• gotcha 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.
  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.

Install

• npm install clicksuite npm
• yarn add clicksuite yarn
• pnpm add clicksuite pnpm

Imports

• ClickHouseMigrator

  import { ClickHouseMigrator } from 'clicksuite';

  For programmatic usage, the main class to interact with migrations.
• runCli

  import { runCli } from 'clicksuite/dist/cli';

  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.
• MigrationConfig

  import type { MigrationConfig } from 'clicksuite';

  Import types for programmatic configuration when using TypeScript.

Quickstart

Demonstrates programmatic usage of Clicksuite to apply migrations, configuring connection details and paths using environment variables.

import { ClickHouseMigrator } from 'clicksuite';
import path from 'path';

// Load environment variables (e.g., using 'dotenv')
import 'dotenv/config';

async function runMigrations() {
  const config = {
    clickhouseUrl: process.env.CLICKHOUSE_URL ?? 'http://default@localhost:8123/my_database',
    migrationsDir: path.resolve(process.cwd(), 'migrations'),
    migrationsDatabase: process.env.CLICKSUITE_MIGRATIONS_DATABASE ?? 'default',
    environment: process.env.CLICKSUITE_ENVIRONMENT ?? 'development',
    verbose: true,
    skipSchemaUpdate: false,
  };

  const migrator = new ClickHouseMigrator(config);

  console.log('Applying migrations...');
  await migrator.up();
  console.log('Migrations applied successfully.');

  // Example of generating a new migration (typically done via CLI)
  // await migrator.generate('create_users_and_products_tables');

  // Example of rolling back the last migration
  // console.log('Rolling back last migration...');
  // await migrator.down();
  // console.log('Last migration rolled back.');
}

runMigrations().catch(error => {
  console.error('Migration failed:', error);
  process.exit(1);
});