@fjall/components-infrastructure 0.100.0 → 0.102.0

package/dist/lib/patterns/aws/clickhouseDatabase.d.ts

@@ -4,7 +4,7 @@ import { type IBucket } from "aws-cdk-lib/aws-s3";
 import { Construct } from "constructs";
 import { Secret } from "../../resources/aws/secrets/secret.js";
 import { type ClickHouseSchemaAdmin, type ProfileSpec } from "../../resources/aws/database/clickhouseSchemas.js";
-import { type IClickHouseDatabase } from "./interfaces/database.js";
+import { type ClickHouseMigrationsConfig, type IClickHouseDatabase } from "./interfaces/database.js";
 import { type ISecurityGroupConnector } from "./interfaces/connector.js";
 import { type MigrationContributions } from "./interfaces/migrationContributor.js";
 /**
@@ -95,6 +95,15 @@ export interface ClickHouseDatabaseProps {
      * non-snake_case names.
      */
     profiles?: Record<string, ProfileSpec>;
+    /**
+     * Schema-version gate. When set, every container of every service whose
+     * `connections:` includes this database receives `EXPECTED_CH_SCHEMA_VERSION`
+     * baked into its env at synth, unless the service sets `schemaGate: false`.
+     * The default resolver picks the lexicographically-latest `*.sql` filename
+     * under `dir` (skipping `*.dev.sql`), matching what `runSqlMigrations`
+     * records in `_schema_migrations.ch_version`.
+     */
+    migrations?: ClickHouseMigrationsConfig;
 }
 /**
  * ClickHouse analytics database wrapper implementing IClickHouseDatabase.
@@ -134,6 +143,8 @@ export declare class ClickHouseDatabase extends Construct implements IClickHouse
     getDatabaseName(): string;
     getBackupBucket(): IBucket;
     getColdTierBucket(): IBucket | undefined;
+    getMigrationsConfig(): ClickHouseMigrationsConfig | undefined;
+    getExpectedSchemaVersion(): string | undefined;
     grantConnect(grantee: IConnectable): void;
     /**
      * Migration contributions for a task connecting to this ClickHouse cluster

package/dist/lib/patterns/aws/clickhouseDatabase.js

@@ -1,4 +1,4 @@
-import { CLICKHOUSE_MANAGED_USERS_ENV } from "@fjall/util/migration";
+import { CLICKHOUSE_MANAGED_USERS_ENV, pickLatestClickHouseMigration } from "@fjall/util/migration";
 import { Annotations, CfnOutput, Duration, Fn, Stack } from "aws-cdk-lib";
 import { Connections, Port, UserData } from "aws-cdk-lib/aws-ec2";
 import { Monitoring } from "aws-cdk-lib/aws-autoscaling";
@@ -89,6 +89,7 @@ export class ClickHouseDatabase extends Construct {
     #managedPasswordNames;
     #backupBucket;
     #coldTierBucket;
+    #migrationsConfig;
     constructor(scope, id, props) {
         super(scope, id);
         this.id = id;
@@ -185,6 +186,7 @@ export class ClickHouseDatabase extends Construct {
             : undefined;
         this.#backupBucket = backupBucket;
         this.#coldTierBucket = coldTierBucket;
+        this.#migrationsConfig = props.migrations;
         const backupTaskLogGroup = backupEnabled
             ? new LogGroup(this, "ClickHouseBackupTaskLogGroup", {
                 retention: RetentionDays.TWO_WEEKS
@@ -518,6 +520,20 @@ export class ClickHouseDatabase extends Construct {
     getColdTierBucket() {
         return this.#coldTierBucket;
     }
+    getMigrationsConfig() {
+        return this.#migrationsConfig;
+    }
+    getExpectedSchemaVersion() {
+        const config = this.#migrationsConfig;
+        if (config === undefined)
+            return undefined;
+        const resolver = config.versionResolver ?? pickLatestClickHouseMigration;
+        const version = resolver(config.dir);
+        if (version.trim() === "") {
+            throw new Error(`ClickHouseDatabase '${this.id}': migrations.versionResolver returned an empty string for dir '${config.dir}' — refusing to inject an empty EXPECTED_CH_SCHEMA_VERSION.`);
+        }
+        return version;
+    }
     grantConnect(grantee) {
         this.connections.allowDefaultPortFrom(grantee);
         this.connections.allowFrom(grantee, Port.tcp(CLICKHOUSE_NATIVE_PORT));

package/dist/lib/patterns/aws/computeEcs.d.ts

@@ -48,7 +48,7 @@ export declare function expandMigrationsSugar(service: EcsServiceConfig, userCon
  *                      themselves and the resolved value differs.
  * @internal Exported for testing only
  */
-export declare function buildContainerConfigs(service: EcsServiceConfig, schemaVersionEnv?: Record<string, string>, annotationsScope?: Construct): EcsClusterProps["services"][number]["containers"];
+export declare function buildContainerConfigs(service: EcsServiceConfig, schemaVersionEnv?: Record<string, string>, annotationsScope?: Construct, chSchemaVersionEnv?: Record<string, string>): EcsClusterProps["services"][number]["containers"];
 /**
  * Resolved scaling configuration for an ECS service.
  * @internal Exported for testing only
@@ -92,6 +92,18 @@ export declare class EcsCompute extends Construct implements IEcsCompute {
      * hardcoding one.
      */
     private resolveSchemaVersionEnv;
+    /**
+     * ClickHouse mirror of `resolveSchemaVersionEnv`. Returns the
+     * `EXPECTED_CH_SCHEMA_VERSION` env entry, or `undefined` when the service is
+     * not gated.
+     *
+     * - `schemaGate: false` → returns `undefined` (auditable opt-out — same flag
+     *   covers BOTH PG and CH gates)
+     * - No migrated CH in connections → returns `undefined`
+     * - Exactly one migrated CH → returns `{ EXPECTED_CH_SCHEMA_VERSION }`
+     * - Two or more migrated CHs → throws via `resolveClickHouseDatabaseForService`
+     */
+    private resolveClickHouseSchemaVersionEnv;
     private materialiseScheduledTasks;
     private buildScheduledTaskDefinition;
     /**

package/dist/lib/patterns/aws/computeEcs.js

@@ -7,7 +7,7 @@ import { Secret } from "aws-cdk-lib/aws-secretsmanager";
 import { StringParameter } from "aws-cdk-lib/aws-ssm";
 import { Construct } from "constructs";
 import { resolveAlertsTopic } from "../../utils/resolveAlertsTopic.js";
-import { EXPECTED_SCHEMA_VERSION_ENV, EXPECTED_SCHEMA_VERSION_TOOL_ENV, isDatabase, isRelationalDatabase } from "./interfaces/database.js";
+import { EXPECTED_SCHEMA_VERSION_ENV, EXPECTED_SCHEMA_VERSION_TOOL_ENV, EXPECTED_CH_SCHEMA_VERSION_ENV, isClickHouseDatabase, isDatabase, isRelationalDatabase } from "./interfaces/database.js";
 import { isConnectionConfig } from "../../utils/connector.js";
 import { isMigrationContributor } from "./interfaces/migrationContributor.js";
 import App from "../../app.js";
@@ -274,6 +274,37 @@ function resolveMigrationDatabaseForService(service) {
     }
     return matches[0];
 }
+/**
+ * ClickHouse mirror of `resolveMigrationDatabaseForService`. Two-CH-per-service
+ * is rejected for the same reason: the gate can only inject one
+ * `EXPECTED_CH_SCHEMA_VERSION`.
+ */
+function resolveClickHouseDatabaseForService(service) {
+    const connections = service.connections;
+    if (connections === undefined || connections.length === 0)
+        return undefined;
+    const matches = [];
+    for (const spec of connections) {
+        const resource = isConnectionConfig(spec) ? spec.resource : spec;
+        if (!isDatabase(resource))
+            continue;
+        if (!isClickHouseDatabase(resource))
+            continue;
+        if (resource.getMigrationsConfig() !== undefined)
+            matches.push(resource);
+    }
+    if (matches.length === 0)
+        return undefined;
+    if (matches.length > 1) {
+        const names = matches.map((d) => d.node.id).join(", ");
+        throw new Error(`Service '${service.name}': connections include two or more ClickHouse ` +
+            `databases declaring \`migrations:\` (${names}). The schema-version ` +
+            `gate cannot inject ${EXPECTED_CH_SCHEMA_VERSION_ENV} unambiguously. ` +
+            `Split the service so each consumes a single migrated database, or ` +
+            `set \`schemaGate: false\` and inject the env manually.`);
+    }
+    return matches[0];
+}
 function getResourceLabel(resource) {
     if (resource !== null &&
         typeof resource === "object" &&
@@ -436,7 +467,7 @@ function mergeContributionsIntoSeparateTaskDef(separateTaskDef, contributions) {
  *                      themselves and the resolved value differs.
  * @internal Exported for testing only
  */
-export function buildContainerConfigs(service, schemaVersionEnv, annotationsScope) {
+export function buildContainerConfigs(service, schemaVersionEnv, annotationsScope, chSchemaVersionEnv) {
     const userContainers = service.containers && service.containers.length > 0
         ? service.containers
         : undefined;
@@ -464,19 +495,43 @@ export function buildContainerConfigs(service, schemaVersionEnv, annotationsScop
             };
         }
         const merged = { ...(authored ?? {}) };
-        for (const [key, value] of Object.entries(schemaVersionEnv)) {
-            if (merged[key] === undefined)
-                merged[key] = value;
+        if (schemaVersionEnv[EXPECTED_SCHEMA_VERSION_ENV] !== undefined) {
+            merged[EXPECTED_SCHEMA_VERSION_ENV] =
+                schemaVersionEnv[EXPECTED_SCHEMA_VERSION_ENV];
+        }
+        if (schemaVersionEnv[EXPECTED_SCHEMA_VERSION_TOOL_ENV] !== undefined) {
+            merged[EXPECTED_SCHEMA_VERSION_TOOL_ENV] =
+                schemaVersionEnv[EXPECTED_SCHEMA_VERSION_TOOL_ENV];
         }
         return merged;
     };
+    const mergeChSchemaEnv = (authored) => {
+        if (chSchemaVersionEnv === undefined)
+            return authored;
+        const authoredValue = authored?.[EXPECTED_CH_SCHEMA_VERSION_ENV];
+        const resolvedValue = chSchemaVersionEnv[EXPECTED_CH_SCHEMA_VERSION_ENV];
+        if (authoredValue !== undefined) {
+            if (authoredValue !== resolvedValue && annotationsScope !== undefined) {
+                Annotations.of(annotationsScope).addWarning(`Service '${service.name}': author-set ${EXPECTED_CH_SCHEMA_VERSION_ENV}` +
+                    `='${authoredValue}' overrides the value resolved from the connected ` +
+                    `ClickHouse database's \`migrations:\` config ('${resolvedValue}'). The ` +
+                    `author value wins; set \`schemaGate: false\` to silence this warning.`);
+            }
+            return authored;
+        }
+        return {
+            ...(authored ?? {}),
+            [EXPECTED_CH_SCHEMA_VERSION_ENV]: resolvedValue
+        };
+    };
+    const mergeAllSchemaEnv = (authored) => mergeChSchemaEnv(mergeSchemaEnv(authored));
     if (expanded) {
         return expanded.map((c, index) => {
             return {
                 name: c.name || `${service.name}Container${index > 0 ? index : ""}`,
                 image: c.image,
                 port: c.port,
-                environment: mergeSchemaEnv(c.environment),
+                environment: mergeAllSchemaEnv(c.environment),
                 secrets: c.secrets,
                 secretsImport: c.secretsImport,
                 command: c.command,
@@ -490,7 +545,7 @@ export function buildContainerConfigs(service, schemaVersionEnv, annotationsScop
             };
         });
     }
-    const fallbackEnv = mergeSchemaEnv(undefined);
+    const fallbackEnv = mergeAllSchemaEnv(undefined);
     return [
         {
             name: `${service.name}Container`,
@@ -562,7 +617,8 @@ export class EcsCompute extends Construct {
         this.appName = props.appName;
         const services = props.services.map((service) => {
             const schemaVersionEnv = this.resolveSchemaVersionEnv(service);
-            const containers = buildContainerConfigs(service, schemaVersionEnv, this);
+            const chSchemaVersionEnv = this.resolveClickHouseSchemaVersionEnv(service);
+            const containers = buildContainerConfigs(service, schemaVersionEnv, this, chSchemaVersionEnv);
             const { scalingType, minCapacity, maxCapacity } = resolveScalingConfig(service.scaling);
             const cloudMapService = service.serviceDiscovery !== undefined
                 ? App.getInstance().registerService({
@@ -670,6 +726,30 @@ export class EcsCompute extends Construct {
             [EXPECTED_SCHEMA_VERSION_TOOL_ENV]: config.tool
         };
     }
+    /**
+     * ClickHouse mirror of `resolveSchemaVersionEnv`. Returns the
+     * `EXPECTED_CH_SCHEMA_VERSION` env entry, or `undefined` when the service is
+     * not gated.
+     *
+     * - `schemaGate: false` → returns `undefined` (auditable opt-out — same flag
+     *   covers BOTH PG and CH gates)
+     * - No migrated CH in connections → returns `undefined`
+     * - Exactly one migrated CH → returns `{ EXPECTED_CH_SCHEMA_VERSION }`
+     * - Two or more migrated CHs → throws via `resolveClickHouseDatabaseForService`
+     */
+    resolveClickHouseSchemaVersionEnv(service) {
+        if (service.schemaGate === false)
+            return undefined;
+        const db = resolveClickHouseDatabaseForService(service);
+        if (db === undefined)
+            return undefined;
+        const version = db.getExpectedSchemaVersion();
+        if (version === undefined)
+            return undefined;
+        return {
+            [EXPECTED_CH_SCHEMA_VERSION_ENV]: version
+        };
+    }
     materialiseScheduledTasks(id, props) {
         const scheduledTasks = props.cluster?.scheduledTasks;
         if (!scheduledTasks || scheduledTasks.length === 0)

package/dist/lib/patterns/aws/interfaces/database.d.ts

@@ -23,7 +23,7 @@ import { type Secret } from "../../../resources/aws/secrets/index.js";
 import { type SnapshotTarget } from "../../../utils/databaseTypes.js";
 import { type IMigrationContributor } from "./migrationContributor.js";
 export { type SnapshotTarget } from "../../../utils/databaseTypes.js";
-export { MIGRATION_SNAPSHOT_NAME_PREFIX, EXPECTED_SCHEMA_VERSION_ENV, EXPECTED_SCHEMA_VERSION_TOOL_ENV } from "@fjall/util";
+export { MIGRATION_SNAPSHOT_NAME_PREFIX, EXPECTED_SCHEMA_VERSION_ENV, EXPECTED_SCHEMA_VERSION_TOOL_ENV, EXPECTED_CH_SCHEMA_VERSION_ENV } from "@fjall/util";
 /**
  * Declarative migration configuration on a relational database. Drives:
  *  - the schema-version resolver at synth (filesystem scan of `dir`)
@@ -42,6 +42,21 @@ export type MigrationsConfig = {
     readonly dir: string;
     readonly versionResolver: (dir: string) => string;
 };
+/**
+ * Declarative migration configuration on a ClickHouse database. Drives:
+ *  - the schema-version resolver at synth (filesystem scan of `dir`)
+ *  - the `EXPECTED_CH_SCHEMA_VERSION` auto-injection through every
+ *    connected service's containers
+ *
+ * The default resolver picks the lexicographically-latest `*.sql` filename
+ * under `dir` (skipping `*.dev.sql`), matching what `runSqlMigrations`
+ * records in `_schema_migrations.ch_version`. `versionResolver` overrides
+ * the default for projects with a different file convention.
+ */
+export type ClickHouseMigrationsConfig = {
+    readonly dir: string;
+    readonly versionResolver?: (dir: string) => string;
+};
 /**
  * Database type discriminator.
  * Relational types share the IRelationalDatabase interface.
@@ -267,6 +282,22 @@ export interface IClickHouseDatabase extends IDatabase, IConnectable, IMigration
     getBackupBucket(): IBucket;
     /** Get the cold-tier bucket, or `undefined` when cold-tier storage is disabled. */
     getColdTierBucket(): IBucket | undefined;
+    /**
+     * Returns the migration configuration declared on this ClickHouse database,
+     * or `undefined` when the user did not declare one. When set, every
+     * container of every service in this database's `connections:` graph
+     * receives an `EXPECTED_CH_SCHEMA_VERSION` env entry (unless service-level
+     * `schemaGate: false`).
+     */
+    getMigrationsConfig(): ClickHouseMigrationsConfig | undefined;
+    /**
+     * Resolves `migrations.dir` via the resolver (default
+     * `pickLatestClickHouseMigration`) at synth time. Returns `undefined`
+     * when no `migrations:` was declared. Throws when declared but the
+     * directory is empty / unreadable / contains no matching entries — fail
+     * loud, never silent.
+     */
+    getExpectedSchemaVersion(): string | undefined;
     /**
      * Grant connect permissions to a grantee.
      * Adds the grantee to the database security group on both ports.

package/dist/lib/patterns/aws/interfaces/database.js

@@ -13,7 +13,7 @@
  * dynamo.getTableName(); // ✓ Available on IDynamoDBDatabase
  * dynamo.getHostEndpoint(); // ✗ Compile error - not on IDynamoDBDatabase
  */
-export { MIGRATION_SNAPSHOT_NAME_PREFIX, EXPECTED_SCHEMA_VERSION_ENV, EXPECTED_SCHEMA_VERSION_TOOL_ENV } from "@fjall/util";
+export { MIGRATION_SNAPSHOT_NAME_PREFIX, EXPECTED_SCHEMA_VERSION_ENV, EXPECTED_SCHEMA_VERSION_TOOL_ENV, EXPECTED_CH_SCHEMA_VERSION_ENV } from "@fjall/util";
 /**
  * Relational database type discriminator.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "0.100.0",
+  "version": "0.102.0",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "bin": {
@@ -61,8 +61,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1038.0",
-    "@fjall/generator": "^0.100.0",
-    "@fjall/util": "^0.100.0",
+    "@fjall/generator": "^0.102.0",
+    "@fjall/util": "^0.102.0",
     "constructs": "^10.0.0",
     "uuid": "^14.0.0"
   },
@@ -77,5 +77,5 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "gitHead": "9eb16c56de49e6757cfd6352ad860dd125c6c21e"
+  "gitHead": "04a4f13181c261cc063786eae527fa82c90a610e"
 }