feat(db): add drizzle-kit generate workflow with DSQL compatibility check

- Add drizzle-kit as devDependency with drizzle.config.ts
- Add check-dsql-compat.ts validator (runs after generate)
- Add 'generate' pnpm script: drizzle-kit generate && check
- Initialize drizzle-kit snapshot from existing 0001_initial.sql
- Document schema change workflow in AGENTS.md

Author: konokenj

AGENTS.md

@@ -60,7 +60,27 @@ DSQL constraints:
 
 Migrations are SQL files in `packages/db/migrations/`. The migration runner is invoked automatically during `cdk deploy` via CDK Trigger. For manual invocation, use the `MigrationCommand` from CDK outputs.
 
-Schema changes: edit `packages/db/src/schema.ts` → generate migration SQL → place in `packages/db/migrations/` → commit. Each SQL statement must be separated by a blank line (the runner splits on `\n\n`).
+Schema changes:
+
+```bash
+# 1. Edit schema
+#    packages/db/src/schema.ts
+
+# 2. Generate migration SQL + DSQL compatibility check
+pnpm --filter @repo/db run generate
+
+# 3. Review and fix the generated SQL in packages/db/migrations/
+#    - Add IF NOT EXISTS for idempotency
+#    - Replace CREATE INDEX with CREATE INDEX ASYNC
+#    - Replace --> statement-breakpoint with blank lines (runner splits on \n\n)
+
+# 4. Apply to dev cluster
+pnpm --filter @repo/db run migrate
+
+# 5. Commit schema + migration + snapshot together
+```
+
+Do not use `drizzle-kit push` or `drizzle-kit migrate` — DSQL requires 1 DDL per transaction. The custom runner (`pnpm run migrate`) handles this.
 
 ### Lambda environment
 

packages/db/drizzle.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+  dialect: 'postgresql',
+  schema: './src/schema.ts',
+  out: './migrations',
+  // No dbCredentials — generate is schema-diff only, no DB connection needed.
+  // Do not use drizzle-kit push/migrate — DSQL requires 1 DDL per transaction.
+  // Use `pnpm run migrate` (custom runner) to apply migrations.
+});

packages/db/migrations/meta/0001_snapshot.json

@@ -0,0 +1,97 @@
+{
+  "id": "beb16dd9-127f-4aa6-b85f-1def0450252c",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.TodoItem": {
+      "name": "TodoItem",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "userId": {
+          "name": "userId",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'PENDING'"
+        },
+        "createdAt": {
+          "name": "createdAt",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updatedAt": {
+          "name": "updatedAt",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.User": {
+      "name": "User",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

packages/db/migrations/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1774012279412,
+      "tag": "0001_initial",
+      "breakpoints": true
+    }
+  ]
+}

packages/db/package.json

@@ -9,6 +9,7 @@
     "./migrate": "./src/migrate.ts"
   },
   "scripts": {
+    "generate": "drizzle-kit generate && tsx src/check-dsql-compat.ts",
     "migrate": "tsx --env-file=.env src/cli.ts",
     "format": "oxfmt --write .",
     "format:ci": "oxfmt --check .",
@@ -24,6 +25,7 @@
   },
   "devDependencies": {
     "@types/pg": "^8",
+    "drizzle-kit": "^0.31.10",
     "tsx": "^4",
     "typescript": "^5"
   }

packages/db/src/check-dsql-compat.ts

@@ -0,0 +1,36 @@
+// Validate migration SQL files for DSQL compatibility.
+// Run after drizzle-kit generate to catch incompatible DDL before commit.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const migrationsDir = path.join(__dirname, '..', 'migrations');
+
+const rules: { pattern: RegExp; message: string }[] = [
+  { pattern: /CREATE\s+INDEX\s+(?!.*ASYNC)/i, message: 'CREATE INDEX must use ASYNC keyword' },
+  { pattern: /REFERENCES\s+/i, message: 'FOREIGN KEY / REFERENCES not supported' },
+  { pattern: /FOREIGN\s+KEY/i, message: 'FOREIGN KEY not supported' },
+  { pattern: /ALTER\s+.*\s+TYPE\s+/i, message: 'ALTER COLUMN TYPE not supported' },
+  { pattern: /DROP\s+COLUMN/i, message: 'DROP COLUMN not supported' },
+  { pattern: /\bSERIAL\b/i, message: 'SERIAL types not supported (use UUID)' },
+];
+
+const files = fs.readdirSync(migrationsDir).filter((f) => f.endsWith('.sql'));
+let errors = 0;
+
+for (const file of files) {
+  const content = fs.readFileSync(path.join(migrationsDir, file), 'utf8');
+  for (const { pattern, message } of rules) {
+    if (pattern.test(content)) {
+      console.error(`ERROR: ${file} — ${message}`);
+      errors++;
+    }
+  }
+}
+
+if (errors > 0) {
+  console.error(`\n${errors} DSQL compatibility error(s). Fix the SQL before committing.`);
+  process.exit(1);
+}
+console.log('All migration files DSQL-compatible.');