@aws-blocks/bb-distributed-data 0.1.5 → 0.1.7

package/README.md

@@ -90,6 +90,10 @@ CREATE INDEX ASYNC idx_users_email ON users(email);
 
 Migrations are validated at dev time — unsupported features (FK, SERIAL, TRUNCATE, etc.) are caught before deploy.
 
+> **Set `migrationsPath` to a path relative to your project root** (e.g. `'./aws-blocks/dsql-migrations'`); it's resolved at synth from the directory you run `cdk` / `npm run deploy` in. That's the simplest reliable pattern.
+>
+> You don't need `fileURLToPath(import.meta.url)` for this. Your backend module runs as ESM locally but is bundled to **CommonJS** in Lambda, where `import.meta` is empty. AWS Blocks shims `import.meta.url` / `import.meta.dirname` in the bundle so it won't crash at load — but at runtime those resolve to the **bundled output** location, not your source tree. So don't use `import.meta.url` to read a file relative to your source at request time; inline the data or ship it as a Lambda asset instead.
+
 ## DSQL Limitations
 
 DSQL is a subset of PostgreSQL. The local mock enforces these restrictions so code that works locally also works in production.

package/dist/engines/dsql-mock-engine.d.ts

@@ -1,10 +1,31 @@
-import type { DatabaseEngine, TransactionHandle } from '@aws-blocks/data-common';
+/**
+ * PGlite engine wrapped with DSQL validation layer for local development.
+ */
+import { PGlite } from '@electric-sql/pglite';
+import { type DatabaseEngine, type TransactionHandle } from '@aws-blocks/data-common';
 export declare class DsqlMockEngine implements DatabaseEngine {
     private db;
     private closed;
     private shouldConflict;
     private _allowDdl;
-    constructor(dataDir: string);
+    private readonly dataDir;
+    private readonly createClient;
+    private ready?;
+    /**
+     * @param dataDir - directory the PGlite mock persists to.
+     * @param createClient - factory for the underlying PGlite instance; defaults
+     *   to a real `PGlite`. Exposed as a seam so tests can inject an instance
+     *   that simulates a WASM init trap.
+     */
+    constructor(dataDir: string, createClient?: (dataDir: string) => PGlite);
+    private createDb;
+    /**
+     * Force PGlite's lazy WASM initialization, retrying past intermittent
+     * `_pg_initdb` `unreachable` traps by recreating the instance. Runs once per
+     * engine; a permanent failure is not cached, so a later query can retry once
+     * transient memory pressure eases.
+     */
+    private ensureReady;
     /** Test helper: simulate OCC conflict on next commit. */
     simulateConflict(): void;
     /**

package/dist/engines/dsql-mock-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dsql-mock-engine.d.ts","sourceRoot":"","sources":["../../src/engines/dsql-mock-engine.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAoCjF,qBAAa,cAAe,YAAW,cAAc;IACnD,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,SAAS,CAAS;gBAEd,OAAO,EAAE,MAAM;IAM3B,yDAAyD;IACzD,gBAAgB,IAAI,IAAI;IAExB;;;OAGG;IACG,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAK5C,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAMvD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAMvE,gBAAgB,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAK9C,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAc3D,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7D,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAO/F,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAW/G,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAK/B"}
+{"version":3,"file":"dsql-mock-engine.d.ts","sourceRoot":"","sources":["../../src/engines/dsql-mock-engine.ts"],"names":[],"mappings":"AAGA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAG9C,OAAO,EAA6B,KAAK,cAAc,EAAE,KAAK,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAoCjH,qBAAa,cAAe,YAAW,cAAc;IACnD,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA8B;IAC3D,OAAO,CAAC,KAAK,CAAC,CAAkB;IAEhC;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,EAAE,YAAY,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAiC;IAMjG,OAAO,CAAC,QAAQ;IAMhB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IA6BnB,yDAAyD;IACzD,gBAAgB,IAAI,IAAI;IAExB;;;OAGG;IACG,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAK5C,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAMvD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAMvE,gBAAgB,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAQ9C,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAc3D,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7D,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAO/F,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAW/G,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAK/B"}

package/dist/engines/dsql-mock-engine.js

@@ -6,6 +6,7 @@
 import { PGlite } from '@electric-sql/pglite';
 import { existsSync, unlinkSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { initializePgliteWithRetry } from '@aws-blocks/data-common';
 import { DistributedDatabaseErrors, PG_SERIALIZATION_FAILURE, translateDsqlError } from '../errors.js';
 import { validateStatement, classifyStatement, TransactionTracker } from '../validation.js';
 function cleanStaleLock(dataDir) {
@@ -44,10 +45,58 @@ export class DsqlMockEngine {
     closed = false;
     shouldConflict = false;
     _allowDdl = false;
-    constructor(dataDir) {
-        cleanStaleLock(dataDir);
-        mkdirSync(dataDir, { recursive: true });
-        this.db = new PGlite(dataDir);
+    dataDir;
+    createClient;
+    ready;
+    /**
+     * @param dataDir - directory the PGlite mock persists to.
+     * @param createClient - factory for the underlying PGlite instance; defaults
+     *   to a real `PGlite`. Exposed as a seam so tests can inject an instance
+     *   that simulates a WASM init trap.
+     */
+    constructor(dataDir, createClient = (dir) => new PGlite(dir)) {
+        this.dataDir = dataDir;
+        this.createClient = createClient;
+        this.db = this.createDb();
+    }
+    createDb() {
+        cleanStaleLock(this.dataDir);
+        mkdirSync(this.dataDir, { recursive: true });
+        return this.createClient(this.dataDir);
+    }
+    /**
+     * Force PGlite's lazy WASM initialization, retrying past intermittent
+     * `_pg_initdb` `unreachable` traps by recreating the instance. Runs once per
+     * engine; a permanent failure is not cached, so a later query can retry once
+     * transient memory pressure eases.
+     */
+    ensureReady() {
+        if (!this.ready) {
+            this.ready = initializePgliteWithRetry(this.db, () => (this.db = this.createDb()), {
+                onRetry: (attempt, error) => console.warn(`[DsqlMockEngine] PGlite init trap on attempt ${attempt}; recreating instance`, error),
+            })
+                // Pin this.db to the settled instance explicitly (not just via the recreate closure).
+                .then((db) => (this.db = db))
+                .catch((error) => {
+                // Init retry is exhausted; initializePgliteWithRetry has already closed
+                // the last trapped instance, so this.db now points at a dead handle.
+                // Reset readiness AND swap in a fresh, un-probed instance. Without the
+                // swap, the next call would re-probe the CLOSED handle, whose error is a
+                // "closed" error (not an `unreachable` trap) and is therefore classified
+                // non-retryable — permanently wedging the engine and defeating the
+                // "a later query can retry" recovery documented above. Recreating here
+                // is best effort; if it throws we keep propagating the original init error.
+                this.ready = undefined;
+                try {
+                    this.db = this.createDb();
+                }
+                catch {
+                    // Leave the dead handle in place; the original init error is more useful.
+                }
+                throw error;
+            });
+        }
+        return this.ready;
     }
     /** Test helper: simulate OCC conflict on next commit. */
     simulateConflict() { this.shouldConflict = true; }
@@ -67,6 +116,7 @@ export class DsqlMockEngine {
     async query(sql, params) {
         const normalized = preprocessSqlForDsqlMock(sql, { allowDdl: this._allowDdl });
         try {
+            await this.ensureReady();
             return (await this.db.query(normalized, params)).rows;
         }
         catch (e) {
@@ -76,6 +126,7 @@ export class DsqlMockEngine {
     async execute(sql, params) {
         const normalized = preprocessSqlForDsqlMock(sql, { allowDdl: this._allowDdl });
         try {
+            await this.ensureReady();
             return { rowCount: (await this.db.query(normalized, params)).affectedRows ?? 0 };
         }
         catch (e) {
@@ -83,8 +134,14 @@ export class DsqlMockEngine {
         }
     }
     async beginTransaction() {
-        await this.db.query('BEGIN');
-        return { active: true, tracker: new TransactionTracker() };
+        try {
+            await this.ensureReady();
+            await this.db.query('BEGIN');
+            return { active: true, tracker: new TransactionTracker() };
+        }
+        catch (e) {
+            translateDsqlError(e);
+        }
     }
     async commitTransaction(handle) {
         if (this.shouldConflict) {

package/dist/engines/dsql-mock-engine.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dsql-mock-engine.test.d.ts.map

package/dist/engines/dsql-mock-engine.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsql-mock-engine.test.d.ts","sourceRoot":"","sources":["../../src/engines/dsql-mock-engine.test.ts"],"names":[],"mappings":""}

package/dist/engines/dsql-mock-engine.test.js

@@ -0,0 +1,112 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { test, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { PGlite } from '@electric-sql/pglite';
+import { rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { DsqlMockEngine } from './dsql-mock-engine.js';
+import { DistributedDatabaseErrors } from '../errors.js';
+const TEST_DIR = '.bb-data-dsql-mock-test-' + process.pid;
+let engine;
+afterEach(async () => {
+    if (engine)
+        await engine.destroy().catch(() => { });
+    rmSync(TEST_DIR, { recursive: true, force: true });
+});
+// --- Regression #188: PGlite WASM `_pg_initdb` `unreachable` init trap ---
+// The DSQL mock wraps PGlite; the same lazy-init WASM trap kills the dev server
+// during runMigrations. A factory injects a first instance that traps on the
+// init probe; recovery falls through to a REAL PGlite so data round-trips.
+test('recovers when the first PGlite instance traps during init', async () => {
+    const dir = join(TEST_DIR, 'init-trap-recover');
+    let creates = 0;
+    const factory = (d) => {
+        creates++;
+        if (creates === 1) {
+            return {
+                query: async () => {
+                    throw new Error('Aborted(). Build with -sASSERTIONS for more info. RuntimeError: unreachable');
+                },
+                close: async () => { },
+            };
+        }
+        return new PGlite(d);
+    };
+    engine = new DsqlMockEngine(dir, factory);
+    await engine.withDdl(() => engine.execute('CREATE TABLE t (id TEXT PRIMARY KEY)'));
+    await engine.execute("INSERT INTO t (id) VALUES ('ok')");
+    const rows = await engine.query('SELECT id FROM t');
+    assert.deepStrictEqual(rows, [{ id: 'ok' }]);
+    assert.strictEqual(creates, 2, 'engine should recreate the trapped instance exactly once');
+});
+test('surfaces a QueryFailed error when init keeps trapping', async () => {
+    const dir = join(TEST_DIR, 'init-trap-persistent');
+    const factory = () => ({
+        query: async () => {
+            throw new Error('RuntimeError: unreachable');
+        },
+        close: async () => { },
+    });
+    engine = new DsqlMockEngine(dir, factory);
+    await assert.rejects(() => engine.execute("INSERT INTO t (id) VALUES ('x')"), (err) => {
+        assert.strictEqual(err.name, DistributedDatabaseErrors.QueryFailed);
+        return true;
+    });
+});
+// beginTransaction() forces the same lazy WASM init as query()/execute(); an
+// exhausted init-retry at transaction start must also normalize to QueryFailed
+// rather than leaking a raw `RuntimeError: unreachable`.
+test('surfaces a QueryFailed error when init keeps trapping during beginTransaction', async () => {
+    const dir = join(TEST_DIR, 'init-trap-begin-transaction');
+    const factory = () => ({
+        query: async () => {
+            throw new Error('RuntimeError: unreachable');
+        },
+        close: async () => { },
+    });
+    engine = new DsqlMockEngine(dir, factory);
+    await assert.rejects(() => engine.beginTransaction(), (err) => {
+        assert.strictEqual(err.name, DistributedDatabaseErrors.QueryFailed);
+        return true;
+    });
+});
+// --- Regression #188 (recovery): a later call must succeed after the init
+// retry budget is fully exhausted, once the factory stops trapping. The
+// exhausted attempt closes the last instance; keeping that dead handle would
+// make the next call re-probe a CLOSED instance whose error is a "closed"
+// error (NOT `unreachable`) and thus non-retryable, wedging the engine
+// permanently. Trapped instances model a real PGlite: `unreachable` while
+// open, a "closed" error after close().
+test('recovers on a later call after the init-retry budget is exhausted', async () => {
+    const dir = join(TEST_DIR, 'init-trap-exhaust-recover');
+    let creates = 0;
+    const factory = (d) => {
+        creates++;
+        if (creates <= 3) {
+            let closed = false;
+            return {
+                query: async () => {
+                    throw new Error(closed ? 'PGlite is closed' : 'Aborted(). RuntimeError: unreachable');
+                },
+                close: async () => {
+                    closed = true;
+                },
+            };
+        }
+        return new PGlite(d);
+    };
+    engine = new DsqlMockEngine(dir, factory);
+    // First call exhausts the 3-attempt retry budget and rejects.
+    await assert.rejects(() => engine.withDdl(() => engine.execute('CREATE TABLE t (id TEXT PRIMARY KEY)')), (err) => {
+        assert.strictEqual(err.name, DistributedDatabaseErrors.QueryFailed);
+        return true;
+    });
+    // Once the factory stops trapping, a later call must recover on a fresh
+    // instance instead of re-probing the closed handle forever.
+    await engine.withDdl(() => engine.execute('CREATE TABLE t (id TEXT PRIMARY KEY)'));
+    await engine.execute("INSERT INTO t (id) VALUES ('ok')");
+    const rows = await engine.query('SELECT id FROM t');
+    assert.deepStrictEqual(rows, [{ id: 'ok' }]);
+    assert.ok(creates >= 4, 'engine should build a fresh instance after exhaustion');
+});

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

@@ -1 +1 @@
-{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,EAAoC,MAAM,sBAAsB,CAAC;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAQpD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAG7D,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,0BAA0B;IAyFhF;;;;;OAKG;IACH,SAAS,IAAI,KAAK;CAGnB;AAaD,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,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,EAA0E,MAAM,sBAAsB,CAAC;AACrH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAQpD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAG7D,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,0BAA0B;IAkGhF;;;;;OAKG;IACH,SAAS,IAAI,KAAK;CAGnB;AAaD,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,MAAM,YAAY,CAAC"}

package/dist/index.cdk.js

@@ -5,7 +5,7 @@
  * Provisions Aurora DSQL cluster via CloudFormation.
  * Optionally runs migrations via a CustomResource Lambda.
  */
-import { Scope, DEFAULT_NODE_RUNTIME, synthGuard } from '@aws-blocks/core/cdk';
+import { Scope, DEFAULT_NODE_RUNTIME, synthGuard, blocksNodejsBundling, registerConfig } from '@aws-blocks/core/cdk';
 import * as cdk from 'aws-cdk-lib';
 import * as iam from 'aws-cdk-lib/aws-iam';
 import * as lambda from 'aws-cdk-lib/aws-lambda-nodejs';
@@ -18,32 +18,40 @@ export class DistributedDatabase extends Scope {
     constructor(scope, id, options) {
         super(id, { parent: scope });
         const stack = cdk.Stack.of(this);
-        const isSandbox = stack.node.tryGetContext('sandboxMode') === 'true';
         const envName = this.fullId.replace(ENV_SANITIZE, '_');
         const region = stack.region;
         const dbRole = sanitizeDbRoleName(this.fullId);
-        // DSQL Cluster — respect explicit removalPolicy; default to DESTROY in sandbox, RETAIN otherwise.
-        const shouldDestroy = options?.removalPolicy === 'destroy' || (!options?.removalPolicy && isSandbox);
-        const removalPolicy = shouldDestroy ? cdk.RemovalPolicy.DESTROY : cdk.RemovalPolicy.RETAIN;
+        // Removal policy and deletion protection are resolved independently from the
+        // stack-wide `defaults` (per-block `removalPolicy` option wins for that field).
+        // Reading `defaults.deletionProtection` directly — rather than deriving it
+        // from `removalPolicy` — keeps every adopting block consistent: the same
+        // `defaults` object yields the same posture no matter which block reads it.
+        const removalPolicy = options?.removalPolicy === 'destroy'
+            ? cdk.RemovalPolicy.DESTROY
+            : options?.removalPolicy === 'retain'
+                ? cdk.RemovalPolicy.RETAIN
+                : this.defaults.removalPolicy;
         const cluster = new cdk.CfnResource(stack, `${this.fullId}DsqlCluster`, {
             type: 'AWS::DSQL::Cluster',
             properties: {
-                DeletionProtectionEnabled: removalPolicy !== cdk.RemovalPolicy.DESTROY,
+                DeletionProtectionEnabled: this.defaults.deletionProtection,
             },
         });
         cluster.applyRemovalPolicy(removalPolicy);
         const endpoint = cluster.getAtt('Endpoint').toString();
-        // Env vars for runtime
-        this.handler.addEnvironment(`BLOCKS_${envName}_ENDPOINT`, endpoint);
-        this.handler.addEnvironment(`BLOCKS_${envName}_REGION`, region);
-        // IAM grant — app Lambda gets DML-only access via custom DB role (least privilege)
-        this.handler.addToRolePolicy(new iam.PolicyStatement({
+        // Config for runtime — flows through S3 config (loaded into process.env at
+        // cold start) like every other block, instead of a direct env var.
+        registerConfig(this, `BLOCKS_${envName}_ENDPOINT`, endpoint);
+        registerConfig(this, `BLOCKS_${envName}_REGION`, region);
+        // IAM grant — the shared execution role gets DML-only access via custom DB
+        // role (least privilege).
+        this.executionRole.addToPrincipalPolicy(new iam.PolicyStatement({
             actions: ['dsql:DbConnect'],
             resources: [`arn:aws:dsql:${region}:${stack.account}:cluster/${cluster.ref}`],
         }));
         new cdk.CfnOutput(stack, `${this.fullId}DsqlEndpoint`, { value: endpoint });
-        // The app Lambda's IAM role ARN is needed to map the custom DB role.
-        const appRoleArn = this.handler.role.roleArn;
+        // The shared execution role ARN is mapped to the custom DB role.
+        const appRoleArn = this.executionRole.roleArn;
         // Resolve migrations path if provided
         const resolvedMigrationsPath = options?.migrationsPath ? resolve(options.migrationsPath) : undefined;
         const migrationsHash = resolvedMigrationsPath ? hashMigrationsDir(resolvedMigrationsPath) : 'no-migrations';
@@ -63,7 +71,7 @@ export class DistributedDatabase extends Scope {
                 APP_ROLE_ARN: appRoleArn,
                 DB_ROLE_NAME: dbRole,
             },
-            bundling: {
+            bundling: blocksNodejsBundling({
                 commandHooks: {
                     beforeBundling: () => [],
                     beforeInstall: () => [],
@@ -71,7 +79,7 @@ export class DistributedDatabase extends Scope {
                         ? [`cp -r ${resolvedMigrationsPath} ${outputDir}${LAMBDA_MIGRATIONS_DIR.replace('/var/task', '')}`]
                         : [],
                 },
-            },
+            }),
         });
         // Migration Lambda needs Admin access (DDL + role management)
         migrationFn.addToRolePolicy(new iam.PolicyStatement({

package/dist/index.cdk.test.js

@@ -12,18 +12,23 @@ 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 { DEFAULT_NODE_RUNTIME, BlocksPresets } 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 executionRole = new cdk.aws_iam.Role(stack, 'BlocksRole', {
+        assumedBy: new cdk.aws_iam.ServicePrincipal('lambda.amazonaws.com'),
+    });
     const handler = new lambda.Function(stack, 'Handler', {
         runtime: DEFAULT_NODE_RUNTIME,
         handler: 'index.handler',
         code: lambda.Code.fromInline('exports.handler = async () => {};'),
+        role: executionRole,
     });
     stack.handler = handler;
+    stack.executionRole = executionRole;
     globalThis.CURRENT_BLOCKS_STACK = stack;
     try {
         build(stack);
@@ -52,24 +57,55 @@ test('CDK: cluster has DeletionProtectionEnabled=true by default', () => {
         DeletionPolicy: 'Retain',
     });
 });
-test('CDK: removalPolicy=destroy disables deletion protection', () => {
-    const template = synth((stack) => {
-        new DistributedDatabase(scope(stack), 'mydsql', { removalPolicy: 'destroy' });
+test('CDK: per-block removalPolicy is independent of deletion protection', () => {
+    // Deletion protection is read from `defaults` independently of removalPolicy
+    // (consistent across all adopting blocks). Here: sandbox defaults (protection
+    // off) with a per-block `removalPolicy: 'retain'` override → the cluster is
+    // RETAINed on stack delete but not deletion-protected.
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app, 'IndepStack');
+    const executionRole = new cdk.aws_iam.Role(stack, 'BlocksRole', {
+        assumedBy: new cdk.aws_iam.ServicePrincipal('lambda.amazonaws.com'),
     });
-    template.hasResource('AWS::DSQL::Cluster', {
-        Properties: { DeletionProtectionEnabled: false },
-        DeletionPolicy: 'Delete',
+    const handler = new lambda.Function(stack, 'Handler', {
+        runtime: DEFAULT_NODE_RUNTIME,
+        handler: 'index.handler',
+        code: lambda.Code.fromInline('exports.handler = async () => {};'),
+        role: executionRole,
     });
+    stack.handler = handler;
+    stack.defaults = BlocksPresets.sandbox;
+    stack.executionRole = executionRole;
+    globalThis.CURRENT_BLOCKS_STACK = stack;
+    try {
+        new DistributedDatabase(scope(stack), 'mydsql', { removalPolicy: 'retain' });
+        const template = Template.fromStack(stack);
+        template.hasResource('AWS::DSQL::Cluster', {
+            Properties: { DeletionProtectionEnabled: false },
+            DeletionPolicy: 'Retain',
+        });
+    }
+    finally {
+        delete globalThis.CURRENT_BLOCKS_STACK;
+    }
 });
-test('CDK: sandboxMode=true disables deletion protection', () => {
-    const app = new cdk.App({ context: { sandboxMode: 'true' } });
+test('CDK: sandbox defaults disable deletion protection', () => {
+    const app = new cdk.App();
     const stack = new cdk.Stack(app, 'SandboxStack');
+    const executionRole = new cdk.aws_iam.Role(stack, 'BlocksRole', {
+        assumedBy: new cdk.aws_iam.ServicePrincipal('lambda.amazonaws.com'),
+    });
     const handler = new lambda.Function(stack, 'Handler', {
         runtime: DEFAULT_NODE_RUNTIME,
         handler: 'index.handler',
         code: lambda.Code.fromInline('exports.handler = async () => {};'),
+        role: executionRole,
     });
     stack.handler = handler;
+    // The cluster's removal/protection follows the stack-wide defaults (resolved
+    // via the globalThis fallback here), not the sandboxMode context.
+    stack.defaults = BlocksPresets.sandbox;
+    stack.executionRole = executionRole;
     globalThis.CURRENT_BLOCKS_STACK = stack;
     try {
         new DistributedDatabase(scope(stack), 'mydsql');
@@ -99,18 +135,36 @@ test('CDK: handler gets dsql:DbConnect policy (least privilege)', () => {
         },
     });
 });
-// --- Environment variables ---
-test('CDK: handler gets ENDPOINT and REGION env vars', () => {
-    const template = synth((stack) => {
-        new DistributedDatabase(scope(stack), 'mydsql');
+// --- Runtime config (endpoint + region) ---
+test('CDK: registers ENDPOINT and REGION via the config registry (not handler env vars)', () => {
+    const app = new cdk.App();
+    const stack = new cdk.Stack(app, 'TestStack');
+    const executionRole = new cdk.aws_iam.Role(stack, 'BlocksRole', {
+        assumedBy: new cdk.aws_iam.ServicePrincipal('lambda.amazonaws.com'),
     });
-    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}`);
+    const handler = new lambda.Function(stack, 'Handler', {
+        runtime: DEFAULT_NODE_RUNTIME,
+        handler: 'index.handler',
+        code: lambda.Code.fromInline('exports.handler = async () => {};'),
+        role: executionRole,
+    });
+    stack.handler = handler;
+    stack.executionRole = executionRole;
+    globalThis.CURRENT_BLOCKS_STACK = stack;
+    try {
+        new DistributedDatabase(scope(stack), 'mydsql');
+        // Endpoint + region now flow through the config registry (loaded into
+        // process.env at cold start) like every other block — not a direct env var
+        // on the handler.
+        const registry = stack[Symbol.for('BLOCKS_CONFIG_REGISTRY')];
+        assert.ok(registry, 'config registry exists on the stack');
+        const keys = [...registry.entries.keys()];
+        assert.ok(keys.some(k => k.includes('ENDPOINT')), `Expected an ENDPOINT config key, got: ${keys}`);
+        assert.ok(keys.some(k => k.includes('REGION')), `Expected a REGION config key, got: ${keys}`);
+    }
+    finally {
+        delete globalThis.CURRENT_BLOCKS_STACK;
+    }
 });
 // --- CfnOutput ---
 test('CDK: stack has endpoint output', () => {

package/dist/types.d.ts

@@ -6,8 +6,10 @@ export interface DistributedDatabaseOptions {
     /** Path to directory containing numbered .sql migration files. */
     migrationsPath?: string;
     /**
-     * CloudFormation removal policy.
-     * @default 'retain'
+     * CloudFormation removal policy for the DSQL cluster. When omitted, the
+     * stack-wide `defaults` apply (`production` → RETAIN, `sandbox` → DESTROY).
+     * Pass `'destroy'`/`'retain'` to override for this one database. Deletion
+     * protection follows: on unless the cluster is being destroyed.
      */
     removalPolicy?: 'destroy' | 'retain';
     /** Optional logger for internal operations. When omitted, a default Logger at error level is created. */

package/dist/types.d.ts.map

@@ -1 +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"}
+{"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;;;;;OAKG;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/version.d.ts

@@ -1,3 +1,3 @@
 export declare const BB_NAME = "DistributedDatabase";
-export declare const BB_VERSION = "0.1.5";
+export declare const BB_VERSION = "0.1.7";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.mjs — do not edit manually
 export const BB_NAME = 'DistributedDatabase';
-export const BB_VERSION = '0.1.5';
+export const BB_VERSION = '0.1.7';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-blocks/bb-distributed-data",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/aws-devtools-labs/aws-blocks.git",
@@ -37,9 +37,9 @@
     "test": "node --test 'dist/**/*.test.js'"
   },
   "dependencies": {
-    "@aws-blocks/core": "^0.1.17",
-    "@aws-blocks/data-common": "^0.1.3",
-    "@aws-blocks/bb-logger": "^0.1.3",
+    "@aws-blocks/core": "^0.3.0",
+    "@aws-blocks/data-common": "^0.1.4",
+    "@aws-blocks/bb-logger": "^0.1.5",
     "@aws-sdk/dsql-signer": "^3.700.0",
     "@electric-sql/pglite": "^0.2.0",
     "pg": "^8.13.0"