refactor: rewrite DSQL cluster management in TypeScript and add Name tags

The bash script (scripts/dsql.sh) required jq and AWS CLI, making it
platform-dependent. Rewrite as packages/db/src/cluster-cli.ts using
@aws-sdk/client-dsql with idempotent create, SDK waiter, resource
tagging, and a status subcommand. Rename cli.ts to migrate-cli.ts
for clarity.

Add Name tag to CDK-managed DSQL cluster for console identification.

Document Drizzle findMany() alias pitfall in AGENTS.md and
migration-prompt.ja.md — db.query.*.findMany() with exists()
subqueries causes alias errors on DSQL (drizzle-orm#3068).

Author: konokenj

.serverless-full-stack-webapp-starter-kit/docs/v3.0.0/migration-prompt.ja.md

@@ -41,7 +41,7 @@
 | `packages/db/src/client.ts`              | Proxy 遅延初期化 + globalThis シングルトン |
 | `packages/db/src/migrate.ts`             | マイグレーションランナーコアロジック       |
 | `packages/db/src/dsql-compat.ts`         | SQL 変換 + バリデーション                  |
-| `packages/db/src/cli.ts`                 | CLI エントリポイント                       |
+| `packages/db/src/migrate-cli.ts`         | マイグレーション CLI エントリポイント      |
 | `packages/db/src/check-dsql-compat.ts`   | drizzle-kit generate 後処理                |
 | `packages/db/drizzle.config.ts`          | —                                          |
 | `packages/db/package.json`               | —                                          |
@@ -50,7 +50,7 @@
 | `packages/shared-types/tsconfig.json`    | —                                          |
 | `apps/cdk/lib/constructs/database.ts`    | DSQL CfnCluster + IAM 認証                 |
 | `apps/cdk/lib/constructs/dsql-migrator/` | Dockerfile, handler.ts, index.ts 一式      |
-| `scripts/dsql.sh`                        | 開発用 DSQL クラスタの作成・削除           |
+| `packages/db/src/cluster-cli.ts`         | 開発用 DSQL クラスタの作成・削除           |
 
 以下はユーザー固有の変換が必要なため、コピーではなく手書き・変換する:
 
@@ -229,6 +229,7 @@ pnpm --filter @repo/db run generate
 - `next.config.ts` に `transpilePackages: ['@repo/db', '@repo/shared-types']` を追加（ユーザーの既存設定を保持しつつマージ）
 - **Json カラムの全使用箇所を洗い出す**（`rg 'Json|\.json\b' --type ts` でスキーマ定義と読み書き箇所を特定）。Prisma は Json 型を自動で parse/stringify するが、Drizzle の `text()` は手動変換が必要。読み出し時に `JSON.parse()`、書き込み時に `JSON.stringify()` を追加すること
 - **Prisma の nested create（暗黙トランザクション）を `db.transaction()` に変換する。** 特に `onDelete: Cascade` に依存していた削除ロジックは、`db.transaction()` 内で子テーブルを先に削除してから親テーブルを削除するように書き換えること
+- **`db.query.*.findMany()` を `exists()`/`notExists()` サブクエリと組み合わせないこと。** `findMany()` は内部でテーブルにエイリアスを付与するが、`where`/`extras` 内のカラム参照は元テーブル名で展開されるため `invalid reference to FROM-clause entry for table` エラーになる。`db.select().from().leftJoin()` に書き換えること。`findFirst()` はサブクエリなしなら安全。詳細は drizzle-team/drizzle-orm#3068
 
 ### 3-5. クリーンアップ
 
@@ -238,10 +239,10 @@ pnpm --filter @repo/db run generate
 
 ### 3-6. 開発用 DSQL クラスタでの検証
 
-本番データベースに触れる前に、開発用 DSQL クラスタでスキーマとアプリコードの動作を検証する。v3 キットの `scripts/dsql.sh` を使う:
+本番データベースに触れる前に、開発用 DSQL クラスタでスキーマとアプリコードの動作を検証する。v3 キットの `packages/db` の cluster コマンドを使う:
 
 ```bash
-bash scripts/dsql.sh create --region <region>
+pnpm --filter @repo/db run cluster create --region <region>
 ```
 
 このスクリプトは開発用 DSQL クラスタを作成し、`packages/db/.env` に接続情報を自動で書き込む。
@@ -262,7 +263,7 @@ bash scripts/dsql.sh create --region <region>
 
 ```bash
 # Phase 5 完了後に実行
-bash scripts/dsql.sh delete --region <region>
+pnpm --filter @repo/db run cluster delete --region <region>
 ```
 
 ### チェックポイント

AGENTS.md

@@ -24,7 +24,7 @@ pnpm --filter @repo/db run migrate
 pnpm run lint
 
 # local development (requires DSQL cluster)
-bash scripts/dsql.sh create             # create dev DSQL cluster
+pnpm --filter @repo/db run cluster create   # create dev DSQL cluster
 cd apps/webapp && pnpm run dev
 ```
 
@@ -60,6 +60,8 @@ DSQL constraints:
 - 1 DDL per transaction
 - ALTER TABLE only supports: ADD COLUMN, RENAME COLUMN/TABLE/CONSTRAINT, SET SCHEMA, OWNER TO, and IDENTITY operations. Everything else (DROP COLUMN, ALTER COLUMN TYPE, SET/DROP NOT NULL, SET/DROP DEFAULT, DROP CONSTRAINT) requires table recreation.
 
+- `db.query.*.findMany()` with `exists()`/`sql` subqueries causes alias errors on DSQL (drizzle-team/drizzle-orm#3068). Use `db.select().from()` instead. `findFirst()` is safe.
+
 ### Database migration
 
 See `packages/db/README.md` for full usage. Key rules:

apps/cdk/lib/constructs/database.ts

@@ -30,6 +30,7 @@ export class Database extends Construct {
 
     const cluster = new CfnCluster(this, 'Cluster', {
       deletionProtectionEnabled,
+      tags: [{ key: 'Name', value: `${Stack.of(this).stackName}-dsql` }],
     });
     cluster.applyRemovalPolicy(removalPolicy);
 

apps/cdk/test/__snapshots__/serverless-fullstack-webapp-starter-kit-without-domain.test.ts.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+// Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`Snapshot test 1`] = `
 {
@@ -1597,6 +1597,12 @@ exports[`Snapshot test 2`] = `
       "DeletionPolicy": "RetainExceptOnCreate",
       "Properties": {
         "DeletionProtectionEnabled": false,
+        "Tags": [
+          {
+            "Key": "Name",
+            "Value": "ServerlessWebappStarterKitStack-dsql",
+          },
+        ],
       },
       "Type": "AWS::DSQL::Cluster",
       "UpdateReplacePolicy": "Retain",

apps/cdk/test/__snapshots__/serverless-fullstack-webapp-starter-kit.test.ts.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+// Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`Snapshot test 1`] = `
 {
@@ -1513,6 +1513,12 @@ exports[`Snapshot test 2`] = `
       "DeletionPolicy": "RetainExceptOnCreate",
       "Properties": {
         "DeletionProtectionEnabled": false,
+        "Tags": [
+          {
+            "Key": "Name",
+            "Value": "ServerlessWebappStarterKitStack-dsql",
+          },
+        ],
       },
       "Type": "AWS::DSQL::Cluster",
       "UpdateReplacePolicy": "Retain",

packages/db/README.md

@@ -94,7 +94,7 @@ DSQL_ENDPOINT=<cluster>.dsql.<region>.on.aws
 AWS_REGION=<region>
 ```
 
-Or use `scripts/dsql.sh create --region <region>` from the repo root to provision a dev cluster and write `.env` automatically.
+Or use `pnpm --filter @repo/db run cluster create --region <region>` to provision a dev cluster and write `.env` automatically.
 
 ## Testing
 

packages/db/package.json

@@ -10,7 +10,8 @@
   },
   "scripts": {
     "generate": "drizzle-kit generate && tsx src/check-dsql-compat.ts",
-    "migrate": "tsx --env-file=.env src/cli.ts",
+    "migrate": "tsx --env-file=.env src/migrate-cli.ts",
+    "cluster": "tsx src/cluster-cli.ts",
     "test:unit": "vitest run --exclude '**/*.integ.test.ts'",
     "test:integ": "vitest run --config vitest.integ.config.ts",
     "test:watch": "vitest --exclude '**/*.integ.test.ts'",
@@ -27,6 +28,7 @@
     "pg": "^8"
   },
   "devDependencies": {
+    "@aws-sdk/client-dsql": "^3",
     "@types/pg": "^8",
     "drizzle-kit": "^0.31.10",
     "tsx": "^4",

packages/db/src/cluster-cli.ts

@@ -0,0 +1,142 @@
+// Dev DSQL cluster management CLI
+//
+// Usage:
+//   pnpm --filter @repo/db run cluster create [--region REGION]
+//   pnpm --filter @repo/db run cluster delete [--region REGION]
+//   pnpm --filter @repo/db run cluster status [--region REGION]
+//
+// After creation, DSQL_ENDPOINT and AWS_REGION are written to packages/db/.env.
+
+import { writeFileSync, readFileSync, unlinkSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import {
+  DSQLClient,
+  CreateClusterCommand,
+  DeleteClusterCommand,
+  GetClusterCommand,
+  waitUntilClusterActive,
+} from '@aws-sdk/client-dsql';
+
+const ENV_PATH = join(import.meta.dirname, '..', '.env');
+
+function parseArgs(args: string[]): { command: string; region: string } {
+  const command = args[0] ?? 'help';
+  let region = process.env.AWS_REGION ?? 'us-east-1';
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--region' && args[i + 1]) {
+      region = args[++i];
+    }
+  }
+  return { command, region };
+}
+
+function readClusterId(): string | undefined {
+  if (!existsSync(ENV_PATH)) return undefined;
+  const match = readFileSync(ENV_PATH, 'utf-8').match(/^DSQL_ENDPOINT=([^.]+)/m);
+  return match?.[1];
+}
+
+function writeEnv(endpoint: string, region: string) {
+  writeFileSync(ENV_PATH, `DSQL_ENDPOINT=${endpoint}\nAWS_REGION=${region}\n`);
+}
+
+function getOwner(): string {
+  return execSync('whoami', { encoding: 'utf-8' }).trim();
+}
+
+async function create(client: DSQLClient, region: string) {
+  // Idempotent: skip if an ACTIVE/CREATING cluster already exists
+  const existing = readClusterId();
+  if (existing) {
+    try {
+      const { status: clusterStatus } = await client.send(new GetClusterCommand({ identifier: existing }));
+      if (clusterStatus === 'ACTIVE' || clusterStatus === 'CREATING') {
+        console.log(`Cluster already exists: ${existing} (${clusterStatus})`);
+        return;
+      }
+      console.log(`Previous cluster ${existing} is ${clusterStatus}, creating new one...`);
+    } catch {
+      // Cluster not found — proceed to create
+    }
+  }
+
+  console.log(`Creating DSQL cluster in ${region}...`);
+  const res = await client.send(
+    new CreateClusterCommand({
+      deletionProtectionEnabled: false,
+      tags: {
+        Application: 'ServerlessWebappStarterKit',
+        ManagedBy: 'cluster-cli',
+        Owner: getOwner(),
+        Name: 'ServerlessWebappStarterKit-dsql-dev',
+      },
+    }),
+  );
+
+  const endpoint = res.endpoint!;
+  const identifier = res.identifier!;
+  writeEnv(endpoint, region);
+  console.log(`Cluster created: ${identifier}`);
+  console.log(`Endpoint: ${endpoint}`);
+  console.log(`Written to: .env`);
+
+  console.log('\nWaiting for ACTIVE status...');
+  await waitUntilClusterActive({ client, maxWaitTime: 300 }, { identifier });
+  console.log('Cluster is ACTIVE');
+
+  console.log('\nRun schema migration:');
+  console.log('  pnpm --filter @repo/db run migrate');
+}
+
+async function del(client: DSQLClient) {
+  const clusterId = readClusterId();
+  if (!clusterId) {
+    console.error('No cluster found in .env');
+    process.exit(1);
+  }
+  console.log(`Deleting cluster: ${clusterId}`);
+  await client.send(new DeleteClusterCommand({ identifier: clusterId }));
+  unlinkSync(ENV_PATH);
+  console.log('Cluster deleted and .env removed');
+}
+
+async function status(client: DSQLClient) {
+  const clusterId = readClusterId();
+  if (!clusterId) {
+    console.error('No cluster found in .env');
+    process.exit(1);
+  }
+  const cluster = await client.send(new GetClusterCommand({ identifier: clusterId }));
+  console.log(`Identifier: ${cluster.identifier}`);
+  console.log(`Status:     ${cluster.status}`);
+  console.log(`Endpoint:   ${cluster.endpoint}`);
+}
+
+async function main() {
+  const { command, region } = parseArgs(process.argv.slice(2));
+
+  if (command === 'help') {
+    console.log('Usage: cluster {create|delete|status} [--region REGION]');
+    return;
+  }
+
+  const client = new DSQLClient({ region });
+
+  switch (command) {
+    case 'create':
+      return create(client, region);
+    case 'delete':
+      return del(client);
+    case 'status':
+      return status(client);
+    default:
+      console.error(`Unknown command: ${command}`);
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});