@aws-blocks/bb-distributed-data 0.1.0

package/dist/e2e-mock.test.js

@@ -0,0 +1,185 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * E2E tests for DistributedDatabase mock engine (PGlite + validation).
+ */
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { rmSync } from 'node:fs';
+import { DatabaseBase, sql } from '@aws-blocks/data-common';
+import { DsqlMockEngine } from './engines/dsql-mock-engine.js';
+import { DistributedDatabaseErrors } from './errors.js';
+import { runMigrations } from './migrations.js';
+import { transactionWithRetry } from './transaction.js';
+const DIR = '.bb-data/__test_dsql_e2e__';
+describe('DistributedDatabase E2E (mock)', () => {
+    let engine;
+    let db;
+    before(async () => {
+        rmSync(DIR, { recursive: true, force: true });
+        engine = new DsqlMockEngine(DIR);
+        db = new DatabaseBase(engine);
+        // Schema setup is DDL, which the app runtime rejects (parity with prod
+        // dsql:DbConnect). Run it through the migration-style withDdl escape hatch.
+        await engine.withDdl(async () => {
+            await db.execute(sql `CREATE TABLE users (id TEXT PRIMARY KEY, name TEXT NOT NULL, email TEXT UNIQUE)`);
+            await db.execute(sql `CREATE TABLE accounts (id TEXT PRIMARY KEY, balance INT NOT NULL DEFAULT 0)`);
+        });
+    });
+    after(async () => {
+        await engine.destroy();
+        rmSync(DIR, { recursive: true, force: true });
+    });
+    it('CRUD', async () => {
+        await db.execute(sql `INSERT INTO users (id, name, email) VALUES (${'u1'}, ${'Alice'}, ${'a@t.com'})`);
+        await db.execute(sql `INSERT INTO users (id, name, email) VALUES (${'u2'}, ${'Bob'}, ${'b@t.com'})`);
+        const rows = await db.query(sql `SELECT name FROM users ORDER BY name`);
+        assert.equal(rows.length, 2);
+        assert.equal(rows[0].name, 'Alice');
+        const one = await db.queryOne(sql `SELECT name FROM users WHERE id = ${'u1'}`);
+        assert.equal(one?.name, 'Alice');
+        assert.equal(await db.queryOne(sql `SELECT * FROM users WHERE id = ${'x'}`), null);
+        const upd = await db.execute(sql `UPDATE users SET name = ${'A2'} WHERE id = ${'u1'}`);
+        assert.equal(upd.rowCount, 1);
+    });
+    it('transaction commits', async () => {
+        await db.execute(sql `INSERT INTO accounts (id, balance) VALUES (${'a1'}, ${1000})`);
+        await db.execute(sql `INSERT INTO accounts (id, balance) VALUES (${'a2'}, ${500})`);
+        await db.transaction(async (tx) => {
+            await tx.execute(sql `UPDATE accounts SET balance = balance - ${100} WHERE id = ${'a1'}`);
+            await tx.execute(sql `UPDATE accounts SET balance = balance + ${100} WHERE id = ${'a2'}`);
+        });
+        const a1 = await db.queryOne(sql `SELECT balance FROM accounts WHERE id = ${'a1'}`);
+        assert.equal(a1?.balance, 900);
+    });
+    it('transaction rolls back on error', async () => {
+        const before = await db.queryOne(sql `SELECT balance FROM accounts WHERE id = ${'a1'}`);
+        await assert.rejects(() => db.transaction(async (tx) => {
+            await tx.execute(sql `UPDATE accounts SET balance = 0 WHERE id = ${'a1'}`);
+            throw new Error('fail');
+        }));
+        const after = await db.queryOne(sql `SELECT balance FROM accounts WHERE id = ${'a1'}`);
+        assert.equal(after?.balance, before?.balance);
+    });
+    it('simulateConflict throws SerializationFailure', async () => {
+        engine.simulateConflict();
+        await assert.rejects(() => db.transaction(async (tx) => { await tx.execute(sql `UPDATE accounts SET balance = 1 WHERE id = ${'a1'}`); }), (e) => { assert.equal(e.name, DistributedDatabaseErrors.SerializationFailure); return true; });
+    });
+    it('retryOnConflict recovers', async () => {
+        engine.simulateConflict();
+        const result = await transactionWithRetry(db, async (tx) => { await tx.execute(sql `UPDATE accounts SET balance = balance + ${1} WHERE id = ${'a2'}`); return 'ok'; }, { retryOnConflict: true });
+        assert.equal(result, 'ok');
+    });
+    it('rejects FK at query time', async () => {
+        await assert.rejects(() => db.execute(sql `CREATE TABLE bad (id TEXT REFERENCES users(id))`), { name: 'DsqlValidationError' });
+    });
+    it('rejects DDL+DML in transaction', async () => {
+        await assert.rejects(() => db.transaction(async (tx) => {
+            await tx.execute(sql `INSERT INTO users (id, name) VALUES (${'x'}, ${'X'})`);
+            await tx.execute(sql `CREATE TABLE fail (id TEXT)`);
+        }), { name: 'DsqlPermissionError' });
+    });
+    it('unique constraint violation', async () => {
+        await assert.rejects(() => db.execute(sql `INSERT INTO users (id, name, email) VALUES (${'u1'}, ${'Dup'}, ${'dup@t.com'})`), (e) => { assert.equal(e.name, DistributedDatabaseErrors.UniqueConstraintViolation); return true; });
+    });
+});
+describe('Migration runner E2E', () => {
+    const DIR2 = '.bb-data/__test_dsql_migrations__';
+    let engine;
+    before(async () => { rmSync(DIR2, { recursive: true, force: true }); engine = new DsqlMockEngine(DIR2); });
+    after(async () => { await engine.destroy(); rmSync(DIR2, { recursive: true, force: true }); });
+    it('runs and tracks migrations', async () => {
+        const applied = await engine.withDdl(() => runMigrations(engine, {
+            '001.sql': 'CREATE TABLE t (id TEXT PRIMARY KEY, name TEXT)',
+            '002.sql': "INSERT INTO t (id, name) VALUES ('1', 'Admin')",
+        }));
+        assert.deepEqual(applied, ['001.sql', '002.sql']);
+        const rows = await engine.query('SELECT name FROM t');
+        assert.equal(rows[0].name, 'Admin');
+    });
+    it('skips already-applied', async () => {
+        const applied = await engine.withDdl(() => runMigrations(engine, {
+            '001.sql': 'CREATE TABLE t (id TEXT PRIMARY KEY, name TEXT)',
+            '002.sql': "INSERT INTO t (id, name) VALUES ('1', 'Admin')",
+            '003.sql': 'ALTER TABLE t ADD COLUMN age INT',
+        }));
+        assert.deepEqual(applied, ['003.sql']);
+    });
+    it('rejects invalid migrations', async () => {
+        await assert.rejects(() => engine.withDdl(() => runMigrations(engine, {
+            '004.sql': 'CREATE TABLE bad (id TEXT REFERENCES t(id))',
+        })), { name: 'DsqlMigrationValidationError' });
+    });
+});
+// ─── DsqlMockEngine — CREATE INDEX ASYNC parity ─────────────────────────────
+// DSQL supports `CREATE INDEX ASYNC` for non-blocking index builds. The mock
+// engine must accept this syntax and execute it synchronously (PGlite doesn't
+// understand the ASYNC keyword natively).
+describe('DsqlMockEngine — CREATE INDEX ASYNC parity', () => {
+    const DIR3 = '.bb-data/__test_dsql_async_index__';
+    let engine;
+    let db;
+    before(async () => {
+        rmSync(DIR3, { recursive: true, force: true });
+        engine = new DsqlMockEngine(DIR3);
+        db = new DatabaseBase(engine);
+        // CREATE INDEX is DDL, which the app runtime rejects. This suite exercises
+        // the engine's CREATE INDEX ASYNC preprocessing directly, so run all DDL
+        // through the withDdl escape hatch (the same one the migration runner uses).
+        await engine.withDdl(() => db.execute(sql `CREATE TABLE users (id TEXT PRIMARY KEY, email TEXT, active BOOLEAN DEFAULT true)`));
+    });
+    after(async () => {
+        await engine.destroy();
+        rmSync(DIR3, { recursive: true, force: true });
+    });
+    it('accepts CREATE INDEX ASYNC (executes as synchronous locally)', async () => {
+        await assert.doesNotReject(() => engine.withDdl(() => db.execute(sql `CREATE INDEX ASYNC idx_users_email ON users(email)`)));
+    });
+    it('makes the index usable immediately after CREATE INDEX ASYNC', async () => {
+        await engine.withDdl(() => db.execute(sql `CREATE INDEX ASYNC idx_users_active ON users(active)`));
+        // If the index was actually created, EXPLAIN/usage and inserts still work.
+        await db.execute(sql `INSERT INTO users (id, email, active) VALUES (${'u-async'}, ${'a@t.com'}, ${true})`);
+        const row = await db.queryOne(sql `SELECT id FROM users WHERE active = ${true} AND id = ${'u-async'}`);
+        assert.equal(row?.id, 'u-async');
+    });
+    it('accepts CREATE UNIQUE INDEX ASYNC', async () => {
+        await assert.doesNotReject(() => engine.withDdl(() => db.execute(sql `CREATE UNIQUE INDEX ASYNC idx_users_email_uniq ON users(email)`)));
+    });
+    it('accepts CREATE INDEX ASYNC with IF NOT EXISTS', async () => {
+        await assert.doesNotReject(() => engine.withDdl(() => db.execute(sql `CREATE INDEX ASYNC IF NOT EXISTS idx_users_email2 ON users(email)`)));
+    });
+    it('accepts a partial CREATE INDEX ASYNC (WHERE clause)', async () => {
+        await assert.doesNotReject(() => engine.withDdl(() => db.execute(sql `CREATE INDEX ASYNC idx_users_active_email ON users(email) WHERE active = true`)));
+    });
+    it('still supports a plain CREATE INDEX (no ASYNC)', async () => {
+        await assert.doesNotReject(() => engine.withDdl(() => db.execute(sql `CREATE INDEX idx_users_plain ON users(id)`)));
+    });
+    it('does not strip ASYNC outside of CREATE INDEX (column named "async")', async () => {
+        await engine.withDdl(() => db.execute(sql `CREATE TABLE jobs (id TEXT PRIMARY KEY, async BOOLEAN)`));
+        await db.execute(sql `INSERT INTO jobs (id, async) VALUES (${'j1'}, ${true})`);
+        const row = await db.queryOne(sql `SELECT async FROM jobs WHERE id = ${'j1'}`);
+        assert.equal(row?.async, true);
+    });
+    it('does not strip the word ASYNC inside a string literal', async () => {
+        await engine.withDdl(() => db.execute(sql `CREATE TABLE notes (id TEXT PRIMARY KEY, body TEXT)`));
+        await db.execute(sql `INSERT INTO notes (id, body) VALUES (${'n1'}, ${'run ASYNC index later'})`);
+        const row = await db.queryOne(sql `SELECT body FROM notes WHERE id = ${'n1'}`);
+        assert.equal(row?.body, 'run ASYNC index later');
+    });
+    it('runs migrations that use CREATE INDEX ASYNC', async () => {
+        const DIR4 = '.bb-data/__test_dsql_async_index_mig__';
+        rmSync(DIR4, { recursive: true, force: true });
+        const mengine = new DsqlMockEngine(DIR4);
+        try {
+            const applied = await mengine.withDdl(() => runMigrations(mengine, {
+                '001_create_posts.sql': 'CREATE TABLE posts (id TEXT PRIMARY KEY, slug TEXT)',
+                '002_index_slug.sql': 'CREATE INDEX ASYNC idx_posts_slug ON posts(slug)',
+            }));
+            assert.deepEqual(applied, ['001_create_posts.sql', '002_index_slug.sql']);
+        }
+        finally {
+            await mengine.destroy();
+            rmSync(DIR4, { recursive: true, force: true });
+        }
+    });
+});

package/dist/e2e.test.d.ts

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

package/dist/e2e.test.d.ts.map

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

package/dist/e2e.test.js

@@ -0,0 +1,329 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * E2E tests for the DistributedDatabase public API.
+ *
+ * Exercises the full user-facing surface: DistributedDatabase class with migrations,
+ * CRUD, transactions, OCC retry, and DSQL validation guardrails.
+ *
+ * Runs against the mock engine (PGlite) locally. The same test scenarios
+ * would apply against a real DSQL cluster — swap the import condition to
+ * 'aws-runtime' and provide DSQL_ENDPOINT / AWS_REGION env vars.
+ */
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DistributedDatabase, sql, DistributedDatabaseErrors } from './index.mock.js';
+// ── Helpers ─────────────────────────────────────────────────────────────────
+const TEST_DIR = '.bb-data/__test_dsql_public_api__';
+const MIGRATIONS_DIR = join(TEST_DIR, 'migrations');
+/** Minimal scope stub — DistributedDatabase extends Scope which needs a parent. */
+const scope = { id: 'test' };
+function uniqueId() {
+    return `id-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+// ── Setup migrations on disk ────────────────────────────────────────────────
+function writeMigrations(files) {
+    rmSync(MIGRATIONS_DIR, { recursive: true, force: true });
+    mkdirSync(MIGRATIONS_DIR, { recursive: true });
+    for (const [name, content] of Object.entries(files)) {
+        writeFileSync(join(MIGRATIONS_DIR, name), content);
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// Test Suite: DistributedDatabase with migrations
+// ═══════════════════════════════════════════════════════════════════════════════
+describe('DistributedDatabase — public API with migrations', () => {
+    let db;
+    before(() => {
+        rmSync(TEST_DIR, { recursive: true, force: true });
+        writeMigrations({
+            '001_create_users.sql': `CREATE TABLE users (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        email TEXT UNIQUE NOT NULL
+      )`,
+            '002_create_accounts.sql': `CREATE TABLE accounts (
+        id TEXT PRIMARY KEY,
+        owner_id TEXT NOT NULL,
+        balance INT NOT NULL DEFAULT 0
+      )`,
+            '003_seed_admin.sql': `INSERT INTO users (id, name, email) VALUES ('admin', 'Admin', 'admin@test.com')`,
+        });
+        db = new DistributedDatabase(scope, 'e2e', { migrationsPath: MIGRATIONS_DIR });
+    });
+    after(async () => {
+        await db.mockEngine.destroy();
+        rmSync(TEST_DIR, { recursive: true, force: true });
+    });
+    // ── Migrations ──────────────────────────────────────────────────────────
+    describe('migrations', () => {
+        it('applies migrations and seeds data on first query', async () => {
+            const admin = await db.queryOne(sql `SELECT name, email FROM users WHERE id = ${'admin'}`);
+            assert.equal(admin?.name, 'Admin');
+            assert.equal(admin?.email, 'admin@test.com');
+        });
+        it('created all tables from migrations', async () => {
+            // Verify accounts table exists by inserting
+            const { rowCount } = await db.execute(sql `INSERT INTO accounts (id, owner_id, balance) VALUES (${'acc-check'}, ${'admin'}, ${0})`);
+            assert.equal(rowCount, 1);
+            await db.execute(sql `DELETE FROM accounts WHERE id = ${'acc-check'}`);
+        });
+    });
+    // ── CRUD Operations ─────────────────────────────────────────────────────
+    describe('CRUD', () => {
+        it('insert and query', async () => {
+            const id = uniqueId();
+            const { rowCount } = await db.execute(sql `INSERT INTO users (id, name, email) VALUES (${id}, ${'Alice'}, ${`alice-${id}@test.com`})`);
+            assert.equal(rowCount, 1);
+            const rows = await db.query(sql `SELECT id, name FROM users WHERE id = ${id}`);
+            assert.equal(rows.length, 1);
+            assert.equal(rows[0].name, 'Alice');
+            await db.execute(sql `DELETE FROM users WHERE id = ${id}`);
+        });
+        it('queryOne returns row or null', async () => {
+            const id = uniqueId();
+            await db.execute(sql `INSERT INTO users (id, name, email) VALUES (${id}, ${'Bob'}, ${`bob-${id}@test.com`})`);
+            const found = await db.queryOne(sql `SELECT name FROM users WHERE id = ${id}`);
+            assert.equal(found?.name, 'Bob');
+            const missing = await db.queryOne(sql `SELECT * FROM users WHERE id = ${'nonexistent'}`);
+            assert.equal(missing, null);
+            await db.execute(sql `DELETE FROM users WHERE id = ${id}`);
+        });
+        it('update returns affected row count', async () => {
+            const id = uniqueId();
+            await db.execute(sql `INSERT INTO users (id, name, email) VALUES (${id}, ${'Carol'}, ${`carol-${id}@test.com`})`);
+            const { rowCount } = await db.execute(sql `UPDATE users SET name = ${'Carol2'} WHERE id = ${id}`);
+            assert.equal(rowCount, 1);
+            const updated = await db.queryOne(sql `SELECT name FROM users WHERE id = ${id}`);
+            assert.equal(updated?.name, 'Carol2');
+            await db.execute(sql `DELETE FROM users WHERE id = ${id}`);
+        });
+        it('delete returns affected row count', async () => {
+            const id = uniqueId();
+            await db.execute(sql `INSERT INTO users (id, name, email) VALUES (${id}, ${'Del'}, ${`del-${id}@test.com`})`);
+            const { rowCount } = await db.execute(sql `DELETE FROM users WHERE id = ${id}`);
+            assert.equal(rowCount, 1);
+            const gone = await db.queryOne(sql `SELECT * FROM users WHERE id = ${id}`);
+            assert.equal(gone, null);
+        });
+        it('query with multiple results ordered', async () => {
+            const ids = [uniqueId(), uniqueId(), uniqueId()];
+            for (const [i, id] of ids.entries()) {
+                await db.execute(sql `INSERT INTO users (id, name, email) VALUES (${id}, ${`User${i}`}, ${`u${i}-${id}@test.com`})`);
+            }
+            const rows = await db.query(sql `SELECT name FROM users WHERE id = ANY(${ids}) ORDER BY name`);
+            assert.equal(rows.length, 3);
+            assert.equal(rows[0].name, 'User0');
+            assert.equal(rows[2].name, 'User2');
+            for (const id of ids)
+                await db.execute(sql `DELETE FROM users WHERE id = ${id}`);
+        });
+    });
+    // ── Transactions ────────────────────────────────────────────────────────
+    describe('transactions', () => {
+        it('commits atomically', async () => {
+            const a = uniqueId();
+            const b = uniqueId();
+            await db.execute(sql `INSERT INTO accounts (id, owner_id, balance) VALUES (${a}, ${'x'}, ${1000})`);
+            await db.execute(sql `INSERT INTO accounts (id, owner_id, balance) VALUES (${b}, ${'y'}, ${500})`);
+            await db.transaction(async (tx) => {
+                await tx.execute(sql `UPDATE accounts SET balance = balance - ${200} WHERE id = ${a}`);
+                await tx.execute(sql `UPDATE accounts SET balance = balance + ${200} WHERE id = ${b}`);
+            });
+            const accA = await db.queryOne(sql `SELECT balance FROM accounts WHERE id = ${a}`);
+            const accB = await db.queryOne(sql `SELECT balance FROM accounts WHERE id = ${b}`);
+            assert.equal(accA?.balance, 800);
+            assert.equal(accB?.balance, 700);
+            await db.execute(sql `DELETE FROM accounts WHERE id = ${a}`);
+            await db.execute(sql `DELETE FROM accounts WHERE id = ${b}`);
+        });
+        it('rolls back on error — no partial writes', async () => {
+            const id = uniqueId();
+            await db.execute(sql `INSERT INTO accounts (id, owner_id, balance) VALUES (${id}, ${'z'}, ${100})`);
+            await assert.rejects(() => db.transaction(async (tx) => {
+                await tx.execute(sql `UPDATE accounts SET balance = ${0} WHERE id = ${id}`);
+                throw new Error('Simulated failure');
+            }), /Simulated failure/);
+            const acc = await db.queryOne(sql `SELECT balance FROM accounts WHERE id = ${id}`);
+            assert.equal(acc?.balance, 100); // unchanged
+            await db.execute(sql `DELETE FROM accounts WHERE id = ${id}`);
+        });
+        it('returns value from transaction callback', async () => {
+            const id = uniqueId();
+            await db.execute(sql `INSERT INTO accounts (id, owner_id, balance) VALUES (${id}, ${'w'}, ${42})`);
+            const result = await db.transaction(async (tx) => {
+                const row = await tx.queryOne(sql `SELECT balance FROM accounts WHERE id = ${id}`);
+                return row.balance * 2;
+            });
+            assert.equal(result, 84);
+            await db.execute(sql `DELETE FROM accounts WHERE id = ${id}`);
+        });
+    });
+    // ── OCC Conflict & Retry ───────────────────────────────────────────────
+    describe('OCC conflict handling', () => {
+        it('throws SerializationFailureException without retry', async () => {
+            const id = uniqueId();
+            await db.execute(sql `INSERT INTO accounts (id, owner_id, balance) VALUES (${id}, ${'occ'}, ${50})`);
+            db.simulateConflict();
+            await assert.rejects(() => db.transaction(async (tx) => {
+                await tx.execute(sql `UPDATE accounts SET balance = ${99} WHERE id = ${id}`);
+            }), (e) => {
+                assert.equal(e.name, DistributedDatabaseErrors.SerializationFailure);
+                return true;
+            });
+            await db.execute(sql `DELETE FROM accounts WHERE id = ${id}`);
+        });
+        it('retryOnConflict recovers transparently', async () => {
+            const id = uniqueId();
+            await db.execute(sql `INSERT INTO accounts (id, owner_id, balance) VALUES (${id}, ${'occ2'}, ${10})`);
+            db.simulateConflict();
+            const result = await db.transaction(async (tx) => {
+                await tx.execute(sql `UPDATE accounts SET balance = balance + ${5} WHERE id = ${id}`);
+                return 'done';
+            }, { retryOnConflict: true });
+            assert.equal(result, 'done');
+            const acc = await db.queryOne(sql `SELECT balance FROM accounts WHERE id = ${id}`);
+            assert.equal(acc?.balance, 15);
+            await db.execute(sql `DELETE FROM accounts WHERE id = ${id}`);
+        });
+        it('respects maxRetries limit', async () => {
+            const id = uniqueId();
+            await db.execute(sql `INSERT INTO accounts (id, owner_id, balance) VALUES (${id}, ${'occ3'}, ${1})`);
+            // Simulate conflict on every attempt — should exhaust retries
+            let attempts = 0;
+            const origSimulate = db.simulateConflict.bind(db);
+            await assert.rejects(() => db.transaction(async (tx) => {
+                attempts++;
+                db.simulateConflict(); // re-arm for next attempt
+                await tx.execute(sql `UPDATE accounts SET balance = ${99} WHERE id = ${id}`);
+            }, { retryOnConflict: true, maxRetries: 2 }), (e) => {
+                assert.equal(e.name, DistributedDatabaseErrors.SerializationFailure);
+                return true;
+            });
+            // 1 initial + 2 retries = 3 attempts
+            assert.equal(attempts, 3);
+            await db.execute(sql `DELETE FROM accounts WHERE id = ${id}`);
+        });
+    });
+    // ── DSQL Validation Guardrails ─────────────────────────────────────────
+    describe('DSQL validation at query time', () => {
+        it('rejects FOREIGN KEY', async () => {
+            await assert.rejects(() => db.execute(sql `CREATE TABLE bad_fk (id TEXT, ref TEXT REFERENCES users(id))`), { name: 'DsqlValidationError' });
+        });
+        it('rejects SERIAL/BIGSERIAL', async () => {
+            await assert.rejects(() => db.execute(sql `CREATE TABLE bad_serial (id SERIAL PRIMARY KEY)`), { name: 'DsqlValidationError' });
+        });
+        it('rejects TRUNCATE', async () => {
+            await assert.rejects(() => db.execute(sql `TRUNCATE TABLE users`), { name: 'DsqlValidationError' });
+        });
+        it('rejects CREATE VIEW', async () => {
+            await assert.rejects(() => db.execute(sql `CREATE VIEW user_names AS SELECT name FROM users`), { name: 'DsqlValidationError' });
+        });
+        it('rejects CREATE TRIGGER', async () => {
+            await assert.rejects(() => db.execute(sql `CREATE TRIGGER t BEFORE INSERT ON users FOR EACH ROW EXECUTE FUNCTION f()`), { name: 'DsqlValidationError' });
+        });
+        it('rejects TEMP TABLE', async () => {
+            await assert.rejects(() => db.execute(sql `CREATE TEMP TABLE staging (id TEXT)`), { name: 'DsqlValidationError' });
+        });
+        // DDL is rejected outright in the app runtime (parity with prod
+        // dsql:DbConnect, which is DML-only), so any CREATE inside a normal
+        // transaction surfaces as DsqlPermissionError before the DDL/DML mixing
+        // rule is ever evaluated.
+        it('rejects DDL + DML in same transaction', async () => {
+            await assert.rejects(() => db.transaction(async (tx) => {
+                await tx.execute(sql `INSERT INTO users (id, name, email) VALUES (${'x'}, ${'X'}, ${'x@t.com'})`);
+                await tx.execute(sql `CREATE TABLE should_fail (id TEXT PRIMARY KEY)`);
+            }), { name: 'DsqlPermissionError' });
+        });
+        it('rejects multiple DDL in same transaction', async () => {
+            await assert.rejects(() => db.transaction(async (tx) => {
+                await tx.execute(sql `CREATE TABLE t1 (id TEXT PRIMARY KEY)`);
+                await tx.execute(sql `CREATE TABLE t2 (id TEXT PRIMARY KEY)`);
+            }), { name: 'DsqlPermissionError' });
+        });
+    });
+    // ── Error Translation ──────────────────────────────────────────────────
+    describe('error translation', () => {
+        it('unique constraint violation → UniqueConstraintViolationException', async () => {
+            const id = uniqueId();
+            await db.execute(sql `INSERT INTO users (id, name, email) VALUES (${id}, ${'First'}, ${`dup-${id}@test.com`})`);
+            await assert.rejects(() => db.execute(sql `INSERT INTO users (id, name, email) VALUES (${id}, ${'Second'}, ${`dup2-${id}@test.com`})`), (e) => {
+                assert.equal(e.name, DistributedDatabaseErrors.UniqueConstraintViolation);
+                return true;
+            });
+            await db.execute(sql `DELETE FROM users WHERE id = ${id}`);
+        });
+        it('unique constraint on email column', async () => {
+            const id1 = uniqueId();
+            const id2 = uniqueId();
+            const email = `shared-${uniqueId()}@test.com`;
+            await db.execute(sql `INSERT INTO users (id, name, email) VALUES (${id1}, ${'A'}, ${email})`);
+            await assert.rejects(() => db.execute(sql `INSERT INTO users (id, name, email) VALUES (${id2}, ${'B'}, ${email})`), (e) => {
+                assert.equal(e.name, DistributedDatabaseErrors.UniqueConstraintViolation);
+                return true;
+            });
+            await db.execute(sql `DELETE FROM users WHERE id = ${id1}`);
+        });
+    });
+    // ── Concurrent-style Scenarios ─────────────────────────────────────────
+    describe('realistic scenarios', () => {
+        it('bank transfer — debit and credit are atomic', async () => {
+            const alice = uniqueId();
+            const bob = uniqueId();
+            await db.execute(sql `INSERT INTO accounts (id, owner_id, balance) VALUES (${alice}, ${'alice'}, ${1000})`);
+            await db.execute(sql `INSERT INTO accounts (id, owner_id, balance) VALUES (${bob}, ${'bob'}, ${200})`);
+            await db.transaction(async (tx) => {
+                const sender = await tx.queryOne(sql `SELECT balance FROM accounts WHERE id = ${alice}`);
+                if (!sender || sender.balance < 300)
+                    throw new Error('Insufficient funds');
+                await tx.execute(sql `UPDATE accounts SET balance = balance - ${300} WHERE id = ${alice}`);
+                await tx.execute(sql `UPDATE accounts SET balance = balance + ${300} WHERE id = ${bob}`);
+            });
+            const a = await db.queryOne(sql `SELECT balance FROM accounts WHERE id = ${alice}`);
+            const b = await db.queryOne(sql `SELECT balance FROM accounts WHERE id = ${bob}`);
+            assert.equal(a?.balance, 700);
+            assert.equal(b?.balance, 500);
+            await db.execute(sql `DELETE FROM accounts WHERE id = ${alice}`);
+            await db.execute(sql `DELETE FROM accounts WHERE id = ${bob}`);
+        });
+        it('insufficient funds — transaction aborts cleanly', async () => {
+            const acc = uniqueId();
+            await db.execute(sql `INSERT INTO accounts (id, owner_id, balance) VALUES (${acc}, ${'poor'}, ${10})`);
+            await assert.rejects(() => db.transaction(async (tx) => {
+                const row = await tx.queryOne(sql `SELECT balance FROM accounts WHERE id = ${acc}`);
+                if (!row || row.balance < 1000)
+                    throw new Error('Insufficient funds');
+                await tx.execute(sql `UPDATE accounts SET balance = balance - ${1000} WHERE id = ${acc}`);
+            }), /Insufficient funds/);
+            const row = await db.queryOne(sql `SELECT balance FROM accounts WHERE id = ${acc}`);
+            assert.equal(row?.balance, 10); // unchanged
+            await db.execute(sql `DELETE FROM accounts WHERE id = ${acc}`);
+        });
+        it('batch insert with unique IDs', async () => {
+            const ids = [];
+            for (let i = 0; i < 10; i++) {
+                const id = uniqueId();
+                ids.push(id);
+                await db.execute(sql `INSERT INTO accounts (id, owner_id, balance) VALUES (${id}, ${`owner-${i}`}, ${i * 100})`);
+            }
+            const rows = await db.query(sql `SELECT balance FROM accounts WHERE id = ANY(${ids}) ORDER BY balance`);
+            assert.equal(rows.length, 10);
+            assert.equal(rows[0].balance, 0);
+            assert.equal(rows[9].balance, 900);
+            for (const id of ids)
+                await db.execute(sql `DELETE FROM accounts WHERE id = ${id}`);
+        });
+        it('read-after-write consistency within transaction', async () => {
+            const id = uniqueId();
+            await db.execute(sql `INSERT INTO accounts (id, owner_id, balance) VALUES (${id}, ${'rw'}, ${0})`);
+            await db.transaction(async (tx) => {
+                await tx.execute(sql `UPDATE accounts SET balance = ${500} WHERE id = ${id}`);
+                const row = await tx.queryOne(sql `SELECT balance FROM accounts WHERE id = ${id}`);
+                assert.equal(row?.balance, 500); // sees own write
+            });
+            await db.execute(sql `DELETE FROM accounts WHERE id = ${id}`);
+        });
+    });
+});

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

@@ -0,0 +1,26 @@
+import type { DatabaseEngine, TransactionHandle } from '@aws-blocks/data-common';
+export interface DsqlEngineConfig {
+    endpoint: string;
+    region: string;
+    getAuthToken: () => Promise<string>;
+    poolSize?: number;
+    /** PostgreSQL role name to connect as (mapped from IAM via `AWS IAM GRANT`). */
+    role: string;
+}
+export declare class DsqlEngine implements DatabaseEngine {
+    private pool;
+    constructor(config: DsqlEngineConfig);
+    query<T>(sql: string, params?: unknown[]): Promise<T[]>;
+    execute(sql: string, params?: unknown[]): Promise<{
+        rowCount: number;
+    }>;
+    beginTransaction(): Promise<TransactionHandle>;
+    commitTransaction(handle: TransactionHandle): Promise<void>;
+    rollbackTransaction(handle: TransactionHandle): Promise<void>;
+    queryInTransaction<T>(handle: TransactionHandle, sql: string, params?: unknown[]): Promise<T[]>;
+    executeInTransaction(handle: TransactionHandle, sql: string, params?: unknown[]): Promise<{
+        rowCount: number;
+    }>;
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=dsql-engine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dsql-engine.d.ts","sourceRoot":"","sources":["../../src/engines/dsql-engine.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAIjF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,UAAW,YAAW,cAAc;IAC/C,OAAO,CAAC,IAAI,CAAU;gBAEV,MAAM,EAAE,gBAAgB;IAc9B,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IASvD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IASvE,gBAAgB,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAY9C,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAY3D,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAU7D,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAS/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;IAS/G,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAC/B"}

package/dist/engines/dsql-engine.js

@@ -0,0 +1,103 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Production DSQL engine — pg.Pool with IAM token authentication.
+ */
+import pg from 'pg';
+import { translateDsqlError } from '../errors.js';
+import { DEFAULT_POOL_SIZE } from '../constants.js';
+export class DsqlEngine {
+    pool;
+    constructor(config) {
+        // DSQL clusters have a fixed connection contract: port 5432,
+        // database 'postgres', TLS required.
+        this.pool = new pg.Pool({
+            host: config.endpoint,
+            port: 5432,
+            user: config.role,
+            database: 'postgres',
+            ssl: true,
+            max: config.poolSize ?? DEFAULT_POOL_SIZE,
+            password: config.getAuthToken,
+        });
+    }
+    async query(sql, params) {
+        try {
+            return (await this.pool.query(sql, params)).rows;
+        }
+        catch (e) {
+            const err = e;
+            console.error('[DsqlEngine] query failed', { code: err.code, severity: err.severity });
+            translateDsqlError(err);
+        }
+    }
+    async execute(sql, params) {
+        try {
+            return { rowCount: (await this.pool.query(sql, params)).rowCount ?? 0 };
+        }
+        catch (e) {
+            const err = e;
+            console.error('[DsqlEngine] execute failed', { code: err.code, severity: err.severity });
+            translateDsqlError(err);
+        }
+    }
+    async beginTransaction() {
+        try {
+            const client = await this.pool.connect();
+            await client.query('BEGIN');
+            return client;
+        }
+        catch (e) {
+            const err = e;
+            console.error('[DsqlEngine] beginTransaction failed', { code: err.code, severity: err.severity });
+            translateDsqlError(err);
+        }
+    }
+    async commitTransaction(handle) {
+        const client = handle;
+        try {
+            await client.query('COMMIT');
+        }
+        catch (e) {
+            client.release();
+            const err = e;
+            console.error('[DsqlEngine] commitTransaction failed', { code: err.code, severity: err.severity });
+            translateDsqlError(err);
+        }
+        client.release();
+    }
+    async rollbackTransaction(handle) {
+        const client = handle;
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch (e) {
+            const err = e;
+            console.error('[DsqlEngine] rollbackTransaction failed', { code: err.code, severity: err.severity });
+        }
+        finally {
+            client.release();
+        }
+    }
+    async queryInTransaction(handle, sql, params) {
+        try {
+            return (await handle.query(sql, params)).rows;
+        }
+        catch (e) {
+            const err = e;
+            console.error('[DsqlEngine] queryInTransaction failed', { code: err.code, severity: err.severity });
+            translateDsqlError(err);
+        }
+    }
+    async executeInTransaction(handle, sql, params) {
+        try {
+            return { rowCount: (await handle.query(sql, params)).rowCount ?? 0 };
+        }
+        catch (e) {
+            const err = e;
+            console.error('[DsqlEngine] executeInTransaction failed', { code: err.code, severity: err.severity });
+            translateDsqlError(err);
+        }
+    }
+    async destroy() { await this.pool.end(); }
+}