@fjall/clickhouse 20.0.0 → 21.0.0

package/dist/.build-source-hash

@@ -9,22 +9,27 @@
     "package.json",
     "tsconfig.json"
   ],
-  "hash": "fed8b5f23e405cd72b8ffac8e6bbb7366aeec50b549ff7ed01033e4ed1668691",
+  "hash": "a7b1cae6ae0602be76a77f22cd3aaeb4c2f54db3b7fa6075c6c71824d9248d27",
   "files": {
-    "src/connectWithRetry.ts": "eb4d131ea8e81922",
-    "src/constants.ts": "00b236fd35f098cb",
+    "src/awaitControlPlaneIdle.ts": "055a56eaeb34e080",
+    "src/classifyClickHouseError.ts": "aab06571cf2b7ae3",
+    "src/connectWithRetry.ts": "61d241f2e4114134",
+    "src/constants.ts": "8d7fc4f3f97d5777",
     "src/createClient.ts": "83f093bfd7765a9f",
-    "src/index.ts": "2ab0816e1d411108",
+    "src/ensureUserWithPassword.ts": "ee9ad7e1a22a9c50",
+    "src/index.ts": "ec05b861e901baf8",
     "src/logger.ts": "659d04c534247903",
-    "src/provisionUsers.ts": "3e88d53b5eb1ccf5",
-    "src/runSqlMigrations.ts": "d187aa5de9e4316e",
-    "src/schemas.ts": "f3be95e003bd7e6e",
-    "src/sleepAbortable.ts": "0286a0719bef3a38",
-    "src/verifyExpectedClickHouseSchemaVersion.ts": "84f5463cd47e4a30",
+    "src/maskSqlError.ts": "1747db71f13ea3ea",
+    "src/provisionFrameworkUsers.ts": "781feeb539c4f92d",
+    "src/provisionUsers.ts": "c627778679ebb2a2",
+    "src/runSqlMigrations.ts": "e71fcef12eefb3fc",
+    "src/schemas.ts": "0567f2d427d55707",
+    "src/sleepAbortable.ts": "ee2facc7b89ab9f5",
+    "src/verifyExpectedClickHouseSchemaVersion.ts": "d202d40c76ba8ad6",
     "../scripts/minify-dist.mjs": "6b2e4b0df8aec601",
-    "package.json": "bb5effb75c412d2e",
+    "package.json": "e0f1cc4b1a798f0b",
     "tsconfig.json": "db759831ad95f396"
   },
-  "outputHash": "aca383c4bebdbc651b13cf6955b9b4c1943eeb59eecfd82e777d11aa3c143c93",
-  "outputFileCount": 21
+  "outputHash": "b109dab9cb0f44e0e44420c4197505d972e8afb628941b5c54690e3a5dd29622",
+  "outputFileCount": 31
 }

package/dist/.minified

@@ -1 +1 @@
-10 files minified at 2026-08-24T18:04:51.057Z
+15 files minified at 2026-08-26T08:32:32.000Z

package/dist/awaitControlPlaneIdle.d.ts

@@ -0,0 +1,42 @@
+import type { ClickHouseClient } from "@clickhouse/client";
+import type { MigrationLogger } from "./logger.js";
+export interface AwaitControlPlaneIdleOpts {
+    client: ClickHouseClient;
+    /** The OTHER side of the mutex — never the caller's own identity. */
+    users: readonly string[];
+    /** Total wait budget. Exceeding it returns `timeout`; it never throws. */
+    timeoutMs: number;
+    /** Interval between probes. Defaults to 5000. */
+    pollMs?: number;
+    /** Overrides `CONTROL_PLANE_ACTIVITY_RECENCY_SECONDS`. */
+    recencySeconds?: number;
+    signal?: AbortSignal;
+    logger?: MigrationLogger;
+}
+export type ControlPlaneIdleResult = {
+    outcome: "idle";
+} | {
+    outcome: "timeout";
+    waitedMs: number;
+} | {
+    outcome: "aborted";
+};
+/**
+ * Waits for the other control-plane identities to go idle — the migration
+ * runner calls this as the schema admin with `users: [FJALL_MAINTENANCE_USER]`
+ * before its ClickHouse phase (the maintenance sidecars run the same SQL the
+ * other way round, in sh). Polls `buildControlPlaneActivityQuery` until it
+ * reports `active = 0`.
+ *
+ * Returns rather than throws on `timeout` and `aborted`: the runner owns the
+ * verdict, and it fails closed on `timeout` (a still-busy maintenance
+ * identity means an OPTIMIZE or BACKUP is holding the server). A probe that
+ * cannot be read is NOT proof of idleness — `busy` / `unreachable` /
+ * `indeterminate` probe errors are logged and polling continues inside the
+ * budget — including the `Code: 60` a brand-new server returns until its
+ * first log flush creates `system.query_log` (verified on 26.3; the probe's
+ * own queries create it inside one flush interval). A `denied` probe throws
+ * immediately: no amount of waiting grants `SELECT ON system.processes` /
+ * `system.query_log`.
+ */
+export declare function awaitControlPlaneIdle(opts: AwaitControlPlaneIdleOpts): Promise<ControlPlaneIdleResult>;

package/dist/awaitControlPlaneIdle.js

@@ -0,0 +1 @@
+var w=Object.defineProperty;var l=(e,s)=>w(e,"name",{value:s,configurable:!0});import{buildControlPlaneActivityQuery as y}from"@fjall/util/migration";import{classifyClickHouseError as m,describeClickHouseErrorClass as b}from"./classifyClickHouseError.js";import{sleepAbortable as p}from"./sleepAbortable.js";const v=5e3,S=new Set([1,"1",!0]),g=new Set([0,"0",!1]);async function E(e,s,r){try{const t=await(await e.query({query:s,format:"JSONEachRow",...r!==void 0&&{abort_signal:r}})).json(),o=t[0]?.active;return S.has(o)?{kind:"active",active:!0}:g.has(o)?{kind:"active",active:!1}:{kind:"error",err:new Error(`activity probe returned ${t.length} rows with active=${String(o)}; expected one row of 0/1`)}}catch(a){return{kind:"error",err:a}}}l(E,"probeActivity");async function L(e){const{client:s,users:r,timeoutMs:a,signal:t,logger:o}=e,d=e.pollMs??v,u=y({users:r,...e.recencySeconds!==void 0&&{recencySeconds:e.recencySeconds}}),f=Date.now();for(;;){if(t?.aborted)return{outcome:"aborted"};const c=await E(s,u,t),n=Date.now()-f;if(c.kind==="active"&&!c.active)return n>0&&o?.info("control plane idle",{users:[...r],waitedMs:n}),{outcome:"idle"};if(c.kind==="error"){if(t?.aborted)return{outcome:"aborted"};const i=m(c.err);if(i.class==="denied")throw new Error(`awaitControlPlaneIdle: activity probe denied (${b(i)}) \u2014 grant SELECT ON system.processes and system.query_log to the probing identity: ${i.message}`,{cause:c.err});o?.warn("control plane activity probe failed; retrying",{users:[...r],waitedMs:n,class:i.class,...i.code!==void 0&&{code:i.code},error:i.message})}else o?.info("control plane busy; waiting",{users:[...r],waitedMs:n});if(n>=a)return{outcome:"timeout",waitedMs:n};await p(Math.min(d,a-n),t)}}l(L,"awaitControlPlaneIdle");export{L as awaitControlPlaneIdle};

package/dist/classifyClickHouseError.d.ts

@@ -0,0 +1,45 @@
+/**
+ * ClickHouse server error codes this package branches on. `@clickhouse/client`
+ * carries them as STRING `code` values on `ClickHouseError`; the literals here
+ * are the single source for every class set below.
+ */
+export declare const CLICKHOUSE_ERROR_CODES: {
+    readonly UNKNOWN_TABLE: "60";
+    readonly UNKNOWN_DATABASE: "81";
+    readonly READONLY: "164";
+    readonly UNKNOWN_USER: "192";
+    readonly IP_ADDRESS_NOT_ALLOWED: "195";
+    readonly QUOTA_EXCEEDED: "201";
+    readonly TOO_MANY_SIMULTANEOUS_QUERIES: "202";
+    readonly SETTING_CONSTRAINT_VIOLATION: "452";
+    readonly ACCESS_DENIED: "497";
+    readonly AUTHENTICATION_FAILED: "516";
+};
+export type ClickHouseErrorCode = (typeof CLICKHOUSE_ERROR_CODES)[keyof typeof CLICKHOUSE_ERROR_CODES];
+export type ClickHouseErrorClass = "absent" | "busy" | "denied" | "unreachable" | "indeterminate";
+export interface ClickHouseErrorClassification {
+    class: ClickHouseErrorClass;
+    /** Server code (`"202"`) or Node error code (`"ECONNREFUSED"`) when one was found. */
+    code?: string;
+    /** `busy` 202 only: the per-user cap (`user`) or the server-wide cap (`server`). */
+    scope?: "user" | "server";
+    /** Pre-masked via `maskSensitiveOutput` — safe for every sink without re-masking. */
+    message: string;
+}
+/**
+ * Classifies any error raised on the ClickHouse path into the verdict the
+ * caller needs — `absent` (table/database missing), `busy` (a concurrency or
+ * quota cap tripped), `denied` (authentication / authorisation / constraint),
+ * `unreachable` (the network or the client's own timeout/abort), or
+ * `indeterminate`.
+ *
+ * Server codes are read from the `code` property (string per
+ * `@clickhouse/client`; a numeric code is accepted defensively) or, when a
+ * wrapper has flattened the error, from the `Code: NNN.` marker in the
+ * message. A wrapper carrying no code of its own but a `cause` is classified
+ * by that cause; the wrapper's message is kept. Pre-masked producer:
+ * `message` has been through `maskSensitiveOutput` — sinks must not re-mask.
+ */
+export declare function classifyClickHouseError(err: unknown): ClickHouseErrorClassification;
+/** `denied 497` / `unreachable ECONNREFUSED` / `indeterminate` — for error messages and log context. */
+export declare function describeClickHouseErrorClass(classification: ClickHouseErrorClassification): string;

package/dist/classifyClickHouseError.js

@@ -0,0 +1 @@
+var S=Object.defineProperty;var o=(e,n)=>S(e,"name",{value:n,configurable:!0});import{getErrorMessage as u,maskSensitiveOutput as A}from"@fjall/util";const t={UNKNOWN_TABLE:"60",UNKNOWN_DATABASE:"81",READONLY:"164",UNKNOWN_USER:"192",IP_ADDRESS_NOT_ALLOWED:"195",QUOTA_EXCEEDED:"201",TOO_MANY_SIMULTANEOUS_QUERIES:"202",SETTING_CONSTRAINT_VIOLATION:"452",ACCESS_DENIED:"497",AUTHENTICATION_FAILED:"516"},T=new Set([t.UNKNOWN_TABLE,t.UNKNOWN_DATABASE]),d=new Set([t.TOO_MANY_SIMULTANEOUS_QUERIES,t.QUOTA_EXCEEDED]),i=new Set([t.AUTHENTICATION_FAILED,t.ACCESS_DENIED,t.UNKNOWN_USER,t.IP_ADDRESS_NOT_ALLOWED,t.READONLY,t.SETTING_CONSTRAINT_VIOLATION]),a=new Set(["ECONNREFUSED","ECONNRESET","ETIMEDOUT","ENOTFOUND","EAI_AGAIN","EHOSTUNREACH","ECONNABORTED","EPROTO","ABORT_ERR"]),C=/^(?:ERR_(?:TLS|SSL|OSSL)_|CERT_|UNABLE_TO_|DEPTH_ZERO_SELF_SIGNED_CERT$|SELF_SIGNED_CERT_IN_CHAIN$|HOSTNAME_MISMATCH$)/,D=/^Timeout error\.?$|The user aborted a request|socket hang up/i,R=/^\d+$/,I=/\bCode: (\d+)\./;function f(e){if(typeof e!="object"||e===null||!("code"in e))return;const n=e.code;if(typeof n=="number"&&Number.isInteger(n))return String(n);if(typeof n=="string"&&n!=="")return n}o(f,"readCodeProperty");function U(e){return typeof e=="object"&&e!==null&&"name"in e&&e.name==="AbortError"}o(U,"isAbortError");const L=5;function l(e){return typeof e=="object"&&e!==null&&"cause"in e?e.cause:void 0}o(l,"readCause");function p(e){return c(e,0)}o(p,"classifyClickHouseError");function c(e,n){const E=m(e);if(E.class!=="indeterminate"||E.code!==void 0||n>=L)return E;const s=l(e);if(s===void 0)return E;const _=c(s,n+1);return{..._,message:E.message!==""?E.message:_.message}}o(c,"classifyWalkingCause");function m(e){const n=u(e),E=f(e),s=E!==void 0&&R.test(E)?E:I.exec(n)?.[1],_=A(n),r=_!==""?_:s??E??"";if(s!==void 0){if(T.has(s))return{class:"absent",code:s,message:r};if(d.has(s)){const O=s===t.TOO_MANY_SIMULTANEOUS_QUERIES;return{class:"busy",code:s,...O&&{scope:/for user/i.test(n)?"user":"server"},message:r}}return i.has(s)?{class:"denied",code:s,message:r}:{class:"indeterminate",code:s,message:r}}if(E!==void 0&&(a.has(E)||C.test(E)))return{class:"unreachable",code:E,message:r};const N=E!==void 0&&{code:E};return U(e)||D.test(n)?{class:"unreachable",...N,message:r}:{class:"indeterminate",...N,message:r}}o(m,"classifyOwn");function H(e){return e.code===void 0?e.class:`${e.class} ${e.code}`}o(H,"describeClickHouseErrorClass");export{t as CLICKHOUSE_ERROR_CODES,p as classifyClickHouseError,H as describeClickHouseErrorClass};

package/dist/connectWithRetry.d.ts

@@ -6,4 +6,14 @@ export interface ConnectWithRetryOpts {
     delays?: readonly number[];
     logger?: MigrationLogger;
 }
+/**
+ * Waits for the ClickHouse server to answer `/ping`, retrying `unreachable`,
+ * `indeterminate` and `busy` failures across `delays` and `denied` ONLY for
+ * the auth-propagation case (516, up to `AUTH_FAILED_MAX_RETRIES` attempts);
+ * every other `denied` fails closed at once with the classification in the
+ * message.
+ *
+ * `/ping` does NOT authenticate — a wrong password or a missing user
+ * surfaces at the first real query, not here.
+ */
 export declare function connectWithRetry(client: ClickHouseClient, opts: ConnectWithRetryOpts): Promise<void>;

package/dist/connectWithRetry.js

@@ -1 +1 @@
-var y=Object.defineProperty;var f=(c,o)=>y(c,"name",{value:o,configurable:!0});import{getErrorMessage as h,maskSensitiveOutput as _}from"@fjall/util";import{sleepAbortable as p}from"./sleepAbortable.js";const m=[5e3,1e4,2e4,4e4,6e4],A=3,w=516,D=["ECONNREFUSED","ETIMEDOUT","ENOTFOUND"];async function O(c,o){const{label:n,signal:i,logger:s}=o,e=o.delays??m;let l;for(let t=0;t<e.length;t++){if(i?.aborted)throw new Error(`connectWithRetry: ${n} aborted by signal before attempt ${t+1}`);try{await c.ping(),t>0&&s?.info("connect succeeded after retry",{label:n,attempt:t+1});return}catch(r){l=r;const a=typeof r=="object"&&r!==null&&"code"in r?r.code:void 0,E=a===w,d=typeof a=="string"&&D.includes(a);if(!(d||E&&t<A))throw r;const g=E?"AUTH_FAILED":d?a:"UNKNOWN";s?.warn("connect attempt failed; retrying",{label:_(n),attempt:t+1,attempts:e.length,delayMs:e[t],code:g}),await p(e[t],i)}}if(i?.aborted)throw new Error(`connectWithRetry: ${n} aborted by signal after ${e.length} attempts`);const b=_(h(l));throw new Error(`connectWithRetry: ${n} failed after ${e.length} attempts: ${b}`)}f(O,"connectWithRetry");export{O as connectWithRetry};
+var u=Object.defineProperty;var l=(s,r)=>u(s,"name",{value:r,configurable:!0});import{maskSensitiveOutput as y,normaliseError as h}from"@fjall/util";import{CLICKHOUSE_ERROR_CODES as g,classifyClickHouseError as p,describeClickHouseErrorClass as f}from"./classifyClickHouseError.js";import{sleepAbortable as b}from"./sleepAbortable.js";const _=[5e3,1e4,2e4,4e4,6e4],w=3,A=new Set(["unreachable","indeterminate","busy"]);async function R(s){try{return await s.ping()}catch(r){return{success:!1,error:h(r)}}}l(R,"pingSafely");async function L(s,r){const{label:n,signal:c,logger:d}=r,a=r.delays??_;let o;for(let t=0;t<a.length;t++){if(c?.aborted)throw new Error(`connectWithRetry: ${n} aborted by signal before attempt ${t+1}`);const i=await R(s);if(i.success){t>0&&d?.info("connect succeeded after retry",{label:n,attempt:t+1});return}const e=p(i.error);o=e;const E=e.class==="denied"&&e.code===g.AUTHENTICATION_FAILED&&t<w;if(!A.has(e.class)&&!E)throw new Error(`connectWithRetry: ${n} failed (${f(e)}): ${e.message}`,{cause:i.error});d?.warn("connect attempt failed; retrying",{label:y(n),attempt:t+1,attempts:a.length,delayMs:a[t],class:e.class,...e.code!==void 0&&{code:e.code},error:e.message}),await b(a[t],c)}if(c?.aborted)throw new Error(`connectWithRetry: ${n} aborted by signal after ${a.length} attempts`);const m=o===void 0?"no attempt made":`${f(o)}: ${o.message}`;throw new Error(`connectWithRetry: ${n} failed after ${a.length} attempts (${m})`)}l(L,"connectWithRetry");export{L as connectWithRetry};

package/dist/constants.d.ts

@@ -1 +1,8 @@
-export { CLICKHOUSE_MANAGED_USERS_ENV, userPasswordEnvName, } from "@fjall/util/migration";
+export { CLICKHOUSE_BACKUP_SCRATCH_DATABASE, CLICKHOUSE_FRAMEWORK_USERS_ENV, CLICKHOUSE_MAINTENANCE_PROFILE_ENV, CLICKHOUSE_MANAGED_USERS_ENV, FJALL_CLICKHOUSE_USERS, FJALL_MAINTENANCE_USER, FJALL_SCHEMA_GATE_USER, type FjallClickHouseUser, MANAGED_USER_NAME_PATTERN, SCHEMA_GATE_CH_DATABASE_ENV, userPasswordEnvName, } from "@fjall/util/migration";
+/**
+ * The migration audit table. Coupled across the gate's read
+ * (`verifyExpectedClickHouseSchemaVersion`) and the gate identity's GRANT
+ * (`provisionFrameworkUsersFromEnv`): a drift grants SELECT on a table the
+ * gate never reads while the one it does read fails with ACCESS_DENIED.
+ */
+export declare const SCHEMA_MIGRATIONS_TABLE: "_schema_migrations";

package/dist/constants.js

@@ -1 +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};
+import{CLICKHOUSE_BACKUP_SCRATCH_DATABASE as S,CLICKHOUSE_FRAMEWORK_USERS_ENV as C,CLICKHOUSE_MAINTENANCE_PROFILE_ENV as N,CLICKHOUSE_MANAGED_USERS_ENV as L,FJALL_CLICKHOUSE_USERS as R,FJALL_MAINTENANCE_USER as U,FJALL_SCHEMA_GATE_USER as T,MANAGED_USER_NAME_PATTERN as H,SCHEMA_GATE_CH_DATABASE_ENV as I,userPasswordEnvName as M}from"@fjall/util/migration";const E="_schema_migrations";export{S as CLICKHOUSE_BACKUP_SCRATCH_DATABASE,C as CLICKHOUSE_FRAMEWORK_USERS_ENV,N as CLICKHOUSE_MAINTENANCE_PROFILE_ENV,L as CLICKHOUSE_MANAGED_USERS_ENV,R as FJALL_CLICKHOUSE_USERS,U as FJALL_MAINTENANCE_USER,T as FJALL_SCHEMA_GATE_USER,H as MANAGED_USER_NAME_PATTERN,I as SCHEMA_GATE_CH_DATABASE_ENV,E as SCHEMA_MIGRATIONS_TABLE,M as userPasswordEnvName};

package/dist/ensureUserWithPassword.d.ts

@@ -0,0 +1,24 @@
+import type { ClickHouseClient } from "@clickhouse/client";
+export interface LabelledStatement {
+    readonly label: string;
+    readonly query: string;
+}
+export declare function escapeSqlLiteral(value: string): string;
+/**
+ * The idempotent create-or-rotate pair. `CREATE USER IF NOT EXISTS` is a
+ * silent no-op for an existing user — it converges NEITHER the password NOR
+ * any `SETTINGS` (ClickHouse 26.3, verified) — so the `ALTER USER` that
+ * follows is what actually rotates the password and applies the settings.
+ * Do not collapse to one statement.
+ *
+ * `settings`, when given, must be the COMPLETE settings list for the user:
+ * `ALTER USER … SETTINGS` replaces the whole list rather than merging.
+ */
+export declare function buildEnsureUserStatements(name: string, password: string, settings?: string): readonly LabelledStatement[];
+export interface EnsureUserWithPasswordOpts {
+    /** Complete settings list — see `buildEnsureUserStatements`. */
+    settings?: string;
+    /** Cancels the in-flight statement (worker shutdown), not just the next one. */
+    signal?: AbortSignal;
+}
+export declare function ensureUserWithPassword(client: ClickHouseClient, name: string, password: string, opts?: EnsureUserWithPasswordOpts): Promise<void>;

package/dist/ensureUserWithPassword.js

@@ -0,0 +1 @@
+var i=Object.defineProperty;var s=(e,n)=>i(e,"name",{value:n,configurable:!0});function u(e){return e.replace(/\\/g,"\\\\").replace(/'/g,"''")}s(u,"escapeSqlLiteral");function c(e,n,t){const r=`IDENTIFIED WITH sha256_password BY '${u(n)}'`,a=t===void 0?"":` SETTINGS ${t}`;return[{label:"CREATE USER IF NOT EXISTS",query:`CREATE USER IF NOT EXISTS ${e} ${r}`},{label:"ALTER USER",query:`ALTER USER ${e} ${r}${a}`}]}s(c,"buildEnsureUserStatements");async function S(e,n,t,r={}){const{settings:a,signal:o}=r;for(const{query:E}of c(n,t,a))await e.command({query:E,...o!==void 0&&{abort_signal:o}})}s(S,"ensureUserWithPassword");export{c as buildEnsureUserStatements,S as ensureUserWithPassword,u as escapeSqlLiteral};

package/dist/index.d.ts

@@ -1,8 +1,12 @@
-export { CLICKHOUSE_MANAGED_USERS_ENV, userPasswordEnvName, } from "./constants.js";
-export { ManagedUserNameSchema, ManagedUserNamesSchema, type ManagedUserName, type ManagedUserNames, } from "./schemas.js";
+export { CLICKHOUSE_BACKUP_SCRATCH_DATABASE, CLICKHOUSE_FRAMEWORK_USERS_ENV, CLICKHOUSE_MAINTENANCE_PROFILE_ENV, CLICKHOUSE_MANAGED_USERS_ENV, FJALL_CLICKHOUSE_USERS, FJALL_MAINTENANCE_USER, FJALL_SCHEMA_GATE_USER, type FjallClickHouseUser, SCHEMA_MIGRATIONS_TABLE, userPasswordEnvName, } from "./constants.js";
+export { FrameworkUserNameSchema, FrameworkUserNamesSchema, type FrameworkUserName, type FrameworkUserNames, ManagedUserNameSchema, ManagedUserNamesSchema, type ManagedUserName, type ManagedUserNames, } from "./schemas.js";
 export { type MigrationLogger, createConsoleMigrationLogger, } from "./logger.js";
+export { CLICKHOUSE_ERROR_CODES, type ClickHouseErrorClass, type ClickHouseErrorClassification, type ClickHouseErrorCode, classifyClickHouseError, describeClickHouseErrorClass, } from "./classifyClickHouseError.js";
 export { type ConnectWithRetryOpts, connectWithRetry, } from "./connectWithRetry.js";
 export { type ProvisionUsersFromEnvOpts, type ProvisionUsersFromEnvResult, provisionUsersFromEnv, } from "./provisionUsers.js";
+export { type ProvisionFrameworkUsersFromEnvOpts, type ProvisionFrameworkUsersFromEnvResult, provisionFrameworkUsersFromEnv, } from "./provisionFrameworkUsers.js";
+export { type AwaitControlPlaneIdleOpts, type ControlPlaneIdleResult, awaitControlPlaneIdle, } from "./awaitControlPlaneIdle.js";
 export { type RunSqlMigrationsOpts, type RunSqlMigrationsResult, runSqlMigrations, } from "./runSqlMigrations.js";
 export { type VerifyExpectedClickHouseSchemaVersionOpts, type VerifyExpectedClickHouseSchemaVersionResult, verifyExpectedClickHouseSchemaVersion, } from "./verifyExpectedClickHouseSchemaVersion.js";
 export { type CreateFjallClickHouseClientOptions, createFjallClickHouseClient, WIRE_FORMAT_CLICKHOUSE_SETTINGS, } from "./createClient.js";
+export { sleepAbortable } from "./sleepAbortable.js";

package/dist/index.js

@@ -1 +1 @@
-import{CLICKHOUSE_MANAGED_USERS_ENV as o,userPasswordEnvName as t}from"./constants.js";import{ManagedUserNameSchema as m,ManagedUserNamesSchema as s}from"./schemas.js";import{createConsoleMigrationLogger as i}from"./logger.js";import{connectWithRetry as p}from"./connectWithRetry.js";import{provisionUsersFromEnv as S}from"./provisionUsers.js";import{runSqlMigrations as x}from"./runSqlMigrations.js";import{verifyExpectedClickHouseSchemaVersion as l}from"./verifyExpectedClickHouseSchemaVersion.js";import{createFjallClickHouseClient as M,WIRE_FORMAT_CLICKHOUSE_SETTINGS as N}from"./createClient.js";export{o as CLICKHOUSE_MANAGED_USERS_ENV,m as ManagedUserNameSchema,s as ManagedUserNamesSchema,N as WIRE_FORMAT_CLICKHOUSE_SETTINGS,p as connectWithRetry,i as createConsoleMigrationLogger,M as createFjallClickHouseClient,S as provisionUsersFromEnv,x as runSqlMigrations,t as userPasswordEnvName,l as verifyExpectedClickHouseSchemaVersion};
+import{CLICKHOUSE_BACKUP_SCRATCH_DATABASE as o,CLICKHOUSE_FRAMEWORK_USERS_ENV as E,CLICKHOUSE_MAINTENANCE_PROFILE_ENV as C,CLICKHOUSE_MANAGED_USERS_ENV as a,FJALL_CLICKHOUSE_USERS as S,FJALL_MAINTENANCE_USER as s,FJALL_SCHEMA_GATE_USER as m,SCHEMA_MIGRATIONS_TABLE as _,userPasswordEnvName as t}from"./constants.js";import{FrameworkUserNameSchema as i,FrameworkUserNamesSchema as U,ManagedUserNameSchema as n,ManagedUserNamesSchema as N}from"./schemas.js";import{createConsoleMigrationLogger as l}from"./logger.js";import{CLICKHOUSE_ERROR_CODES as L,classifyClickHouseError as R,describeClickHouseErrorClass as I}from"./classifyClickHouseError.js";import{connectWithRetry as H}from"./connectWithRetry.js";import{provisionUsersFromEnv as O}from"./provisionUsers.js";import{provisionFrameworkUsersFromEnv as M}from"./provisionFrameworkUsers.js";import{awaitControlPlaneIdle as K}from"./awaitControlPlaneIdle.js";import{runSqlMigrations as d}from"./runSqlMigrations.js";import{verifyExpectedClickHouseSchemaVersion as h}from"./verifyExpectedClickHouseSchemaVersion.js";import{createFjallClickHouseClient as v,WIRE_FORMAT_CLICKHOUSE_SETTINGS as w}from"./createClient.js";import{sleepAbortable as P}from"./sleepAbortable.js";export{o as CLICKHOUSE_BACKUP_SCRATCH_DATABASE,L as CLICKHOUSE_ERROR_CODES,E as CLICKHOUSE_FRAMEWORK_USERS_ENV,C as CLICKHOUSE_MAINTENANCE_PROFILE_ENV,a as CLICKHOUSE_MANAGED_USERS_ENV,S as FJALL_CLICKHOUSE_USERS,s as FJALL_MAINTENANCE_USER,m as FJALL_SCHEMA_GATE_USER,i as FrameworkUserNameSchema,U as FrameworkUserNamesSchema,n as ManagedUserNameSchema,N as ManagedUserNamesSchema,_ as SCHEMA_MIGRATIONS_TABLE,w as WIRE_FORMAT_CLICKHOUSE_SETTINGS,K as awaitControlPlaneIdle,R as classifyClickHouseError,H as connectWithRetry,l as createConsoleMigrationLogger,v as createFjallClickHouseClient,I as describeClickHouseErrorClass,M as provisionFrameworkUsersFromEnv,O as provisionUsersFromEnv,d as runSqlMigrations,P as sleepAbortable,t as userPasswordEnvName,h as verifyExpectedClickHouseSchemaVersion};

package/dist/maskSqlError.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Masks a server error that may echo the failing statement. Every
+ * single-quoted literal is redacted first because an echoed
+ * `IDENTIFIED WITH sha256_password BY '<password>'` matches no credential
+ * regex; masking runs on the full string and truncation LAST (a truncated
+ * credential loses the anchors the mask needs).
+ */
+export declare function maskSqlError(err: unknown): string;

package/dist/maskSqlError.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var o=(t,e)=>n(t,"name",{value:e,configurable:!0});import{getErrorMessage as i,maskSensitiveOutput as E}from"@fjall/util";const s=400;function u(t){const e=i(t).replace(/'(?:[^']|'')*'/g,"'<REDACTED>'"),r=E(e);return r.length>s?r.slice(0,s)+"\u2026":r}o(u,"maskSqlError");export{u as maskSqlError};

package/dist/provisionFrameworkUsers.d.ts

@@ -0,0 +1,38 @@
+import type { ClickHouseClient } from "@clickhouse/client";
+import { type FjallClickHouseUser } from "./constants.js";
+import type { MigrationLogger } from "./logger.js";
+export interface ProvisionFrameworkUsersFromEnvOpts {
+    client: ClickHouseClient;
+    /**
+     * Database whose audit table the gate reads and whose tables the
+     * maintenance identity may OPTIMIZE / BACKUP. Defaults to env
+     * `CLICKHOUSE_DATABASE`; absent on both → fails closed (a GRANT on the
+     * wrong database is a silent misconfiguration).
+     */
+    database?: string;
+    signal?: AbortSignal;
+    logger?: MigrationLogger;
+    env?: NodeJS.ProcessEnv;
+}
+export interface ProvisionFrameworkUsersFromEnvResult {
+    provisioned: readonly FjallClickHouseUser[];
+}
+/**
+ * Provisions the framework-owned ClickHouse identities (`fjall_schema_gate`,
+ * `fjall_maintenance`) from the migration task, running as the XML schema
+ * admin. Sibling of `provisionUsersFromEnv` (customer users): reads the
+ * manifest from `CLICKHOUSE_FRAMEWORK_USERS`, each password from
+ * `USER_<NAME>_PASSWORD`, and the maintenance profile from
+ * `CLICKHOUSE_MAINTENANCE_PROFILE`.
+ *
+ * An absent manifest is NOT an error — constructs older than the framework
+ * identities emit no manifest, and a runner image ahead of its constructs
+ * must still migrate. Every other missing input fails closed BEFORE the
+ * first statement, naming the env (never the value).
+ *
+ * Idempotent: `CREATE USER IF NOT EXISTS` → `ALTER USER … SETTINGS <complete
+ * list>` → `GRANT …`, each safe to re-run. Failures carry the
+ * `classifyClickHouseError` verdict so the runner's forensic log reads
+ * `denied 497` rather than raw text.
+ */
+export declare function provisionFrameworkUsersFromEnv(opts: ProvisionFrameworkUsersFromEnvOpts): Promise<ProvisionFrameworkUsersFromEnvResult>;

package/dist/provisionFrameworkUsers.js

@@ -0,0 +1 @@
+var v=Object.defineProperty;var o=(e,r)=>v(e,"name",{value:r,configurable:!0});import{getErrorMessage as h,maskSensitiveOutput as m}from"@fjall/util";import{classifyClickHouseError as b,describeClickHouseErrorClass as L}from"./classifyClickHouseError.js";import{CLICKHOUSE_BACKUP_SCRATCH_DATABASE as I,CLICKHOUSE_FRAMEWORK_USERS_ENV as u,CLICKHOUSE_MAINTENANCE_PROFILE_ENV as f,FJALL_CLICKHOUSE_USERS as U,FJALL_MAINTENANCE_USER as E,FJALL_SCHEMA_GATE_USER as p,MANAGED_USER_NAME_PATTERN as k,SCHEMA_GATE_CH_DATABASE_ENV as N,SCHEMA_MIGRATIONS_TABLE as F,userPasswordEnvName as M}from"./constants.js";import{buildEnsureUserStatements as P}from"./ensureUserWithPassword.js";import{maskSqlError as H}from"./maskSqlError.js";import{FrameworkUserNamesSchema as y}from"./schemas.js";const i="provisionFrameworkUsersFromEnv",q=/^[A-Za-z_][A-Za-z0-9_]*$/,B=["parts","disks","tables","processes","query_log"],G={[p]:{settings:o(()=>"readonly = 2 CONST, max_threads = 1 CONST, max_execution_time = 10 CONST","settings"),grants:o(({database:e})=>[`GRANT SELECT ON ${e}.${F} TO ${p}`],"grants")},[E]:{settings:o(({maintenanceProfile:e})=>{if(e===void 0)throw new Error(`${i}: ${E} requires env ${f} (the settings profile it binds to)`);return`PROFILE '${e}', max_concurrent_queries_for_user = 1 CONST`},"settings"),grants:o(({database:e})=>[`GRANT SELECT, SHOW, OPTIMIZE, BACKUP ON ${e}.* TO ${E}`,`GRANT SELECT, INSERT, CREATE DATABASE, CREATE TABLE, DROP DATABASE, DROP TABLE ON ${I}.* TO ${E}`,...B.map(r=>`GRANT SELECT ON system.${r} TO ${E}`)],"grants")}};function D(e){let r;try{r=JSON.parse(e)}catch(s){throw new Error(`${i}: malformed ${u} \u2014 JSON parse failed: ${m(h(s))}`)}const n=y.safeParse(r);if(!n.success)throw new Error(`${i}: malformed ${u} \u2014 ${n.error.message}`);return n.data}o(D,"parseManifest");function K(e,r){const n=r[N],s=e!==void 0&&e!==""?e:n!==void 0&&n!==""?n:void 0;if(s===void 0)throw new Error(`${i}: target database required (opts.database or env ${N})`);if(!q.test(s))throw new Error(`${i}: unsafe database identifier '${m(s)}'`);return s}o(K,"resolveDatabase");function J(e){const r=e[f];if(r===void 0||r==="")throw new Error(`${i}: required env ${f} is missing or empty (the settings profile ${E} binds to)`);if(!k.test(r))throw new Error(`${i}: ${f} must be lowercase snake_case, got '${m(r)}'`);return r}o(J,"requireMaintenanceProfile");function W(e,r){const n=M(r),s=e[n];if(s===void 0||s==="")throw new Error(`${i}: required env ${n} is missing or empty`);return s}o(W,"requirePassword");function x(e,r,n){const s=G[e];return[...P(e,r,s.settings(n)),...s.grants(n).map(a=>({label:a,query:a}))]}o(x,"buildFrameworkUserStatements");async function ee(e){const{client:r,signal:n,logger:s}=e,a=e.env??process.env,c=a[u];if(c===void 0||c==="")return s?.info("no framework users to provision (manifest env absent \u2014 constructs predate the framework identities)",{}),{provisioned:[]};const A=new Set(D(c)),S=U.filter(t=>A.has(t));if(S.length===0)return s?.info("no framework users to provision (manifest empty)",{}),{provisioned:[]};const _=K(e.database,a),w={database:_,...A.has(E)&&{maintenanceProfile:J(a)}},C=S.map(t=>({name:t,statements:x(t,W(a,t),w)})),T=[];for(const{name:t,statements:O}of C){for(const{label:d,query:R}of O){if(n?.aborted)throw new Error(`${i}: aborted by signal before '${t}' ${d}`);try{await r.command({query:R,...n!==void 0&&{abort_signal:n}})}catch($){const l=b($),g=l.class==="denied"?" \u2014 the provisioning identity needs access_management=1 and the granted privileges WITH GRANT OPTION":"";throw new Error(`${i}: ${t}: ${d} failed (${L(l)})${g}: ${H($)}`)}s?.info("framework user statement applied",{name:t,label:d})}s?.info("clickhouse framework user provisioned",{name:t,database:_}),T.push(t)}return{provisioned:T}}o(ee,"provisionFrameworkUsersFromEnv");export{ee as provisionFrameworkUsersFromEnv};

package/dist/provisionUsers.js

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

package/dist/runSqlMigrations.js

@@ -1,3 +1,3 @@
-var S=Object.defineProperty;var l=(r,t)=>S(r,"name",{value:t,configurable:!0});import{readFileSync as y,readdirSync as k}from"node:fs";import{join as q}from"node:path";import{getErrorMessage as h,maskSensitiveOutput as u}from"@fjall/util";import{CLICKHOUSE_MIGRATION_SKIP_RE as R}from"@fjall/util/migration";const $=R,g=400,I=/^--\s*fjall:skip-if:(.*)$/,M=new Set([1,!0,"1"]),_=new Set([0,!1,"0"]);function A(r){return r.split(`
-`).some(t=>{const i=t.trim();return i.length>0&&!i.startsWith("--")})}l(A,"hasSqlContent");function b(r){return r.split(/;\s*\n/).map(t=>t.trim()).filter(t=>t.length>0&&A(t))}l(b,"splitSqlStatements");function w(r){const i=h(r).replace(/'(?:[^']|'')*'/g,"'<REDACTED>'"),e=u(i);return e.length>g?e.slice(0,g)+"\u2026":e}l(w,"maskAndTruncateError");function x(r){let t;for(const i of r.split(`
-`)){const e=i.trim();if(e.length>0&&!e.startsWith("--"))break;const s=I.exec(e);if(s===null)continue;const o=(s[1]??"").trim();if(o.length===0)throw new Error("fjall:skip-if directive has an empty expression");if(t!==void 0)throw new Error("duplicate fjall:skip-if directive in the leading comment block");t=o}return t}l(x,"parseSkipIfDirective");async function j(r,t,i){let e;try{e=await(await r.query({query:`SELECT (${i})`,format:"JSONEachRow"})).json()}catch(c){throw new Error(`runSqlMigrations: ${t}: fjall:skip-if predicate failed: ${w(c)}`,{cause:c})}if(e.length!==1)throw new Error(`runSqlMigrations: ${t}: fjall:skip-if predicate returned ${e.length} rows (expected exactly 1)`);const s=Object.values(e[0]??{});if(s.length!==1)throw new Error(`runSqlMigrations: ${t}: fjall:skip-if predicate returned ${s.length} columns (expected exactly 1)`);const o=s[0];if(M.has(o))return!0;if(_.has(o))return!1;throw new Error(`runSqlMigrations: ${t}: fjall:skip-if predicate returned a non-boolean value (${u(JSON.stringify(o))}); expected 0/1`)}l(j,"evaluateSkipIfPredicate");async function L(r){const{client:t,dir:i,signal:e,logger:s}=r,o=r.skipFilesMatching??$,c=k(i).filter(n=>n.endsWith(".sql")).filter(n=>!o.test(n)).sort(),p=[];for(const n of c){if(e?.aborted)throw new Error(`runSqlMigrations: aborted by signal before applying '${n}'`);const E=q(i,n),d=y(E,"utf8");let f;try{f=x(d)}catch(a){throw new Error(`runSqlMigrations: ${n}: ${u(h(a))}`,{cause:a})}if(f!==void 0&&await j(t,n,f)){s?.info("sql migration skipped by fjall:skip-if directive",{file:n,skipIf:f});continue}const m=b(d);try{for(const a of m){if(e?.aborted)throw new Error(`runSqlMigrations: aborted by signal while applying '${n}'`);await t.command({query:a})}}catch(a){throw new Error(`runSqlMigrations: ${n}: ${w(a)}`,{cause:a})}s?.info("sql migration applied",{file:n}),p.push(n)}return{applied:p}}l(L,"runSqlMigrations");export{A as hasSqlContent,x as parseSkipIfDirective,L as runSqlMigrations};
+var g=Object.defineProperty;var l=(r,t)=>g(r,"name",{value:t,configurable:!0});import{readFileSync as w,readdirSync as E}from"node:fs";import{join as y}from"node:path";import{getErrorMessage as k,maskSensitiveOutput as d}from"@fjall/util";import{CLICKHOUSE_MIGRATION_SKIP_RE as q}from"@fjall/util/migration";import{maskSqlError as h}from"./maskSqlError.js";const $=q,I=/^--\s*fjall:skip-if:(.*)$/,b=new Set([1,!0,"1"]),x=new Set([0,!1,"0"]);function M(r){return r.split(`
+`).some(t=>{const n=t.trim();return n.length>0&&!n.startsWith("--")})}l(M,"hasSqlContent");function j(r){return r.split(/;\s*\n/).map(t=>t.trim()).filter(t=>t.length>0&&M(t))}l(j,"splitSqlStatements");function _(r){let t;for(const n of r.split(`
+`)){const i=n.trim();if(i.length>0&&!i.startsWith("--"))break;const o=I.exec(i);if(o===null)continue;const s=(o[1]??"").trim();if(s.length===0)throw new Error("fjall:skip-if directive has an empty expression");if(t!==void 0)throw new Error("duplicate fjall:skip-if directive in the leading comment block");t=s}return t}l(_,"parseSkipIfDirective");async function v(r,t,n){let i;try{i=await(await r.query({query:`SELECT (${n})`,format:"JSONEachRow"})).json()}catch(c){throw new Error(`runSqlMigrations: ${t}: fjall:skip-if predicate failed: ${h(c)}`,{cause:c})}if(i.length!==1)throw new Error(`runSqlMigrations: ${t}: fjall:skip-if predicate returned ${i.length} rows (expected exactly 1)`);const o=Object.values(i[0]??{});if(o.length!==1)throw new Error(`runSqlMigrations: ${t}: fjall:skip-if predicate returned ${o.length} columns (expected exactly 1)`);const s=o[0];if(b.has(s))return!0;if(x.has(s))return!1;throw new Error(`runSqlMigrations: ${t}: fjall:skip-if predicate returned a non-boolean value (${d(JSON.stringify(s))}); expected 0/1`)}l(v,"evaluateSkipIfPredicate");async function O(r){const{client:t,dir:n,signal:i,logger:o}=r,s=r.skipFilesMatching??$,c=E(n).filter(e=>e.endsWith(".sql")).filter(e=>!s.test(e)).sort(),p=[];for(const e of c){if(i?.aborted)throw new Error(`runSqlMigrations: aborted by signal before applying '${e}'`);const m=y(n,e),u=w(m,"utf8");let f;try{f=_(u)}catch(a){throw new Error(`runSqlMigrations: ${e}: ${d(k(a))}`,{cause:a})}if(f!==void 0&&await v(t,e,f)){o?.info("sql migration skipped by fjall:skip-if directive",{file:e,skipIf:f});continue}const S=j(u);try{for(const a of S){if(i?.aborted)throw new Error(`runSqlMigrations: aborted by signal while applying '${e}'`);await t.command({query:a})}}catch(a){throw new Error(`runSqlMigrations: ${e}: ${h(a)}`,{cause:a})}o?.info("sql migration applied",{file:e}),p.push(e)}return{applied:p}}l(O,"runSqlMigrations");export{M as hasSqlContent,_ as parseSkipIfDirective,O as runSqlMigrations};

package/dist/schemas.d.ts

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

package/dist/schemas.js

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

package/dist/sleepAbortable.d.ts

@@ -1 +1 @@
-export declare function sleepAbortable(ms: number, signal?: AbortSignal): Promise<void>;
+export { sleepAbortable } from "@fjall/util/migration";

package/dist/sleepAbortable.js

@@ -1 +1 @@
-var i=Object.defineProperty;var o=(t,e)=>i(t,"name",{value:e,configurable:!0});function s(t,e){return e?.aborted?Promise.resolve():new Promise(n=>{const r=o(()=>{clearTimeout(b),e?.removeEventListener("abort",r),n()},"onAbort"),b=setTimeout(()=>{e?.removeEventListener("abort",r),n()},t);e?.addEventListener("abort",r,{once:!0})})}o(s,"sleepAbortable");export{s as sleepAbortable};
+import{sleepAbortable as r}from"@fjall/util/migration";export{r as sleepAbortable};

package/dist/verifyExpectedClickHouseSchemaVersion.d.ts

@@ -24,12 +24,26 @@
  * (`version` sha256 hash, `prisma_version` constant) fall back to strict
  * identity.
  */
-import type { ClickHouseClient } from "@clickhouse/client";
 import type { MigrationLogger } from "./logger.js";
 declare const ALLOWED_FIELDS: readonly ["version", "ch_version", "prisma_version"];
 type AllowedField = (typeof ALLOWED_FIELDS)[number];
+/**
+ * The slice of `ClickHouseClient` this check needs. Structural so a caller
+ * holding a narrower handle (the schema-gate container's injectable
+ * `SchemaGateChHandle`) passes it without a cast; `@clickhouse/client`
+ * satisfies it directly.
+ */
+export interface SchemaVersionQueryClient {
+    query(params: {
+        query: string;
+        format: "JSONEachRow";
+        abort_signal?: AbortSignal;
+    }): Promise<{
+        json(): Promise<unknown>;
+    }>;
+}
 export interface VerifyExpectedClickHouseSchemaVersionOpts {
-    client: ClickHouseClient;
+    client: SchemaVersionQueryClient;
     /** Expected version (typically read from an env var baked into the image). */
     expected: string;
     /** Database holding the audit table. Defaults to `"analytics"`. */

package/dist/verifyExpectedClickHouseSchemaVersion.js

@@ -1 +1 @@
-var u=Object.defineProperty;var s=(e,t)=>u(e,"name",{value:t,configurable:!0});import{isSchemaVersionSatisfied as E}from"@fjall/util/migration";const n=/^[A-Za-z_][A-Za-z0-9_]*$/,l=["version","ch_version","prisma_version"],f="analytics",d="_schema_migrations",h="ch_version";async function A(e){if(e.signal?.aborted)throw new Error("verifyExpectedClickHouseSchemaVersion: aborted by signal before query");const t=e.database??f,r=e.table??d,a=e.field??h;if(!n.test(t))throw new Error(`verifyExpectedClickHouseSchemaVersion: unsafe database identifier '${t}'`);if(!n.test(r))throw new Error(`verifyExpectedClickHouseSchemaVersion: unsafe table identifier '${r}'`);if(!l.includes(a))throw new Error(`verifyExpectedClickHouseSchemaVersion: field must be one of ${l.join("|")} (got '${a}')`);const o=(await(await e.client.query({query:`SELECT ${a} AS value FROM ${t}.${r} ORDER BY applied_at DESC LIMIT 1`,format:"JSONEachRow"})).json())[0]?.value,i=typeof o=="string"?o:null,c={matches:i!==null&&E(e.expected,i),expected:e.expected,actual:i};return e.logger?.info("ClickHouse schema-version check complete",{matches:c.matches,expected:c.expected,actual:c.actual,database:t,table:r,field:a}),c}s(A,"verifyExpectedClickHouseSchemaVersion");export{A as verifyExpectedClickHouseSchemaVersion};
+var u=Object.defineProperty;var o=(e,t)=>u(e,"name",{value:t,configurable:!0});import{isSchemaVersionSatisfied as E}from"@fjall/util/migration";import{SCHEMA_MIGRATIONS_TABLE as f}from"./constants.js";const s=/^[A-Za-z_][A-Za-z0-9_]*$/,l=["version","ch_version","prisma_version"],d="analytics",h=f,m="ch_version";async function v(e){if(e.signal?.aborted)throw new Error("verifyExpectedClickHouseSchemaVersion: aborted by signal before query");const t=e.database??d,r=e.table??h,a=e.field??m;if(!s.test(t))throw new Error(`verifyExpectedClickHouseSchemaVersion: unsafe database identifier '${t}'`);if(!s.test(r))throw new Error(`verifyExpectedClickHouseSchemaVersion: unsafe table identifier '${r}'`);if(!l.includes(a))throw new Error(`verifyExpectedClickHouseSchemaVersion: field must be one of ${l.join("|")} (got '${a}')`);const n=(await(await e.client.query({query:`SELECT ${a} AS value FROM ${t}.${r} ORDER BY applied_at DESC LIMIT 1`,format:"JSONEachRow",...e.signal!==void 0&&{abort_signal:e.signal}})).json())[0]?.value,c=typeof n=="string"?n:null,i={matches:c!==null&&E(e.expected,c),expected:e.expected,actual:c};return e.logger?.info("ClickHouse schema-version check complete",{matches:i.matches,expected:i.expected,actual:i.actual,database:t,table:r,field:a}),i}o(v,"verifyExpectedClickHouseSchemaVersion");export{v as verifyExpectedClickHouseSchemaVersion};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/clickhouse",
-  "version": "20.0.0",
+  "version": "21.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",
@@ -50,7 +50,7 @@
     "@clickhouse/client": "^1.18.0"
   },
   "dependencies": {
-    "@fjall/util": "^20.0.0",
+    "@fjall/util": "^21.0.0",
     "zod": "^4.4.3"
   },
   "engines": {