fix(bb-distributed-data): reject index key sort order (ASC/DESC) for DSQL (#148)

Author: fossamagna

.changeset/dsql-index-sort-order.md

@@ -0,0 +1,5 @@
+---
+"@aws-blocks/bb-distributed-data": patch
+---
+
+Reject index key sort direction (`ASC`/`DESC`) in `CREATE INDEX` at dev time. DSQL does not allow a sort direction on index keys ("specifying sort order not supported for index keys"), but the PGlite-based local mock previously accepted it, so the error only surfaced on deploy. Migration and mock validation now fail locally instead. (`NULLS FIRST/LAST` is supported by DSQL and is not rejected.)

packages/bb-distributed-data/DESIGN.md

@@ -74,6 +74,7 @@ The core insight: PGlite supports everything DSQL doesn't. Without validation, c
 | `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
 

packages/bb-distributed-data/README.md

@@ -108,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
 

packages/bb-distributed-data/src/e2e-mock.test.ts

@@ -207,6 +207,13 @@ describe('DsqlMockEngine — CREATE INDEX ASYNC parity', () => {
     );
   });
 
+  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})`);

packages/bb-distributed-data/src/validation.test.ts

@@ -500,3 +500,44 @@ 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'));
+  });
+});

packages/bb-distributed-data/src/validation.ts

@@ -85,6 +85,13 @@ const RULES: ValidationRule[] = [
   { 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. */