clickhouse-migrations 1.5.1 → 1.6.0

package/README.md

@@ -1,6 +1,6 @@
 # clickhouse-migrations
 
-> ClickHouse Migrations CLI
+> ClickHouse Migrations CLI and library
 
 ## Install
 
@@ -153,6 +153,59 @@ LAYOUT(COMPLEX_KEY_HASHED());
 
 _Please note:_ When substitution is enabled, the checksum is taken from the **raw file**, before substitution. This keeps a migration stable across environments and keeps secrets out of `_migrations`. Two consequences follow: an already-applied migration is not re-run when a variable changes (ship a new migration instead), and the substituted SQL still reaches ClickHouse, so it may appear in `system.query_log` or server logs.
 
+## Use as a library
+
+Import `migration` and pass an options object. Named options let you set a timeout or an engine without filling in unused arguments.
+
+```typescript
+import { migration, type MigrationOptions } from 'clickhouse-migrations';
+
+const options: MigrationOptions = {
+  migrations_home: './migrations',
+  host: 'http://localhost:8123',
+  username: 'default',
+  password: '',
+  db_name: 'analytics',
+  timeout: '60000',
+};
+
+await migration(options);
+```
+
+For CommonJS, use `const { migration } = require('clickhouse-migrations')` and call it from an async function.
+
+Possible function parameters:
+
+| Option | Type | Required | Description |
+| --- | --- | --- | --- |
+| `migrations_home` | `string` | Yes | Directory containing the SQL files, relative to the working directory or absolute. |
+| `host` | `string` | Yes | ClickHouse HTTP or HTTPS URL, including the port. |
+| `username` | `string` | Yes | ClickHouse username. |
+| `password` | `string` | Yes | Use `''` for an empty password. |
+| `db_name` | `string` | Yes | Target database. Created if it does not exist, unless `skip_db_creation` is enabled. |
+| `db_engine` | `string` | No | Optional `ON CLUSTER` and/or `ENGINE` clauses for database creation. If omitted, ClickHouse chooses its default engine. |
+| `table_engine` | `string` | No | Engine for the `_migrations` table. Defaults to `MergeTree`. |
+| `timeout` | `string` | No | Request timeout in milliseconds, for example `'60000'`. Defaults to the client's `30000` ms. |
+| `ca_cert` | `string` | No | Path to a CA certificate file for TLS. |
+| `cert` | `string` | No | Path to a client certificate. Use with `ca_cert` and `key`. |
+| `key` | `string` | No | Path to the client private key. Use with `ca_cert` and `cert`. |
+| `skip_db_creation` | `boolean` | No | Defaults to `false`. When `true`, checks that the database exists without trying to create it. |
+
+Connection options come from the object. The CLI's `CH_MIGRATIONS_*` connection variables are not read by `migration()`. [Environment variable substitution](#environment-variable-substitution-optional) in SQL files uses `CH_MIGRATIONS_SUBSTITUTE_ENV` for both the library and the CLI.
+
+`migration(options)` logs progress to the console and returns a `Promise<void>` that resolves after migrations finish successfully and connections are closed. If a migration fails, it attempts to close its connections and rejects with an error your application can catch. It does not exit the process. A cleanup failure does not replace the original migration error, and underlying client or SQL parsing errors are available through `error.cause`. The CLI and deprecated positional form also attempt cleanup, but then log the error and exit with status `1`.
+
+```typescript
+try {
+  await migration(options);
+} catch (error) {
+  console.error('Migration failed:', error);
+  // Decide whether to retry, stop startup, or shut down your application.
+}
+```
+
+**Note:** The previously undocumented positional form of `migration()` is deprecated and will be removed in a future major release. If you use it, switch to the options object shown above.
+
 ## SQL execution and settings
 
 Queries execute in file order. Assignment-style `SET name = value` statements are collected before executing the file: the last assignment to each setting applies to **every query in that file**, including queries written before the `SET`. This preserves the package's existing behavior. Settings do not carry over to the next migration file.

package/lib/migrate.d.ts

@@ -1,3 +1,35 @@
-declare const migration: (migrations_home: string, host: string, username: string, password: string, db_name: string, db_engine?: string, table_engine?: string, timeout?: string, ca_cert?: string | undefined, cert?: string | undefined, key?: string | undefined, skip_db_creation?: boolean) => Promise<void>;
+/** Options object for applying migrations. */
+export interface MigrationOptions {
+    migrations_home: string;
+    host: string;
+    username: string;
+    password: string;
+    db_name: string;
+    db_engine?: string;
+    table_engine?: string;
+    timeout?: string;
+    ca_cert?: string;
+    cert?: string;
+    key?: string;
+    skip_db_creation?: boolean;
+}
+type LegacyMigrationArguments = [
+    migrations_home: string,
+    host: string,
+    username: string,
+    password: string,
+    db_name: string,
+    db_engine?: string,
+    table_engine?: string,
+    timeout?: string,
+    ca_cert?: string,
+    cert?: string,
+    key?: string,
+    skip_db_creation?: boolean
+];
+/** Apply migrations, rejecting on failure without exiting the process. */
+declare function migration(options: MigrationOptions): Promise<void>;
+/** @deprecated Use migration(options). Positional calls log failures and exit with status 1. */
+declare function migration(...args: LegacyMigrationArguments): Promise<void>;
 declare const migrate: () => void;
 export { migrate, migration };

package/lib/migrate.js

@@ -3,7 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.migration = exports.migrate = void 0;
+exports.migrate = void 0;
+exports.migration = migration;
 const client_1 = require("@clickhouse/client");
 const commander_1 = require("commander");
 const fs_1 = __importDefault(require("fs"));
@@ -47,8 +48,7 @@ const connect = (url, username, password, db_name, timeout, ca_cert, cert, key)
             }
         }
         catch (e) {
-            log('error', 'Failed to read CA certificate file for TLS connection.', e instanceof Error ? e.message : String(e));
-            process.exit(1);
+            throw new Error('Failed to read CA certificate file for TLS connection.', { cause: e });
         }
     }
     return (0, client_1.createClient)(db_params);
@@ -57,52 +57,53 @@ const create_db = async (host, username, password, db_name, db_engine, timeout,
     // Don't specify database name when creating it - connect to default database
     const client = connect(host, username, password, undefined, timeout, ca_cert, cert, key);
     try {
-        await client.ping();
-    }
-    catch (e) {
-        log('error', `Failed to connect to ClickHouse`, e.message);
-        process.exit(1);
-    }
-    if (skip_db_creation) {
-        // Database creation is disabled - verify the database already exists.
-        let exists = false;
         try {
-            const resultSet = await client.query({
-                query: `SELECT 1 AS ok FROM system.databases WHERE name = {db_name:String}`,
-                query_params: { db_name },
-                format: 'JSONEachRow',
-            });
-            const rows = (await resultSet.json());
-            exists = rows.length > 0;
+            await client.ping();
         }
         catch (e) {
-            log('error', `can't verify that the database ${db_name} exists.`, e.message);
-            await client.close();
-            process.exit(1);
+            throw new Error(`Failed to connect to ClickHouse`, { cause: e });
         }
-        if (!exists) {
-            log('error', `the database ${db_name} doesn't exist and --skip-db-creation is set. Please create the database manually or remove --skip-db-creation.`);
-            await client.close();
-            process.exit(1);
+        if (skip_db_creation) {
+            // Database creation is disabled - verify the database already exists.
+            let exists = false;
+            try {
+                const resultSet = await client.query({
+                    query: `SELECT 1 AS ok FROM system.databases WHERE name = {db_name:String}`,
+                    query_params: { db_name },
+                    format: 'JSONEachRow',
+                });
+                const rows = (await resultSet.json());
+                exists = rows.length > 0;
+            }
+            catch (e) {
+                throw new Error(`can't verify that the database ${db_name} exists.`, { cause: e });
+            }
+            if (!exists) {
+                throw new Error(`the database ${db_name} doesn't exist and --skip-db-creation is set. Please create the database manually or remove --skip-db-creation.`);
+            }
+        }
+        else {
+            // In open source ClickHouse - default DB engine is "Atomic", for Cloud - "Shared". If not set, appropriate default is used.
+            const q = db_engine
+                ? `CREATE DATABASE IF NOT EXISTS "${db_name}" ${db_engine}`
+                : `CREATE DATABASE IF NOT EXISTS "${db_name}"`;
+            try {
+                await client.command({
+                    query: q,
+                    clickhouse_settings: {
+                        wait_end_of_query: 1,
+                    },
+                });
+            }
+            catch (e) {
+                throw new Error(`can't create the database ${db_name}.`, { cause: e });
+            }
         }
-        await client.close();
-        return;
-    }
-    // In open source ClickHouse - default DB engine is "Atomic", for Cloud - "Shared". If not set, appropriate default is used.
-    const q = db_engine
-        ? `CREATE DATABASE IF NOT EXISTS "${db_name}" ${db_engine}`
-        : `CREATE DATABASE IF NOT EXISTS "${db_name}"`;
-    try {
-        await client.command({
-            query: q,
-            clickhouse_settings: {
-                wait_end_of_query: 1,
-            },
-        });
     }
-    catch (e) {
-        log('error', `can't create the database ${db_name}.`, e.message);
-        process.exit(1);
+    catch (error) {
+        // Preserve the original failure if closing the connection also fails.
+        await client.close().catch(() => undefined);
+        throw error;
     }
     await client.close();
 };
@@ -125,8 +126,7 @@ const init_migration_table = async (client, table_engine = 'MergeTree') => {
         });
     }
     catch (e) {
-        log('error', `can't create the _migrations table.`, e.message);
-        process.exit(1);
+        throw new Error(`can't create the _migrations table.`, { cause: e });
     }
 };
 const get_migrations = (migrations_home) => {
@@ -134,9 +134,8 @@ const get_migrations = (migrations_home) => {
     try {
         files = fs_1.default.readdirSync(migrations_home);
     }
-    catch (e) {
-        log('error', `no migration directory ${migrations_home}. Please create it.`);
-        process.exit(1);
+    catch {
+        throw new Error(`no migration directory ${migrations_home}. Please create it.`);
     }
     const migrations = [];
     files.forEach((file) => {
@@ -146,8 +145,7 @@ const get_migrations = (migrations_home) => {
         }
         const version = Number(file.split('_')[0]);
         if (!version) {
-            log('error', `a migration name should start from number, example: 1_init.sql. Please check, if the migration ${file} is named correctly`);
-            process.exit(1);
+            throw new Error(`a migration name should start from number, example: 1_init.sql. Please check, if the migration ${file} is named correctly`);
         }
         migrations.push({
             version,
@@ -162,7 +160,7 @@ const get_migrations = (migrations_home) => {
     return migrations;
 };
 const apply_migrations = async (client, migrations, migrations_home) => {
-    let migration_query_result = [];
+    let migration_query_result;
     try {
         const resultSet = await client.query({
             query: `SELECT version, checksum, migration_name FROM _migrations ORDER BY version`,
@@ -171,8 +169,7 @@ const apply_migrations = async (client, migrations, migrations_home) => {
         migration_query_result = await resultSet.json();
     }
     catch (e) {
-        log('error', `can't select data from the _migrations table.`, e.message);
-        process.exit(1);
+        throw new Error(`can't select data from the _migrations table.`, { cause: e });
     }
     const migrations_applied = [];
     migration_query_result.forEach((row) => {
@@ -184,8 +181,7 @@ const apply_migrations = async (client, migrations, migrations_home) => {
         // Check if migration file was not removed after apply.
         const migration_exist = migrations.find(({ version }) => version === row.version);
         if (!migration_exist) {
-            log('error', `a migration file shouldn't be removed after apply. Please, restore the migration ${row.migration_name}.`);
-            process.exit(1);
+            throw new Error(`a migration file shouldn't be removed after apply. Please, restore the migration ${row.migration_name}.`);
         }
     });
     let applied_migrations = '';
@@ -195,8 +191,7 @@ const apply_migrations = async (client, migrations, migrations_home) => {
         if (migrations_applied[migration.version]) {
             // Check if migration file was not changed after apply.
             if (migrations_applied[migration.version].checksum !== checksum) {
-                log('error', `a migration file should't be changed after apply. Please, restore content of the ${migrations_applied[migration.version].migration_name} migrations.`);
-                process.exit(1);
+                throw new Error(`a migration file should't be changed after apply. Please, restore content of the ${migrations_applied[migration.version].migration_name} migrations.`);
             }
             // Skip if a migration is already applied.
             continue;
@@ -209,8 +204,7 @@ const apply_migrations = async (client, migrations, migrations_home) => {
             ({ queries, settings } = (0, sql_parse_1.parse_migration_sql)((0, sql_parse_1.substitute_env)(content)));
         }
         catch (e) {
-            log('error', `the migration ${migration.file} has an error.`, e instanceof Error ? e.message : String(e));
-            process.exit(1);
+            throw new Error(`the migration ${migration.file} has an error.`, { cause: e });
         }
         // Keep the established file-wide SET behavior: the last assignment wins,
         // including for queries earlier in the file. Send settings on every request
@@ -228,8 +222,7 @@ const apply_migrations = async (client, migrations, migrations_home) => {
                 if (applied_migrations) {
                     log('info', `The migration(s) ${applied_migrations} was successfully applied!`);
                 }
-                log('error', `the migrations ${migration.file} has an error. Please, fix it (be sure that already executed parts of the migration would not be run second time) and re-run migration script.`, e.message);
-                process.exit(1);
+                throw new Error(`the migrations ${migration.file} has an error. Please, fix it (be sure that already executed parts of the migration would not be run second time) and re-run migration script.`, { cause: e });
             }
         }
         try {
@@ -240,8 +233,7 @@ const apply_migrations = async (client, migrations, migrations_home) => {
             });
         }
         catch (e) {
-            log('error', `can't insert a data into the table _migrations.`, e.message);
-            process.exit(1);
+            throw new Error(`can't insert a data into the table _migrations.`, { cause: e });
         }
         applied_migrations = applied_migrations ? applied_migrations + ', ' + migration.file : migration.file;
     }
@@ -252,15 +244,54 @@ const apply_migrations = async (client, migrations, migrations_home) => {
         log('info', `No migrations to apply.`);
     }
 };
-const migration = async (migrations_home, host, username, password, db_name, db_engine, table_engine, timeout, ca_cert, cert, key, skip_db_creation) => {
+const run_migration = async ({ migrations_home, host, username, password, db_name, db_engine, table_engine, timeout, ca_cert, cert, key, skip_db_creation, }) => {
     const migrations = get_migrations(migrations_home);
     await create_db(host, username, password, db_name, db_engine, timeout, ca_cert, cert, key, skip_db_creation);
     const client = connect(host, username, password, db_name, timeout, ca_cert, cert, key);
-    await init_migration_table(client, table_engine);
-    await apply_migrations(client, migrations, migrations_home);
+    try {
+        await init_migration_table(client, table_engine);
+        await apply_migrations(client, migrations, migrations_home);
+    }
+    catch (error) {
+        await client.close().catch(() => undefined);
+        throw error;
+    }
     await client.close();
 };
-exports.migration = migration;
+async function migration(...args) {
+    if (typeof args[0] !== 'string') {
+        // If the first argument is not a string, assume it's the new options object.
+        return run_migration(args[0]);
+    }
+    // Keep using legacy positional arguments for backward compatibility.
+    const [migrations_home, host, username, password, db_name, db_engine, table_engine, timeout, ca_cert, cert, key, skip_db_creation,] = args;
+    try {
+        await run_migration({
+            migrations_home,
+            host,
+            username,
+            password,
+            db_name,
+            db_engine,
+            table_engine,
+            timeout,
+            ca_cert,
+            cert,
+            key,
+            skip_db_creation,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const cause = error instanceof Error ? error.cause : undefined;
+        let detail;
+        if (cause !== undefined) {
+            detail = cause instanceof Error ? cause.message : String(cause);
+        }
+        log('error', message, detail);
+        process.exit(1);
+    }
+}
 const migrate = () => {
     const program = new commander_1.Command();
     program.name('clickhouse-migrations').description('ClickHouse migrations.').version(version_1.VERSION);
@@ -280,7 +311,32 @@ const migrate = () => {
         .option('--key <path>', 'Client key file path', process.env.CH_MIGRATIONS_KEY)
         .option('--skip-db-creation', 'Skip database creation', process.env.CH_MIGRATIONS_SKIP_DB_CREATION === 'true')
         .action(async (options) => {
-        await migration(options.migrationsHome, options.host, options.user, options.password, options.db, options.dbEngine, options.tableEngine, options.timeout, options.caCert, options.cert, options.key, options.skipDbCreation);
+        try {
+            await run_migration({
+                migrations_home: options.migrationsHome,
+                host: options.host,
+                username: options.user,
+                password: options.password,
+                db_name: options.db,
+                db_engine: options.dbEngine,
+                table_engine: options.tableEngine,
+                timeout: options.timeout,
+                ca_cert: options.caCert,
+                cert: options.cert,
+                key: options.key,
+                skip_db_creation: options.skipDbCreation,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const cause = error instanceof Error ? error.cause : undefined;
+            let detail;
+            if (cause !== undefined) {
+                detail = cause instanceof Error ? cause.message : String(cause);
+            }
+            log('error', message, detail);
+            process.exit(1);
+        }
     });
     program.parse();
 };

package/lib/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.5.1";
+export declare const VERSION = "1.6.0";

package/lib/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '1.5.1'; // x-release-please-version
+exports.VERSION = '1.6.0'; // x-release-please-version

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clickhouse-migrations",
-  "version": "1.5.1",
-  "description": "ClickHouse Migrations",
+  "version": "1.6.0",
+  "description": "ClickHouse Migrations CLI and library.",
   "bin": {
     "clickhouse-migrations": "lib/cli.js"
   },