@aws-blocks/bb-distributed-data 0.1.0

package/dist/index.cdk.test.js

@@ -0,0 +1,182 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CDK construct tests for DistributedDatabase.
+ * Pattern follows bb-auth-cognito/src/index.cdk.test.ts — sets up a plain Stack
+ * with a placeholder handler on globalThis to satisfy Scope.handler lookups.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import * as cdk from 'aws-cdk-lib';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+import { Template, Match } from 'aws-cdk-lib/assertions';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEFAULT_NODE_RUNTIME } from '@aws-blocks/core/cdk';
+import { DistributedDatabase } from './index.cdk.js';
+const MIGRATIONS_DIR = '.bb-data/__test_cdk_migrations__';
+function synth(build) {
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app, 'TestStack');
+    const handler = new lambda.Function(stack, 'Handler', {
+        runtime: DEFAULT_NODE_RUNTIME,
+        handler: 'index.handler',
+        code: lambda.Code.fromInline('exports.handler = async () => {};'),
+    });
+    stack.handler = handler;
+    globalThis.CURRENT_BLOCKS_STACK = stack;
+    try {
+        build(stack);
+        return Template.fromStack(stack);
+    }
+    finally {
+        delete globalThis.CURRENT_BLOCKS_STACK;
+    }
+}
+function scope(stack) {
+    return stack;
+}
+// --- DSQL Cluster ---
+test('CDK: synthesized stack contains AWS::DSQL::Cluster', () => {
+    const template = synth((stack) => {
+        new DistributedDatabase(scope(stack), 'mydsql');
+    });
+    template.resourceCountIs('AWS::DSQL::Cluster', 1);
+});
+test('CDK: cluster has DeletionProtectionEnabled=true by default', () => {
+    const template = synth((stack) => {
+        new DistributedDatabase(scope(stack), 'mydsql');
+    });
+    template.hasResource('AWS::DSQL::Cluster', {
+        Properties: { DeletionProtectionEnabled: true },
+        DeletionPolicy: 'Retain',
+    });
+});
+test('CDK: removalPolicy=destroy disables deletion protection', () => {
+    const template = synth((stack) => {
+        new DistributedDatabase(scope(stack), 'mydsql', { removalPolicy: 'destroy' });
+    });
+    template.hasResource('AWS::DSQL::Cluster', {
+        Properties: { DeletionProtectionEnabled: false },
+        DeletionPolicy: 'Delete',
+    });
+});
+test('CDK: sandboxMode=true disables deletion protection', () => {
+    const app = new cdk.App({ context: { sandboxMode: 'true' } });
+    const stack = new cdk.Stack(app, 'SandboxStack');
+    const handler = new lambda.Function(stack, 'Handler', {
+        runtime: DEFAULT_NODE_RUNTIME,
+        handler: 'index.handler',
+        code: lambda.Code.fromInline('exports.handler = async () => {};'),
+    });
+    stack.handler = handler;
+    globalThis.CURRENT_BLOCKS_STACK = stack;
+    try {
+        new DistributedDatabase(scope(stack), 'mydsql');
+        const template = Template.fromStack(stack);
+        template.hasResource('AWS::DSQL::Cluster', {
+            Properties: { DeletionProtectionEnabled: false },
+            DeletionPolicy: 'Delete',
+        });
+    }
+    finally {
+        delete globalThis.CURRENT_BLOCKS_STACK;
+    }
+});
+// --- IAM ---
+test('CDK: handler gets dsql:DbConnect policy (least privilege)', () => {
+    const template = synth((stack) => {
+        new DistributedDatabase(scope(stack), 'mydsql');
+    });
+    template.hasResourceProperties('AWS::IAM::Policy', {
+        PolicyDocument: {
+            Statement: Match.arrayWith([
+                Match.objectLike({
+                    Action: 'dsql:DbConnect',
+                    Effect: 'Allow',
+                }),
+            ]),
+        },
+    });
+});
+// --- Environment variables ---
+test('CDK: handler gets ENDPOINT and REGION env vars', () => {
+    const template = synth((stack) => {
+        new DistributedDatabase(scope(stack), 'mydsql');
+    });
+    const fns = template.findResources('AWS::Lambda::Function');
+    const handlerFn = Object.entries(fns).find(([id]) => id.startsWith('Handler'));
+    assert.ok(handlerFn, 'Handler Lambda should exist');
+    const env = handlerFn[1].Properties?.Environment?.Variables ?? {};
+    const envKeys = Object.keys(env);
+    assert.ok(envKeys.some(k => k.includes('ENDPOINT')), `Expected ENDPOINT env var, got: ${envKeys}`);
+    assert.ok(envKeys.some(k => k.includes('REGION')), `Expected REGION env var, got: ${envKeys}`);
+});
+// --- CfnOutput ---
+test('CDK: stack has endpoint output', () => {
+    const template = synth((stack) => {
+        new DistributedDatabase(scope(stack), 'mydsql');
+    });
+    const outputs = template.findOutputs('*');
+    const outputKeys = Object.keys(outputs);
+    assert.ok(outputKeys.some(k => k.includes('DsqlEndpoint')), `Expected DsqlEndpoint output, got: ${outputKeys}`);
+});
+// --- Migrations ---
+test('CDK: migration/provisioning resources always created', () => {
+    const template = synth((stack) => {
+        new DistributedDatabase(scope(stack), 'mydsql');
+    });
+    // The provisioning CustomResource is always created (for DB role setup)
+    const customResources = template.findResources('AWS::CloudFormation::CustomResource');
+    assert.ok(Object.keys(customResources).length > 0, 'Should have provisioning CustomResource');
+    // Migration Lambda should have dsql:DbConnectAdmin for role management
+    const policies = template.findResources('AWS::IAM::Policy');
+    const policyValues = Object.values(policies);
+    const hasDsqlGrant = policyValues.some((p) => JSON.stringify(p).includes('dsql:DbConnectAdmin'));
+    assert.ok(hasDsqlGrant, 'Migration Lambda should have dsql:DbConnectAdmin');
+});
+test('CDK: migration resources created when migrationsPath is provided', () => {
+    rmSync(MIGRATIONS_DIR, { recursive: true, force: true });
+    mkdirSync(MIGRATIONS_DIR, { recursive: true });
+    writeFileSync(join(MIGRATIONS_DIR, '001_create.sql'), 'CREATE TABLE t (id TEXT PRIMARY KEY)');
+    try {
+        const template = synth((stack) => {
+            new DistributedDatabase(scope(stack), 'mydsql', { migrationsPath: MIGRATIONS_DIR });
+        });
+        const customResources = template.findResources('AWS::CloudFormation::CustomResource');
+        assert.ok(Object.keys(customResources).length > 0, 'Should have migration CustomResource');
+        // Migration Lambda should have dsql:DbConnectAdmin
+        const policies = template.findResources('AWS::IAM::Policy');
+        const policyValues = Object.values(policies);
+        const hasDsqlGrant = policyValues.some((p) => JSON.stringify(p).includes('dsql:DbConnectAdmin'));
+        assert.ok(hasDsqlGrant, 'Migration Lambda should have dsql:DbConnectAdmin');
+        // Migration Lambda should have APP_ROLE_ARN and DB_ROLE_NAME env vars
+        const fns = template.findResources('AWS::Lambda::Function');
+        const migrationFn = Object.entries(fns).find(([id]) => id.includes('MigrationFn'));
+        assert.ok(migrationFn, 'Migration Lambda should exist');
+        const env = migrationFn[1].Properties?.Environment?.Variables ?? {};
+        assert.ok(env.APP_ROLE_ARN, 'Migration Lambda should have APP_ROLE_ARN env var');
+        assert.ok(env.DB_ROLE_NAME, 'Migration Lambda should have DB_ROLE_NAME env var');
+    }
+    finally {
+        rmSync(MIGRATIONS_DIR, { recursive: true, force: true });
+    }
+});
+test('CDK: migration CustomResource has migrationsHash property', () => {
+    rmSync(MIGRATIONS_DIR, { recursive: true, force: true });
+    mkdirSync(MIGRATIONS_DIR, { recursive: true });
+    writeFileSync(join(MIGRATIONS_DIR, '001_create.sql'), 'CREATE TABLE t (id TEXT PRIMARY KEY)');
+    try {
+        const template = synth((stack) => {
+            new DistributedDatabase(scope(stack), 'mydsql', { migrationsPath: MIGRATIONS_DIR });
+        });
+        const customResources = template.findResources('AWS::CloudFormation::CustomResource');
+        const cr = Object.values(customResources)[0];
+        assert.ok(cr.Properties?.migrationsHash, 'CustomResource should have migrationsHash property');
+        assert.strictEqual(typeof cr.Properties.migrationsHash, 'string');
+        assert.strictEqual(cr.Properties.migrationsHash.length, 16);
+    }
+    finally {
+        rmSync(MIGRATIONS_DIR, { recursive: true, force: true });
+    }
+});

package/dist/index.mock.d.ts

@@ -0,0 +1,39 @@
+/**
+ * DistributedDatabase — Local development entry point.
+ * PGlite + DSQL validation layer.
+ */
+import { Scope } from '@aws-blocks/core';
+import type { ScopeParent } from '@aws-blocks/core';
+import { type SqlQuery, type Transaction } from '@aws-blocks/data-common';
+import type { DistributedDatabaseOptions, TransactionOptions } from './types.js';
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+export declare class DistributedDatabase extends Scope {
+    private base;
+    private mockEngine;
+    private migrationsRun;
+    /** @internal Logger for internal operations. Defaults to error-level when not provided. */
+    protected log: ChildLogger;
+    constructor(scope: ScopeParent, id: string, options?: DistributedDatabaseOptions);
+    private ready;
+    query<T>(query: SqlQuery): Promise<T[]>;
+    queryOne<T>(query: SqlQuery): Promise<T | null>;
+    execute(query: SqlQuery): Promise<{
+        rowCount: number;
+    }>;
+    /**
+     * Execute a function within a transaction with optional OCC retry.
+     *
+     * DSQL uses Optimistic Concurrency Control. Commit may fail with
+     * SerializationFailureException if another transaction modified the same rows.
+     */
+    transaction<T>(fn: (tx: Transaction) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    /** Test helper: simulate OCC conflict on next commit. */
+    simulateConflict(): void;
+    /** @internal */
+    getEngine(): import("@aws-blocks/data-common").DatabaseEngine;
+}
+export { sql, createKyselyAdapter } from '@aws-blocks/data-common';
+export type { SqlQuery, Transaction } from '@aws-blocks/data-common';
+export { DistributedDatabaseErrors } from './errors.js';
+export type { DistributedDatabaseOptions, TransactionOptions } from './types.js';
+//# sourceMappingURL=index.mock.d.ts.map

package/dist/index.mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mock.d.ts","sourceRoot":"","sources":["../src/index.mock.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH,OAAO,EAAE,KAAK,EAA0B,MAAM,kBAAkB,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAgB,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAIxF,OAAO,KAAK,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEjF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,OAAO,CAAC,IAAI,CAAe;IAC3B,OAAO,CAAC,UAAU,CAAiB;IACnC,OAAO,CAAC,aAAa,CAA8B;IAEnD,2FAA2F;IAC3F,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC;gBAEf,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,0BAA0B;YAelE,KAAK;IAEnB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IACvC,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAC/C,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAEvD;;;;;OAKG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;IAKnG,yDAAyD;IACzD,gBAAgB,IAAI,IAAI;IAExB,gBAAgB;IAChB,SAAS;CACV;AAED,OAAO,EAAE,GAAG,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.mock.js

@@ -0,0 +1,53 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * DistributedDatabase — Local development entry point.
+ * PGlite + DSQL validation layer.
+ */
+import { Scope, registerSdkIdentifiers } from '@aws-blocks/core';
+import { DatabaseBase } from '@aws-blocks/data-common';
+import { DsqlMockEngine } from './engines/dsql-mock-engine.js';
+import { runMigrations, loadMigrationsFromDir } from './migrations.js';
+import { transactionWithRetry } from './transaction.js';
+import { Logger } from '@aws-blocks/bb-logger';
+export class DistributedDatabase extends Scope {
+    base;
+    mockEngine;
+    migrationsRun = null;
+    /** @internal Logger for internal operations. Defaults to error-level when not provided. */
+    log;
+    constructor(scope, id, options) {
+        super(id, { parent: scope });
+        this.log = options?.logger ?? new Logger(this, 'logger', { level: 'error' });
+        this.mockEngine = new DsqlMockEngine(`.bb-data/${this.fullId}`);
+        this.base = new DatabaseBase(this.mockEngine);
+        registerSdkIdentifiers(this.fullId, { clusterEndpoint: `mock-endpoint-${this.fullId}` });
+        if (options?.migrationsPath) {
+            const path = options.migrationsPath;
+            this.migrationsRun = loadMigrationsFromDir(path)
+                .then(m => this.mockEngine.withDdl(() => runMigrations(this.mockEngine, m)))
+                .then(() => { });
+        }
+    }
+    async ready() { if (this.migrationsRun)
+        await this.migrationsRun; }
+    query(query) { return this.ready().then(() => this.base.query(query)); }
+    queryOne(query) { return this.ready().then(() => this.base.queryOne(query)); }
+    execute(query) { return this.ready().then(() => this.base.execute(query)); }
+    /**
+     * Execute a function within a transaction with optional OCC retry.
+     *
+     * DSQL uses Optimistic Concurrency Control. Commit may fail with
+     * SerializationFailureException if another transaction modified the same rows.
+     */
+    async transaction(fn, options) {
+        await this.ready();
+        return transactionWithRetry(this.base, fn, options);
+    }
+    /** Test helper: simulate OCC conflict on next commit. */
+    simulateConflict() { this.mockEngine.simulateConflict(); }
+    /** @internal */
+    getEngine() { return this.base.getEngine(); }
+}
+export { sql, createKyselyAdapter } from '@aws-blocks/data-common';
+export { DistributedDatabaseErrors } from './errors.js';

package/dist/migration-lambda.d.ts

@@ -0,0 +1,5 @@
+import type { CloudFormationCustomResourceEvent } from 'aws-lambda';
+export declare const handler: (event: CloudFormationCustomResourceEvent) => Promise<{
+    PhysicalResourceId: string;
+}>;
+//# sourceMappingURL=migration-lambda.d.ts.map

package/dist/migration-lambda.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-lambda.d.ts","sourceRoot":"","sources":["../src/migration-lambda.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,YAAY,CAAC;AA0FpE,eAAO,MAAM,OAAO,GAAU,OAAO,iCAAiC,KAAG,OAAO,CAAC;IAAE,kBAAkB,EAAE,MAAM,CAAA;CAAE,CAoD9G,CAAC"}

package/dist/migration-lambda.js

@@ -0,0 +1,139 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CloudFormation custom resource handler that runs DSQL migrations on deploy.
+ *
+ * Migrations are bundled as `.sql` files in the Lambda deployment package
+ * (at MIGRATIONS_DIR). The CFN resource property `migrationsHash` triggers
+ * re-invocation when migration files change.
+ *
+ * After running migrations, this handler also provisions a least-privilege
+ * database role for the app Lambda and maps it to the app's IAM role ARN.
+ *
+ * Connects to DSQL via pg + IAM token auth (DsqlSigner) as admin.
+ */
+import { DsqlSigner } from '@aws-sdk/dsql-signer';
+import { existsSync } from 'node:fs';
+import { DsqlEngine } from './engines/dsql-engine.js';
+import { runMigrations, loadMigrationsFromDir } from './migrations.js';
+import { LAMBDA_MIGRATIONS_DIR } from './constants.js';
+// Set by the CDK construct's environment config. Default is the Lambda deployment root
+// where CDK's afterBundling hook copies the .sql files.
+const MIGRATIONS_DIR = process.env.MIGRATIONS_DIR || LAMBDA_MIGRATIONS_DIR;
+const MAX_RETRIES = 5;
+const INITIAL_DELAY_MS = 2000;
+const MAX_DELAY_MS = 15000;
+/**
+ * Retry with exponential backoff for transient connection errors.
+ * DSQL clusters may take a moment to accept connections after creation.
+ */
+async function withRetry(fn) {
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            const isTransient = e?.code?.startsWith?.('08') || // connection exception class
+                e?.message?.includes?.('Connection terminated') ||
+                e?.message?.includes?.('ECONNREFUSED');
+            if (!isTransient || attempt === MAX_RETRIES)
+                throw e;
+            const delay = Math.min(INITIAL_DELAY_MS * 2 ** attempt, MAX_DELAY_MS);
+            console.log(`[bb-distributed-data] Connection not ready, retry ${attempt + 1}/${MAX_RETRIES} in ${delay}ms`);
+            await new Promise(r => setTimeout(r, delay));
+        }
+    }
+    throw new Error('unreachable');
+}
+/**
+ * Provision a custom database role for the app Lambda with DML-only permissions.
+ *
+ * 1. CREATE ROLE (idempotent via pg_roles check)
+ * 2. AWS IAM GRANT — maps the DB role to the app Lambda's IAM role ARN
+ * 3. GRANT DML on user-created tables in public schema
+ *
+ * This runs on every deploy (idempotent) to ensure the role mapping stays in sync
+ * if the app Lambda's IAM role is recreated, and to re-grant DML on any new tables.
+ *
+ * DSQL Limitations:
+ * - ALTER DEFAULT PRIVILEGES is not supported
+ * - GRANT ... ON ALL TABLES IN SCHEMA public is not supported (public is a system entity)
+ * - We grant on individually enumerated user tables instead
+ */
+async function provisionAppRole(engine, dbRoleName, appRoleArn) {
+    console.log(`[bb-distributed-data] Provisioning DB role '${dbRoleName}' for ${appRoleArn}`);
+    // Create the role if it doesn't exist. DSQL doesn't support IF NOT EXISTS on CREATE ROLE,
+    // so we check pg_roles first.
+    const existing = await engine.query(`SELECT rolname FROM pg_roles WHERE rolname = $1`, [dbRoleName]);
+    if (existing.length === 0) {
+        await engine.execute(`CREATE ROLE ${quoteIdent(dbRoleName)} WITH LOGIN`);
+        console.log(`[bb-distributed-data] Created role '${dbRoleName}'`);
+    }
+    // Map the DB role to the app Lambda's IAM ARN (idempotent — DSQL ignores duplicate grants)
+    await engine.execute(`AWS IAM GRANT ${quoteIdent(dbRoleName)} TO '${escapeString(appRoleArn)}'`);
+    // Grant DML on user-created tables in public schema (excluding _migrations).
+    // DSQL does not support "ON ALL TABLES IN SCHEMA public" because public is a system entity.
+    // Instead, enumerate user tables and grant in a single batched statement.
+    const userTables = await engine.query(`SELECT tablename FROM pg_tables WHERE schemaname = 'public' AND tableowner = 'admin' AND tablename != '_migrations'`);
+    if (userTables.length > 0) {
+        const tableList = userTables.map(t => `public.${quoteIdent(t.tablename)}`).join(', ');
+        await engine.execute(`GRANT SELECT, INSERT, UPDATE, DELETE ON ${tableList} TO ${quoteIdent(dbRoleName)}`);
+        console.log(`[bb-distributed-data] Granted DML on ${userTables.length} table(s) to role '${dbRoleName}'`);
+    }
+    console.log(`[bb-distributed-data] Role '${dbRoleName}' provisioned successfully`);
+}
+/** Quote a PostgreSQL identifier to prevent injection. */
+function quoteIdent(name) {
+    return `"${name.replace(/"/g, '""')}"`;
+}
+/** Escape a string literal value (for use inside single quotes). */
+function escapeString(value) {
+    return value.replace(/'/g, "''");
+}
+export const handler = async (event) => {
+    console.log('[bb-distributed-data] Migration event:', JSON.stringify({
+        RequestType: event.RequestType,
+        migrationsHash: event.ResourceProperties?.migrationsHash,
+    }));
+    if (event.RequestType === 'Delete') {
+        return { PhysicalResourceId: event.PhysicalResourceId || 'dsql-migrations' };
+    }
+    const endpoint = process.env.DSQL_ENDPOINT;
+    const region = process.env.DSQL_REGION;
+    const appRoleArn = process.env.APP_ROLE_ARN;
+    const dbRoleName = process.env.DB_ROLE_NAME;
+    if (!endpoint || !region) {
+        throw new Error(`Missing env: DSQL_ENDPOINT=${endpoint}, DSQL_REGION=${region}`);
+    }
+    if (!appRoleArn || !dbRoleName) {
+        throw new Error(`Missing env: APP_ROLE_ARN and DB_ROLE_NAME are required for role provisioning`);
+    }
+    const signer = new DsqlSigner({ hostname: endpoint, region });
+    const engine = new DsqlEngine({
+        endpoint,
+        region,
+        role: 'admin',
+        getAuthToken: () => signer.getDbConnectAdminAuthToken(),
+    });
+    try {
+        // 1. Run user-defined migrations if the directory was bundled
+        if (existsSync(MIGRATIONS_DIR)) {
+            const migrations = await loadMigrationsFromDir(MIGRATIONS_DIR);
+            const applied = await withRetry(() => runMigrations(engine, migrations));
+            console.log('[bb-distributed-data] Applied:', applied.length ? applied : '(none pending)');
+        }
+        else {
+            console.log('[bb-distributed-data] No migrations directory bundled, skipping migrations');
+        }
+        // 2. Provision the app Lambda's custom DB role (least-privilege DML access)
+        await withRetry(() => provisionAppRole(engine, dbRoleName, appRoleArn));
+        return {
+            PhysicalResourceId: `dsql-migrations-${event.ResourceProperties?.migrationsHash || 'unknown'}`,
+        };
+    }
+    finally {
+        await engine.destroy().catch((e) => {
+            console.error('[bb-distributed-data] Failed to destroy engine during cleanup', e);
+        });
+    }
+};

package/dist/migrations.d.ts

@@ -0,0 +1,11 @@
+/**
+ * DSQL-compatible migration runner.
+ */
+import type { DatabaseEngine } from '@aws-blocks/data-common';
+/**
+ * Run pending migrations against a DSQL engine.
+ * DDL runs as implicit transactions, DML in explicit transactions.
+ */
+export declare function runMigrations(engine: DatabaseEngine, migrations: Record<string, string>): Promise<string[]>;
+export declare function loadMigrationsFromDir(dir: string): Promise<Record<string, string>>;
+//# sourceMappingURL=migrations.d.ts.map

package/dist/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AAGA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAI9D;;;GAGG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,OAAO,CAAC,MAAM,EAAE,CAAC,CAyCnB;AAED,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAMxF"}

package/dist/migrations.js

@@ -0,0 +1,59 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { splitStatements } from '@aws-blocks/data-common';
+import { validateMigrations, classifyStatement } from './validation.js';
+/**
+ * Run pending migrations against a DSQL engine.
+ * DDL runs as implicit transactions, DML in explicit transactions.
+ */
+export async function runMigrations(engine, migrations) {
+    validateMigrations(migrations);
+    await engine.execute(`
+    CREATE TABLE IF NOT EXISTS _migrations (
+      id TEXT PRIMARY KEY DEFAULT gen_random_uuid(),
+      name TEXT NOT NULL UNIQUE,
+      applied_at TIMESTAMP NOT NULL DEFAULT NOW()
+    )
+  `);
+    const applied = await engine.query('SELECT name FROM _migrations ORDER BY name');
+    const appliedNames = new Set(applied.map(r => r.name));
+    const files = Object.keys(migrations).sort();
+    const results = [];
+    for (const file of files) {
+        if (appliedNames.has(file))
+            continue;
+        const statements = splitStatements(migrations[file]);
+        const isDdl = statements.some(s => classifyStatement(s) === 'ddl');
+        if (isDdl) {
+            for (const stmt of statements)
+                await engine.execute(stmt);
+            await engine.execute('INSERT INTO _migrations (name) VALUES ($1)', [file]);
+        }
+        else {
+            const handle = await engine.beginTransaction();
+            try {
+                for (const stmt of statements)
+                    await engine.executeInTransaction(handle, stmt);
+                await engine.executeInTransaction(handle, 'INSERT INTO _migrations (name) VALUES ($1)', [file]);
+                await engine.commitTransaction(handle);
+            }
+            catch (e) {
+                await engine.rollbackTransaction(handle).catch(() => { });
+                const err = e;
+                console.error(`[bb-distributed-data] Migration failed: ${file}`, { code: err.code, severity: err.severity });
+                throw e;
+            }
+        }
+        results.push(file);
+        console.log(`[bb-distributed-data] Applied: ${file}`);
+    }
+    return results;
+}
+export async function loadMigrationsFromDir(dir) {
+    const { readdirSync, readFileSync } = await import('node:fs');
+    const files = readdirSync(dir).filter(f => f.endsWith('.sql')).sort();
+    const migrations = {};
+    for (const file of files)
+        migrations[file] = readFileSync(`${dir}/${file}`, 'utf-8');
+    return migrations;
+}

package/dist/transaction.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared OCC retry logic for DistributedDatabase.transaction().
+ */
+import type { DatabaseBase } from '@aws-blocks/data-common';
+import type { Transaction } from '@aws-blocks/data-common';
+import type { TransactionOptions } from './types.js';
+/**
+ * Execute a transaction with optional OCC retry.
+ * Retries on serialization failure (error 40001) up to maxRetries times.
+ */
+export declare function transactionWithRetry<T>(base: DatabaseBase, fn: (tx: Transaction) => Promise<T>, options?: TransactionOptions): Promise<T>;
+//# sourceMappingURL=transaction.d.ts.map

package/dist/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAGA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGrD;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,IAAI,EAAE,YAAY,EAClB,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EACnC,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAaZ"}

package/dist/transaction.js

@@ -0,0 +1,24 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { DistributedDatabaseErrors, PG_SERIALIZATION_FAILURE } from './errors.js';
+import { DEFAULT_MAX_RETRIES } from './constants.js';
+/**
+ * Execute a transaction with optional OCC retry.
+ * Retries on serialization failure (error 40001) up to maxRetries times.
+ */
+export async function transactionWithRetry(base, fn, options) {
+    const maxAttempts = options?.retryOnConflict ? (options.maxRetries ?? DEFAULT_MAX_RETRIES) + 1 : 1;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await base.transaction(fn);
+        }
+        catch (e) {
+            const isOcc = e instanceof Error &&
+                (e.code === PG_SERIALIZATION_FAILURE || e.name === DistributedDatabaseErrors.SerializationFailure);
+            if (isOcc && attempt < maxAttempts)
+                continue;
+            throw e;
+        }
+    }
+    throw new Error('Transaction failed: max retries exceeded');
+}

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Configuration options for the DistributedDatabase Building Block.
+ */
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+export interface DistributedDatabaseOptions {
+    /** Path to directory containing numbered .sql migration files. */
+    migrationsPath?: string;
+    /**
+     * CloudFormation removal policy.
+     * @default 'retain'
+     */
+    removalPolicy?: 'destroy' | 'retain';
+    /** Optional logger for internal operations. When omitted, a default Logger at error level is created. */
+    logger?: ChildLogger;
+}
+/**
+ * Options for transaction execution.
+ */
+export interface TransactionOptions {
+    /**
+     * Automatically retry the transaction on OCC conflict (error 40001).
+     * ⚠️ Callback may execute multiple times. Do NOT include external side effects.
+     * @default false
+     */
+    retryOnConflict?: boolean;
+    /**
+     * Maximum retry attempts on OCC conflict. Only applies when retryOnConflict is true.
+     * @default 3
+     */
+    maxRetries?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,MAAM,WAAW,0BAA0B;IACzC,kEAAkE;IAClE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,aAAa,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACtC,yGAAyG;IACzG,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/types.js

@@ -0,0 +1,3 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+export {};

package/dist/validation.d.ts

@@ -0,0 +1,18 @@
+import { splitStatements } from '@aws-blocks/data-common';
+/** Strip string literals and comments to avoid false positives. */
+export declare function stripLiteralsAndComments(sql: string): string;
+/** Validate a SQL statement for DSQL compatibility. Throws on unsupported features. */
+export declare function validateStatement(sql: string): void;
+/** Classify a statement as DDL, DML, or other. */
+export declare function classifyStatement(sql: string): 'ddl' | 'dml' | 'other';
+export declare class TransactionTracker {
+    private ddlCount;
+    private hasDml;
+    private rowCount;
+    recordStatement(sql: string): void;
+    recordRowCount(count: number): void;
+    reset(): void;
+}
+export declare function validateMigrations(migrations: Record<string, string>): void;
+export { splitStatements };
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,eAAe,EAAuB,MAAM,yBAAyB,CAAC;AAU/E,mEAAmE;AACnE,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA6C5D;AAsBD,uFAAuF;AACvF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAenD;AAED,kDAAkD;AAClD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,CAKtE;AAID,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAK;IAErB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAalC,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAUnC,KAAK,IAAI,IAAI;CACd;AAID,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAiB3E;AAED,OAAO,EAAE,eAAe,EAAE,CAAC"}