@fjall/clickhouse-migrations 0.99.4 → 0.100.0

package/dist/.minified

@@ -1 +1 @@
-8 files minified at 2026-05-22T23:32:44.565Z
+9 files minified at 2026-05-23T06:07:03.980Z

package/dist/index.d.ts

@@ -4,3 +4,4 @@ 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";
+export { type VerifyExpectedClickHouseSchemaVersionOpts, type VerifyExpectedClickHouseSchemaVersionResult, verifyExpectedClickHouseSchemaVersion, } from "./verifyExpectedClickHouseSchemaVersion.js";

package/dist/index.js

@@ -1 +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};
+import{CLICKHOUSE_MANAGED_USERS_ENV as o,userPasswordEnvName as a}from"./constants.js";import{ManagedUserNameSchema as t,ManagedUserNamesSchema as s}from"./schemas.js";import{createConsoleMigrationLogger as i}from"./logger.js";import{connectWithRetry as c}from"./connectWithRetry.js";import{provisionUsersFromEnv as x}from"./provisionUsers.js";import{runSqlMigrations as S}from"./runSqlMigrations.js";import{verifyExpectedClickHouseSchemaVersion as M}from"./verifyExpectedClickHouseSchemaVersion.js";export{o as CLICKHOUSE_MANAGED_USERS_ENV,t as ManagedUserNameSchema,s as ManagedUserNamesSchema,c as connectWithRetry,i as createConsoleMigrationLogger,x as provisionUsersFromEnv,S as runSqlMigrations,a as userPasswordEnvName,M as verifyExpectedClickHouseSchemaVersion};

package/dist/verifyExpectedClickHouseSchemaVersion.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Boot-time gate: verify the ClickHouse `_schema_migrations` audit table's
+ * most recently applied row matches the expected version baked into the
+ * deployed image. Companion to the SQL-side helper
+ * `verifyExpectedSchemaVersion` from `@fjall/util/migration` — together they
+ * close the asymmetry where a webapp's boot gate checks Postgres but blindly
+ * trusts ClickHouse.
+ *
+ * The audit table is owned by the migration runner: see the canonical DDL
+ * recorded by `ensureSchemaMigrationsTable` in the webapp's migration-runner
+ * (columns `version`, `applied_at`, `snapshot_arn`, `prisma_version`,
+ * `ch_version`). This helper reads a single configurable column (default
+ * `ch_version`) so callers can pin to whichever the image's expected env
+ * carries (overall migration hash via `version`, Prisma-side via
+ * `prisma_version`, or ClickHouse-side via `ch_version`).
+ *
+ * Returns `{ matches, expected, actual }` rather than throwing on mismatch:
+ * the consumer's boot script owns the exit-code / log shape.
+ */
+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];
+export interface VerifyExpectedClickHouseSchemaVersionOpts {
+    client: ClickHouseClient;
+    /** Expected version (typically read from an env var baked into the image). */
+    expected: string;
+    /** Database holding the audit table. Defaults to `"analytics"`. */
+    database?: string;
+    /** Audit-table name. Defaults to `"_schema_migrations"`. */
+    table?: string;
+    /** Column whose latest value to compare. Defaults to `"ch_version"`. */
+    field?: AllowedField;
+    signal?: AbortSignal;
+    logger?: MigrationLogger;
+}
+export interface VerifyExpectedClickHouseSchemaVersionResult {
+    matches: boolean;
+    expected: string;
+    /** `null` when the audit table is empty (no migrations applied yet). */
+    actual: string | null;
+}
+export declare function verifyExpectedClickHouseSchemaVersion(opts: VerifyExpectedClickHouseSchemaVersionOpts): Promise<VerifyExpectedClickHouseSchemaVersionResult>;
+export {};

package/dist/verifyExpectedClickHouseSchemaVersion.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/clickhouse-migrations",
-  "version": "0.99.4",
+  "version": "0.100.0",
   "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",
@@ -44,11 +44,11 @@
     "@clickhouse/client": "^1.18.0"
   },
   "dependencies": {
-    "@fjall/util": "^0.99.4",
+    "@fjall/util": "^0.100.0",
     "zod": "^4.4.3"
   },
   "engines": {
     "node": ">=22.0.0"
   },
-  "gitHead": "4d52f0059ebb467b4a63603ed397dae36811d735"
+  "gitHead": "9eb16c56de49e6757cfd6352ad860dd125c6c21e"
 }