@fjall/clickhouse-migrations 0.99.1

package/LICENSE

@@ -0,0 +1,50 @@
+Fjall Proprietary Software Licence
+
+Copyright (c) 2026 Fjall. All rights reserved.
+
+This software, including all source, object, bundled, and minified forms
+("the Software"), is the proprietary and confidential property of Fjall.
+
+1. Permitted Use. Subject to the terms of this Licence, Fjall grants you
+   a non-exclusive, non-transferable, revocable licence to install the
+   Software via the npm registry and to execute it solely for the purpose
+   of deploying, operating, and managing your own applications and
+   infrastructure on cloud providers.
+
+2. Restrictions. You may NOT, and may not permit any third party to:
+   (a) copy, redistribute, sublicense, sell, rent, lease, or otherwise
+       transfer the Software;
+   (b) modify, adapt, translate, or create derivative works of the Software;
+   (c) reverse engineer, decompile, disassemble, deminify, or otherwise
+       attempt to derive the source code, structure, or organisation of
+       the Software, except to the minimum extent expressly permitted by
+       applicable mandatory law;
+   (d) use the Software, or any portion of it, to develop, train, or
+       improve any product or service that competes with Fjall;
+   (e) remove, alter, or obscure any proprietary notices contained in
+       the Software;
+   (f) publish, share, or otherwise disclose the Software or its contents
+       to any third party.
+
+3. Ownership. All right, title, and interest in and to the Software,
+   including all intellectual property rights, remain with Fjall. No
+   rights are granted except as expressly set out in this Licence.
+
+4. Termination. This Licence terminates automatically if you breach any
+   of its terms. Upon termination you must cease all use of the Software
+   and destroy all copies in your possession.
+
+5. Disclaimer of Warranty. THE SOFTWARE IS PROVIDED "AS IS" WITHOUT
+   WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION
+   THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+   AND NON-INFRINGEMENT.
+
+6. Limitation of Liability. IN NO EVENT SHALL FJALL BE LIABLE FOR ANY
+   INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES
+   ARISING OUT OF OR RELATED TO THE SOFTWARE, EVEN IF ADVISED OF THE
+   POSSIBILITY OF SUCH DAMAGES.
+
+7. Governing Law. This Licence is governed by the laws of England and
+   Wales, without regard to conflict of laws principles.
+
+For commercial licensing enquiries, contact: contact@fjall.io

package/README.md

@@ -0,0 +1,69 @@
+# @fjall/clickhouse-migrations
+
+Runtime helpers for ClickHouse migration containers. Consumes the user manifest published by `@fjall/components-infrastructure` `ClickHouseDatabase` and provisions workload users in writable `users_local` storage. Also ships a generic SQL-file runner and a connection-retry helper.
+
+## Installation
+
+```bash
+npm install @fjall/clickhouse-migrations @clickhouse/client
+```
+
+`@clickhouse/client` is a peer dependency — the consumer supplies the runtime client.
+
+## Env-var contract
+
+The framework's commitment is the env-var shape, not this package's API. A customer rolling their own consumer reads the same env vars.
+
+| Env var                         | Shape                              | Producer                                                  |
+| ------------------------------- | ---------------------------------- | --------------------------------------------------------- |
+| `CLICKHOUSE_SQL_USERS_MANIFEST` | JSON `Array<{ name, profile }>`    | `ClickHouseDatabase.getMigrationContributions()`          |
+| `USER_<NAME>_PASSWORD`          | plaintext (one per manifest entry) | ECS executionRole + Secrets Manager (no runtime SDK call) |
+
+The constant name + env-name helper live in `@fjall/util/migration`:
+
+```typescript
+import {
+  CLICKHOUSE_SQL_USERS_MANIFEST_ENV,
+  SqlUsersManifestSchema,
+  userPasswordEnvName,
+} from "@fjall/util/migration";
+```
+
+This package re-exports them for convenience so consumers don't need two imports.
+
+## Usage
+
+```typescript
+import {
+  connectWithRetry,
+  createConsoleMigrationLogger,
+  provisionUsersFromEnv,
+  runSqlMigrations,
+} from "@fjall/clickhouse-migrations";
+import { createClient } from "@clickhouse/client";
+
+const logger = createConsoleMigrationLogger("migration-runner");
+const client = createClient({ url, username, password, database });
+
+await connectWithRetry(client, { label: "user-provision", logger });
+await provisionUsersFromEnv({ client, logger });
+await runSqlMigrations({ client, dir: "./clickhouse-init", logger });
+```
+
+`provisionUsersFromEnv` is idempotent — it issues `CREATE USER IF NOT EXISTS` then `ALTER USER` for every manifest entry, so repeated invocations are safe.
+
+## Rolling your own consumer
+
+The env-var contract above is stable. A customer who prefers their own provisioner reads the same env vars; this package's helpers are convenience wrappers. The framework commits to the env shape, not to this package.
+
+If rolling your own, you'll want to replicate:
+
+- single-quote-escape the password literal (`'` → `''`) before string-interpolating into `IDENTIFIED WITH … BY '…'`
+- mask passwords in any log output (use `maskSensitiveOutput` from `@fjall/util`)
+- order `CREATE USER IF NOT EXISTS` before `ALTER USER` so re-provisioning realigns drifted credentials
+- place provisioning BEFORE any migration-hash idempotency gate
+- regex-validate user names before string-interpolating into SQL (CH doesn't bind identifier parameters)
+
+## Licence
+
+Proprietary — see [LICENSE](./LICENSE).

package/dist/.minified

@@ -0,0 +1 @@
+8 files minified at 2026-05-22T01:26:14.923Z

package/dist/connectWithRetry.d.ts

@@ -0,0 +1,9 @@
+import type { ClickHouseClient } from "@clickhouse/client";
+import type { MigrationLogger } from "./logger.js";
+export interface ConnectWithRetryOpts {
+    label: string;
+    signal?: AbortSignal;
+    delays?: readonly number[];
+    logger?: MigrationLogger;
+}
+export declare function connectWithRetry(client: ClickHouseClient, opts: ConnectWithRetryOpts): Promise<void>;

package/dist/connectWithRetry.js

@@ -0,0 +1 @@
+import{getErrorMessage as f,maskSensitiveOutput as _}from"@fjall/util";import{sleepAbortable as g}from"./sleepAbortable.js";const p=[5e3,1e4,2e4,4e4,6e4],y=3,h=516,m=["ECONNREFUSED","ETIMEDOUT","ENOTFOUND"];async function u(E,a){const{label:n,signal:c,logger:i}=a,r=a.delays??p;let s;for(let t=0;t<r.length;t++){if(c?.aborted)throw new Error(`connectWithRetry: ${n} aborted by signal before attempt ${t+1}`);try{await E.ping(),t>0&&i?.info("connect succeeded after retry",{label:n,attempt:t+1});return}catch(e){s=e;const o=typeof e=="object"&&e!==null&&"code"in e?e.code:void 0,l=o===h;if(!(typeof o=="string"&&m.includes(o)||l&&t<y))throw e;i?.warn("connect attempt failed; retrying",{label:n,attempt:t+1,attempts:r.length,delayMs:r[t],code:l?"AUTH_FAILED":o??""}),await g(r[t],c)}}const d=_(f(s));throw new Error(`connectWithRetry: ${n} failed after ${r.length} attempts: ${d}`)}export{u as connectWithRetry};

package/dist/constants.d.ts

@@ -0,0 +1 @@
+export { CLICKHOUSE_MANAGED_USERS_ENV, userPasswordEnvName, } from "@fjall/util/migration";

package/dist/constants.js

@@ -0,0 +1 @@
+import{CLICKHOUSE_MANAGED_USERS_ENV as e,userPasswordEnvName as o}from"@fjall/util/migration";export{e as CLICKHOUSE_MANAGED_USERS_ENV,o as userPasswordEnvName};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { CLICKHOUSE_MANAGED_USERS_ENV, userPasswordEnvName, } from "./constants.js";
+export { ManagedUserNameSchema, ManagedUserNamesSchema, type ManagedUserName, type ManagedUserNames, } from "./schemas.js";
+export { type MigrationLogger, createConsoleMigrationLogger, } from "./logger.js";
+export { type ConnectWithRetryOpts, connectWithRetry, } from "./connectWithRetry.js";
+export { type ProvisionUsersFromEnvOpts, type ProvisionUsersFromEnvResult, provisionUsersFromEnv, } from "./provisionUsers.js";
+export { type RunSqlMigrationsOpts, type RunSqlMigrationsResult, runSqlMigrations, } from "./runSqlMigrations.js";

package/dist/index.js

@@ -0,0 +1 @@
+import{CLICKHOUSE_MANAGED_USERS_ENV as o,userPasswordEnvName as a}from"./constants.js";import{ManagedUserNameSchema as t,ManagedUserNamesSchema as n}from"./schemas.js";import{createConsoleMigrationLogger as i}from"./logger.js";import{connectWithRetry as f}from"./connectWithRetry.js";import{provisionUsersFromEnv as x}from"./provisionUsers.js";import{runSqlMigrations as S}from"./runSqlMigrations.js";export{o as CLICKHOUSE_MANAGED_USERS_ENV,t as ManagedUserNameSchema,n as ManagedUserNamesSchema,f as connectWithRetry,i as createConsoleMigrationLogger,x as provisionUsersFromEnv,S as runSqlMigrations,a as userPasswordEnvName};

package/dist/logger.d.ts

@@ -0,0 +1,5 @@
+export interface MigrationLogger {
+    info(msg: string, ctx?: Record<string, unknown>): void;
+    warn(msg: string, ctx?: Record<string, unknown>): void;
+}
+export declare function createConsoleMigrationLogger(namespace: string): MigrationLogger;

package/dist/logger.js

@@ -0,0 +1,3 @@
+function r(n){return{info(t,e){process.stdout.write(JSON.stringify({level:"info",namespace:n,msg:t,ctx:e??{},ts:new Date().toISOString()})+`
+`)},warn(t,e){process.stdout.write(JSON.stringify({level:"warn",namespace:n,msg:t,ctx:e??{},ts:new Date().toISOString()})+`
+`)}}}export{r as createConsoleMigrationLogger};

package/dist/provisionUsers.d.ts

@@ -0,0 +1,12 @@
+import type { ClickHouseClient } from "@clickhouse/client";
+import type { MigrationLogger } from "./logger.js";
+export interface ProvisionUsersFromEnvOpts {
+    client: ClickHouseClient;
+    signal?: AbortSignal;
+    logger?: MigrationLogger;
+    env?: NodeJS.ProcessEnv;
+}
+export interface ProvisionUsersFromEnvResult {
+    provisioned: readonly string[];
+}
+export declare function provisionUsersFromEnv(opts: ProvisionUsersFromEnvOpts): Promise<ProvisionUsersFromEnvResult>;

package/dist/provisionUsers.js

@@ -0,0 +1 @@
+import{CLICKHOUSE_MANAGED_USERS_ENV as i,userPasswordEnvName as S}from"./constants.js";import{ManagedUserNamesSchema as g}from"./schemas.js";const v=/^[a-z][a-z0-9_]*$/;function h(r){return r.replace(/'/g,"''")}async function I(r){const{client:t,signal:u,logger:s}=r,m=r.env??process.env,o=m[i];if(o===void 0||o==="")return s?.info("no managed users to provision (manifest env absent)",{}),{provisioned:[]};let c;try{c=JSON.parse(o)}catch(e){throw new Error(`provisionUsersFromEnv: malformed ${i} \u2014 JSON parse failed`,{cause:e})}const n=g.safeParse(c);if(!n.success)throw new Error(`provisionUsersFromEnv: malformed ${i} \u2014 ${n.error.message}`);const p=n.data;if(p.length===0)return s?.info("no managed users to provision (manifest empty)",{}),{provisioned:[]};const E=[];for(const e of p){if(u?.aborted)throw new Error(`provisionUsersFromEnv: aborted by signal before user '${e}'`);if(!v.test(e))throw new Error(`provisionUsersFromEnv: user name '${e}' violates name pattern ${v.source}`);const d=S(e),a=m[d];if(a===void 0||a==="")throw new Error(`provisionUsersFromEnv: required env ${d} is missing or empty`);const f=h(a),l=`CREATE USER IF NOT EXISTS ${e} IDENTIFIED WITH sha256_password BY '${f}'`,w=`ALTER USER ${e} IDENTIFIED WITH sha256_password BY '${f}'`;await t.command({query:l}),await t.command({query:w}),s?.info("clickhouse user provisioned",{name:e}),E.push(e)}return{provisioned:E}}export{I as provisionUsersFromEnv};

package/dist/runSqlMigrations.d.ts

@@ -0,0 +1,13 @@
+import type { ClickHouseClient } from "@clickhouse/client";
+import type { MigrationLogger } from "./logger.js";
+export interface RunSqlMigrationsOpts {
+    client: ClickHouseClient;
+    dir: string;
+    skipFilesMatching?: RegExp;
+    signal?: AbortSignal;
+    logger?: MigrationLogger;
+}
+export interface RunSqlMigrationsResult {
+    applied: readonly string[];
+}
+export declare function runSqlMigrations(opts: RunSqlMigrationsOpts): Promise<RunSqlMigrationsResult>;

package/dist/runSqlMigrations.js

@@ -0,0 +1 @@
+import{readFileSync as h,readdirSync as E}from"node:fs";import{join as q}from"node:path";import{getErrorMessage as w,maskSensitiveOutput as M}from"@fjall/util";const S=/\.dev\.sql$/,n=400;async function A(e){const{client:a,dir:o,signal:l,logger:c}=e,g=e.skipFilesMatching??S,f=E(o).filter(t=>t.endsWith(".sql")).filter(t=>!g.test(t)).sort(),s=[];for(const t of f){if(l?.aborted)throw new Error(`runSqlMigrations: aborted by signal before applying '${t}'`);const d=q(o,t),p=h(d,"utf8");try{await a.command({query:p})}catch(i){const u=w(i).replace(/'(?:[^']|'')*'/g,"'<REDACTED>'"),r=M(u),m=r.length>n?r.slice(0,n)+"\u2026":r;throw new Error(`runSqlMigrations: ${t}: ${m}`,{cause:i})}c?.info("sql migration applied",{file:t}),s.push(t)}return{applied:s}}export{A as runSqlMigrations};

package/dist/schemas.d.ts

@@ -0,0 +1 @@
+export { ManagedUserNameSchema, ManagedUserNamesSchema, type ManagedUserName, type ManagedUserNames, } from "@fjall/util/migration";

package/dist/schemas.js

@@ -0,0 +1 @@
+import{ManagedUserNameSchema as m,ManagedUserNamesSchema as r}from"@fjall/util/migration";export{m as ManagedUserNameSchema,r as ManagedUserNamesSchema};

package/dist/sleepAbortable.d.ts

@@ -0,0 +1 @@
+export declare function sleepAbortable(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/sleepAbortable.js

@@ -0,0 +1 @@
+function b(o,e){return e?.aborted?Promise.resolve():new Promise(r=>{const t=()=>{clearTimeout(n),e?.removeEventListener("abort",t),r()},n=setTimeout(()=>{e?.removeEventListener("abort",t),r()},o);e?.addEventListener("abort",t,{once:!0})})}export{b as sleepAbortable};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@fjall/clickhouse-migrations",
+  "version": "0.99.1",
+  "description": "Runtime helpers for ClickHouse migration containers — user provisioning, SQL file application, connection retry. Consumes the manifest contract published by @fjall/components-infrastructure ClickHouseDatabase.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "clean": "rm -rf ./dist ./sourcemaps",
+    "clean:node": "rm -rf ./node_modules",
+    "build": "npm run clean && npx tsc && node ../scripts/minify-dist.mjs dist",
+    "watch": "npm run build && npx tsc-watch",
+    "watch:only": "npx tsc-watch",
+    "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx,js,jsx,json}\"",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "test": "vitest run",
+    "typecheck": "npx tsc --noEmit"
+  },
+  "author": "",
+  "license": "SEE LICENSE IN LICENSE",
+  "devDependencies": {
+    "@clickhouse/client": "^1.18.0",
+    "@types/node": "^25.6.0",
+    "prettier": "^3.8.3",
+    "tsc-watch": "^7.2.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "peerDependencies": {
+    "@clickhouse/client": "^1.18.0"
+  },
+  "dependencies": {
+    "@fjall/util": "^0.99.1",
+    "zod": "^4.4.3"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "gitHead": "0b8cc9b7c5017ca126c884da4cb29793dd26c96a"
+}