@aws-blocks/bb-distributed-data 0.1.1 → 0.1.3

package/DESIGN.md

@@ -0,0 +1,205 @@
+# DistributedDatabase — Design
+
+Design document for the DistributedDatabase Building Block. For usage, see [README.md](./README.md).
+
+**Package:** `@aws-blocks/bb-distributed-data`
+**Type:** Primitive (new infrastructure)
+**AWS Service:** Amazon Aurora DSQL
+
+## Architecture
+
+```
+data-common (shared abstractions)
+    ├── DatabaseEngine interface
+    ├── DatabaseBase class
+    ├── sql tagged template + SqlQuery
+    ├── Kysely adapter
+    └── splitStatements()
+
+bb-distributed-data (this package)
+    ├── DsqlEngine (AWS — pg.Pool + IAM token auth)
+    ├── DsqlMockEngine (local — PGlite + validation layer)
+    ├── Validation layer (DSQL compatibility checks)
+    ├── TransactionTracker (DDL/DML/row-limit enforcement)
+    ├── DSQL-specific migration runner
+    └── CDK construct (CfnResource + migration CustomResource)
+```
+
+## Why a Separate Block (Not an Engine Flag on Database)
+
+1. **Transaction semantics differ** — OCC means callbacks may need retry. Different API contract.
+2. **Feature set is a strict subset** — FK, RLS, triggers, views absent. An engine flag hides this until deploy time.
+3. **Mock parity goes in opposite directions** — PGlite is too permissive for DSQL. A separate block can have a restrictive mock.
+4. **"When to use" guidance is completely different** — customers shouldn't accidentally pick DSQL.
+5. **Multi-region is a first-class capability** — not a bolt-on option.
+
+## Engine Implementations
+
+### DsqlEngine (AWS Runtime)
+
+- `pg.Pool` with IAM token authentication via `@aws-sdk/dsql-signer`
+- Password callback generates fresh tokens per connection (60-min expiry)
+- Translates pg error codes to `DistributedDatabaseErrors` names
+- Pool handles reconnection transparently when connections expire
+
+### DsqlMockEngine (Local Dev)
+
+- PGlite wrapped with a validation layer
+- `validateStatement()` rejects unsupported SQL before execution
+- `TransactionTracker` enforces DDL/DML separation and 3,000-row limit
+- `simulateConflict()` test helper for OCC testing
+- Error translation matches production behavior
+
+## Validation Layer
+
+The core insight: PGlite supports everything DSQL doesn't. Without validation, code works locally but breaks in production — the worst failure mode. The mock actively restricts PGlite to match DSQL's subset.
+
+### Statement Validation
+
+`validateStatement(sql)` strips string literals and comments, then checks regex patterns:
+
+| Pattern | Rejects |
+|---------|---------|
+| `FOREIGN KEY` / `REFERENCES` | FK constraints |
+| `CREATE TRIGGER` | Triggers |
+| `CREATE VIEW` | Views |
+| `LANGUAGE plpgsql` | PL/pgSQL functions |
+| `SERIAL` / `BIGSERIAL` | Sequences |
+| `TRUNCATE` | Use DELETE FROM |
+| `LISTEN` / `NOTIFY` | Async notifications |
+| `CREATE EXTENSION` | Extensions |
+| `ADD COLUMN ... DEFAULT` | Column default on ALTER |
+| `ALTER DEFAULT PRIVILEGES` | Not supported by DSQL |
+| `CREATE POLICY` / `ENABLE ROW LEVEL SECURITY` | RLS |
+| `CREATE TEMP TABLE` | Temporary tables |
+| `SET TRANSACTION ISOLATION LEVEL` | Fixed Repeatable Read |
+| `COLLATE` | C collation only |
+| `CREATE INDEX ... ASC/DESC` | Sort direction on index keys (NULLS FIRST/LAST is allowed) |
+
+### Transaction Tracking
+
+`TransactionTracker` enforces per-transaction constraints:
+
+- Max 1 DDL statement per transaction
+- Cannot mix DDL and DML in the same transaction
+- Max 3,000 rows mutated (cumulative across all executes)
+
+### Migration Validation
+
+`validateMigrations()` checks all files upfront before running any:
+
+- Each file: max 1 DDL statement
+- Each file: no DDL + DML mixing
+- All statements pass `validateStatement()`
+
+## Migration Runner
+
+DSQL's migration runner differs from the generic one in `data-common`:
+
+- **DDL files** run as implicit transactions (no explicit BEGIN/COMMIT) — DSQL auto-commits DDL
+- **DML files** run in explicit transactions (atomic)
+- `validateMigrations()` runs upfront — catches errors before any SQL executes
+- Uses `gen_random_uuid()` for `_migrations.id` (no SERIAL)
+
+## OCC Retry Logic
+
+```typescript
+async transaction<T>(fn, options?) {
+  const maxAttempts = options?.retryOnConflict ? (options.maxRetries ?? 3) + 1 : 1;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await this.base.transaction(fn);
+    } catch (e) {
+      const isOcc = e.code === '40001' || e.name === 'SerializationFailureException';
+      if (isOcc && attempt < maxAttempts) continue;
+      throw e;
+    }
+  }
+}
+```
+
+Default: no retry (honest, predictable). `retryOnConflict: true` is explicit opt-in with JSDoc warning about side effects.
+
+## Error Translation
+
+Happens in the engine layer (same pattern as bb-data engines):
+
+| pg error code | DistributedDatabaseErrors name |
+|---------------|------------------------|
+| `40001` | `SerializationFailure` |
+| `23505` | `UniqueConstraintViolation` |
+| `08xxx` | `ConnectionFailed` |
+| (other) | `QueryFailed` |
+
+The `DistributedDatabase` class does not wrap errors — engines handle translation.
+
+## Infrastructure (CDK)
+
+| Resource | Purpose |
+|----------|---------|
+| `AWS::DSQL::Cluster` (CfnResource) | DSQL cluster |
+| Migration Lambda (NodejsFunction) | Runs .sql files on deploy |
+| CustomResource + Provider | Triggers migration on deploy |
+| IAM PolicyStatement | `dsql:DbConnect` (app Lambda), `dsql:DbConnectAdmin` (migration Lambda) |
+| CfnOutput | Cluster endpoint |
+
+### Deletion Protection
+
+`DeletionProtectionEnabled` is computed from `removalPolicy`:
+- `destroy` or `sandboxMode=true` → disabled
+- Otherwise → enabled
+
+### Migration Lambda
+
+- Connects via `pg.Client` + `DsqlSigner.getDbConnectAdminAuthToken()`
+- Retries with exponential backoff on transient connection errors (cluster may take a moment after creation)
+- `.sql` files bundled into the Lambda package via CDK `commandHooks`
+- `migrationsHash` property triggers re-invocation when files change
+- **Provisions custom DB role** on every deploy (idempotent):
+  1. `CREATE ROLE "app_role" WITH LOGIN` (if not exists)
+  2. `AWS IAM GRANT "app_role" TO 'arn:aws:iam::...:role/...'` (maps IAM to DB role)
+  3. Per-table `GRANT SELECT, INSERT, UPDATE, DELETE` on user-created tables
+
+### DSQL Permission Model Limitations
+
+- `ALTER DEFAULT PRIVILEGES` — not supported (system entity error)
+- `GRANT ... ON ALL TABLES IN SCHEMA public` — not supported (`public` is a system entity)
+- `GRANT USAGE ON SCHEMA public` — not supported (same reason)
+- Handled by enumerating user tables via `pg_tables` and granting DML individually on each deploy
+
+## Mock vs AWS Behavior Differences
+
+| Behavior Difference | Impact | Mitigation |
+|------------|--------|------------|
+| No real OCC conflicts | Single-connection PGlite has no concurrency | `simulateConflict()` test helper |
+| PGlite supports JSONB columns | DSQL rejects JSONB as a column type (use JSON instead; JSONB available as runtime cast only) | Validator rejects JSONB in DDL |
+| System collation vs C only | String sorting may differ | Reject explicit COLLATE |
+| No 60-min connection timeout | Dev sessions are short | Document only |
+| No 10 MiB / 5-min tx limits | Impractical to measure locally | Document only |
+| CREATE INDEX ASYNC is synchronous | Index immediately available locally | Log warning |
+
+## Connection Management
+
+DSQL uses IAM token authentication:
+- **App Lambda**: `DsqlSigner.getDbConnectAuthToken()` (DML only)
+- **Migration Lambda**: `DsqlSigner.getDbConnectAdminAuthToken()` (DDL)
+- `pg.Pool` with password callback (fresh token per connection)
+- 60-min connection timeout — transparent to Lambda (short-lived)
+- No secrets, no VPC, no proxy needed
+
+## Relationship to data-common
+
+`bb-distributed-data` uses `DatabaseBase` from `data-common` directly (no subclass). Error translation is in the engine. This is the cleaner pattern — `bb-data` subclasses `DatabaseBase` only because it adds RLS support.
+
+Shared from `data-common`:
+- `DatabaseEngine` / `DatabaseBase` / `TransactionHandle`
+- `sql` / `SqlQuery` / `unwrapQuery`
+- `createKyselyAdapter`
+- `splitStatements`
+
+DSQL-specific (not shared):
+- `validateStatement` / `classifyStatement` / `TransactionTracker`
+- `validateMigrations`
+- `DsqlEngine` / `DsqlMockEngine`
+- `DistributedDatabaseErrors`
+- OCC retry logic

package/README.md

@@ -6,6 +6,8 @@ Serverless SQL database backed by Amazon Aurora DSQL. Zero-ops, instant provisio
 
 **When NOT to use:** If you need foreign keys, Row Level Security, triggers, views, or stored procedures — use `Database` (Aurora). If you need transactions that must not fail at commit under contention — use `Database`. If you're connecting to Supabase — use `Database` with `fromExisting()`.
 
+> Design & mock parity details: [DESIGN.md](./DESIGN.md)
+
 ## Quick Start
 
 ```typescript
@@ -106,6 +108,7 @@ DSQL is a subset of PostgreSQL. The local mock enforces these restrictions so co
 | LISTEN / NOTIFY | AppSync Events, EventBridge, or polling |
 | Extensions | Not available |
 | ADD COLUMN with DEFAULT | Add column without default, handle nulls in app |
+| Index key sort direction (`ASC`/`DESC`) | Omit it; enforce ordering with `ORDER BY` in queries (`NULLS FIRST/LAST` is supported) |
 
 ### Transaction Constraints
 

package/dist/e2e-mock.test.js

@@ -154,6 +154,9 @@ describe('DsqlMockEngine — CREATE INDEX ASYNC parity', () => {
     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('rejects CREATE INDEX ASYNC with a DESC sort order on a key', async () => {
+        await assert.rejects(() => engine.withDdl(() => db.execute(sql `CREATE INDEX ASYNC idx_users_email_desc ON users (email DESC)`)), /sort order/i);
+    });
     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})`);

package/dist/validation.d.ts.map

@@ -1 +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"}
+{"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;AA6BD,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"}

package/dist/validation.js

@@ -80,6 +80,13 @@ const RULES = [
     { pattern: /\bCOLLATE\b/i, message: 'DSQL only supports C collation.', severity: 'error' },
     { pattern: /(?<!::)\bJSONB\b/i, message: 'DSQL does not support JSONB columns. Use JSON instead (JSONB is available as a query runtime cast via ::jsonb).', severity: 'error' },
     { pattern: /(@>|<@|\?\||\?&)/, message: 'JSONB operators lack GIN index acceleration in DSQL.', severity: 'warn' },
+    // DSQL rejects a sort direction (ASC/DESC) on index keys — it isn't in the
+    // CREATE INDEX ASYNC grammar (only `NULLS FIRST|LAST`, which IS supported, is).
+    // `[^;]*` keeps the match inside a single statement; ASC/DESC cannot otherwise
+    // appear in a CREATE INDEX. Caveat: stripLiteralsAndComments doesn't strip
+    // double-quoted identifiers, so a column literally named "desc"/"asc" would
+    // false-positive — niche, and shared with other single-keyword rules here.
+    { pattern: /\bCREATE\s+(?:UNIQUE\s+)?INDEX\b[^;]*\b(?:ASC|DESC)\b/i, message: 'DSQL does not support sort order (ASC/DESC) on index keys. Remove it — ordering is enforced by ORDER BY in queries (NULLS FIRST/LAST is allowed). (DSQL: "specifying sort order not supported for index keys")', severity: 'error' },
 ];
 /** Validate a SQL statement for DSQL compatibility. Throws on unsupported features. */
 export function validateStatement(sql) {

package/dist/validation.test.js

@@ -352,3 +352,30 @@ describe('validateStatement — unsupported features after bind parameters', ()
         assert.doesNotThrow(() => validateStatement("INSERT INTO audit (id, action) VALUES ($1, 'TRUNCATE')"));
     });
 });
+describe('validateStatement — index key sort order', () => {
+    it('rejects DESC on an index key', () => {
+        assert.throws(() => validateStatement('CREATE INDEX idx ON persons (user_id, last_encounter_at DESC)'), /sort order/i);
+    });
+    it('rejects DESC on a CREATE INDEX ASYNC key', () => {
+        assert.throws(() => validateStatement('CREATE INDEX ASYNC idx_persons_user_recent ON persons (user_id, last_encounter_at DESC)'), /sort order/i);
+    });
+    it('rejects an explicit ASC on an index key', () => {
+        assert.throws(() => validateStatement('CREATE INDEX idx ON t (col ASC)'), /sort order/i);
+    });
+    it('allows NULLS FIRST / NULLS LAST on an index key (supported by DSQL)', () => {
+        assert.doesNotThrow(() => validateStatement('CREATE INDEX ASYNC idx ON t (col NULLS FIRST)'));
+        assert.doesNotThrow(() => validateStatement('CREATE INDEX ASYNC idx ON t (col NULLS LAST)'));
+    });
+    it('allows a plain CREATE INDEX without sort order', () => {
+        assert.doesNotThrow(() => validateStatement('CREATE INDEX idx ON persons (user_id, last_encounter_at)'));
+    });
+    it('allows a partial index whose WHERE mentions a column like "description"', () => {
+        assert.doesNotThrow(() => validateStatement('CREATE INDEX idx ON t (name) WHERE description IS NOT NULL'));
+    });
+    it('allows an expression index without sort order', () => {
+        assert.doesNotThrow(() => validateStatement('CREATE INDEX idx ON t ((lower(name)))'));
+    });
+    it('does not flag ORDER BY ... DESC in a SELECT (no false positive outside CREATE INDEX)', () => {
+        assert.doesNotThrow(() => validateStatement('SELECT * FROM persons ORDER BY last_encounter_at DESC'));
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-blocks/bb-distributed-data",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "author": "Amazon Web Services",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,7 +29,7 @@
   "dependencies": {
     "@aws-blocks/core": "^0.1.1",
     "@aws-blocks/data-common": "^0.1.1",
-    "@aws-blocks/bb-logger": "^0.1.1",
+    "@aws-blocks/bb-logger": "^0.1.2",
     "@aws-sdk/dsql-signer": "^3.700.0",
     "@electric-sql/pglite": "^0.2.0",
     "pg": "^8.13.0"