Claude Code × Drizzle ORM で実現する型安全データベース開発2026

# Claude Code に渡すプロンプト（CLAUDE.md またはチャットで）
# 以下のような指示を与える

// drizzle.config.ts
import type { Config } from "drizzle-kit";
import * as dotenv from "dotenv";
dotenv.config();
 
export default {
  schema: "./src/db/schema/index.ts",
  out: "./src/db/migrations",
  dialect: "postgresql",
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
  // マイグレーションファイルに詳細なメタデータを含める
  verbose: true,
  strict: true,
} satisfies Config;

// src/db/index.ts
import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import * as schema from "./schema";
 
// コネクションプールの設定（本番環境向け）
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 20,              // 最大接続数
  idleTimeoutMillis: 30000,  // アイドル接続のタイムアウト
  connectionTimeoutMillis: 2000, // 接続タイムアウト
});
 
// スキーマを渡すことで型推論が完全に機能する
export const db = drizzle(pool, { schema });
 
// 接続テスト（起動時に実行）
export async function testConnection() {
  try {
    const result = await pool.query("SELECT 1");
    console.log("✅ Database connected successfully");
    return true;
  } catch (error) {
    console.error("❌ Database connection failed:", error);
    return false;
  }
}

// src/db/schema/users.ts
import {
  pgTable,
  uuid,
  varchar,
  text,
  timestamp,
  boolean,
  pgEnum,
} from "drizzle-orm/pg-core";
 
// ユーザーロールのEnum型
export const userRoleEnum = pgEnum("user_role", ["admin", "editor", "viewer"]);
 
export const users = pgTable("users", {
  id: uuid("id").primaryKey().defaultRandom(),
  email: varchar("email", { length: 255 }).notNull().unique(),
  displayName: varchar("display_name", { length: 100 }).notNull(),
  avatarUrl: text("avatar_url"),
  role: userRoleEnum("role").notNull().default("viewer"),
  emailVerified: boolean("email_verified").notNull().default(false),
  createdAt: timestamp("created_at", { withTimezone: true })
    .notNull()
    .defaultNow(),
  updatedAt: timestamp("updated_at", { withTimezone: true })
    .notNull()
    .defaultNow()
    .$onUpdate(() => new Date()),
  deletedAt: timestamp("deleted_at", { withTimezone: true }),
});
 
// 型エクスポート（TypeScript での利用に便利）
export type User = typeof users.$inferSelect;
export type NewUser = typeof users.$inferInsert;

// src/db/schema/posts.ts
import {
  pgTable,
  uuid,
  varchar,
  text,
  timestamp,
  integer,
  pgEnum,
  index,
} from "drizzle-orm/pg-core";
import { users } from "./users";
 
export const postStatusEnum = pgEnum("post_status", [
  "draft",
  "published",
  "archived",
]);
 
export const posts = pgTable(
  "posts",
  {
    id: uuid("id").primaryKey().defaultRandom(),
    title: varchar("title", { length: 500 }).notNull(),
    slug: varchar("slug", { length: 500 }).notNull().unique(),
    content: text("content"),
    excerpt: text("excerpt"),
    authorId: uuid("author_id")
      .notNull()
      .references(() => users.id, { onDelete: "cascade" }),
    status: postStatusEnum("status").notNull().default("draft"),
    viewCount: integer("view_count").notNull().default(0),
    publishedAt: timestamp("published_at", { withTimezone: true }),
    createdAt: timestamp("created_at", { withTimezone: true })
      .notNull()
      .defaultNow(),
    updatedAt: timestamp("updated_at", { withTimezone: true })
      .notNull()
      .defaultNow()
      .$onUpdate(() => new Date()),
    deletedAt: timestamp("deleted_at", { withTimezone: true }),
  },
  (table) => ({
    // クエリパターンに基づいたインデックス設計
    authorIdIdx: index("posts_author_id_idx").on(table.authorId),
    statusIdx: index("posts_status_idx").on(table.status),
    slugIdx: index("posts_slug_idx").on(table.slug),
    // 公開記事の一覧取得に最適化した複合インデックス
    statusPublishedAtIdx: index("posts_status_published_at_idx").on(
      table.status,
      table.publishedAt
    ),
  })
);
 
export type Post = typeof posts.$inferSelect;
export type NewPost = typeof posts.$inferInsert;

// src/db/schema/tags.ts — 多対多リレーション
import { pgTable, uuid, varchar, primaryKey } from "drizzle-orm/pg-core";
import { posts } from "./posts";
 
export const tags = pgTable("tags", {
  id: uuid("id").primaryKey().defaultRandom(),
  name: varchar("name", { length: 100 }).notNull().unique(),
  slug: varchar("slug", { length: 100 }).notNull().unique(),
});
 
// 中間テーブル（多対多）
export const postTags = pgTable(
  "post_tags",
  {
    postId: uuid("post_id")
      .notNull()
      .references(() => posts.id, { onDelete: "cascade" }),
    tagId: uuid("tag_id")
      .notNull()
      .references(() => tags.id, { onDelete: "cascade" }),
  },
  (table) => ({
    pk: primaryKey({ columns: [table.postId, table.tagId] }),
  })
);
 
export type Tag = typeof tags.$inferSelect;

// package.json
{
  "scripts": {
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate",
    "db:push": "drizzle-kit push",
    "db:studio": "drizzle-kit studio",
    "db:check": "drizzle-kit check",
    "db:drop": "drizzle-kit drop"
  }
}

npm run db:generate
# → src/db/migrations/0001_xxxxx.sql が自動生成される

npm run db:migrate
# → 未適用のマイグレーションが順番に実行される

// scripts/migrate.ts
import { drizzle } from "drizzle-orm/node-postgres";
import { migrate } from "drizzle-orm/node-postgres/migrator";
import { Pool } from "pg";
 
async function runMigration() {
  console.log("🔄 Starting database migration...");
 
  const pool = new Pool({
    connectionString: process.env.DATABASE_URL,
    max: 1, // マイグレーション中は接続数を最小限に
  });
 
  const db = drizzle(pool);
 
  try {
    await migrate(db, {
      migrationsFolder: "./src/db/migrations",
    });
    console.log("✅ Migration completed successfully");
  } catch (error) {
    console.error("❌ Migration failed:", error);
    process.exit(1);
  } finally {
    await pool.end();
  }
}
 
runMigration();

# 本番環境での実行
DATABASE_URL="postgresql://..." npx tsx scripts/migrate.ts

// src/db/queries/posts.ts
import { db } from "../index";
import { posts, users, postTags, tags } from "../schema";
import { and, eq, isNull, desc, sql } from "drizzle-orm";
 
// 公開済み投稿をタグ・著者情報付きで取得
export async function getPublishedPosts(limit = 10, offset = 0) {
  const result = await db
    .select({
      id: posts.id,
      title: posts.title,
      slug: posts.slug,
      excerpt: posts.excerpt,
      publishedAt: posts.publishedAt,
      viewCount: posts.viewCount,
      author: {
        id: users.id,
        displayName: users.displayName,
        avatarUrl: users.avatarUrl,
      },
    })
    .from(posts)
    .innerJoin(users, eq(posts.authorId, users.id))
    .where(
      and(
        eq(posts.status, "published"),
        isNull(posts.deletedAt),
        isNull(users.deletedAt)
      )
    )
    .orderBy(desc(posts.publishedAt))
    .limit(limit)
    .offset(offset);
 
  return result;
  // 戻り値の型は TypeScript が自動推論 — キャスト不要
}
 
// 閲覧数でランキングされた人気記事の取得
export async function getPopularPosts(days = 30, limit = 5) {
  const cutoffDate = new Date();
  cutoffDate.setDate(cutoffDate.getDate() - days);
 
  return await db
    .select({
      id: posts.id,
      title: posts.title,
      slug: posts.slug,
      viewCount: posts.viewCount,
      publishedAt: posts.publishedAt,
    })
    .from(posts)
    .where(
      and(
        eq(posts.status, "published"),
        isNull(posts.deletedAt),
        sql`${posts.publishedAt} >= ${cutoffDate.toISOString()}`
      )
    )
    .orderBy(desc(posts.viewCount))
    .limit(limit);
}

// src/db/queries/transactions.ts
import { db } from "../index";
import { posts, postTags, tags } from "../schema";
import { eq, inArray } from "drizzle-orm";
 
// 投稿作成とタグ紐付けをトランザクションで実行
export async function createPostWithTags(
  postData: {
    title: string;
    slug: string;
    content: string;
    authorId: string;
  },
  tagNames: string[]
) {
  return await db.transaction(async (tx) => {
    // 1. 投稿を作成
    const [newPost] = await tx
      .insert(posts)
      .values(postData)
      .returning();
 
    // 2. タグをupsert（存在しない場合は新規作成）
    const upsertedTags = await Promise.all(
      tagNames.map((name) =>
        tx
          .insert(tags)
          .values({
            name,
            slug: name.toLowerCase().replace(/\s+/g, "-"),
          })
          .onConflictDoUpdate({
            target: tags.slug,
            set: { name },
          })
          .returning()
      )
    );
 
    // 3. 投稿とタグを紐付け
    const tagIds = upsertedTags.map(([tag]) => tag.id);
    if (tagIds.length > 0) {
      await tx.insert(postTags).values(
        tagIds.map((tagId) => ({
          postId: newPost.id,
          tagId,
        }))
      );
    }
 
    return { post: newPost, tagCount: tagIds.length };
    // どこかでエラーが発生した場合、トランザクション全体がロールバックされる
  });
}

// カーソルベースのページネーション（無限スクロール対応）
export async function getPostsCursor(
  cursor?: string,
  limit = 10
) {
  const query = db
    .select({
      id: posts.id,
      title: posts.title,
      slug: posts.slug,
      publishedAt: posts.publishedAt,
    })
    .from(posts)
    .where(
      and(
        eq(posts.status, "published"),
        isNull(posts.deletedAt),
        cursor
          ? sql`${posts.publishedAt} < ${new Date(cursor).toISOString()}`
          : undefined
      )
    )
    .orderBy(desc(posts.publishedAt))
    .limit(limit + 1); // 次のページ存在チェック用に1件多く取得
 
  const results = await query;
  const hasNextPage = results.length > limit;
  const items = hasNextPage ? results.slice(0, -1) : results;
  const nextCursor = hasNextPage
    ? items[items.length - 1].publishedAt?.toISOString()
    : null;
 
  return { items, nextCursor, hasNextPage };
}

<!-- CLAUDE.md -->
# データベース開発ルール
 
## Drizzle ORM の規約
- スキーマ変更後は必ず `npm run db:generate` でマイグレーションファイルを生成すること
- `db.query.*` の関連クエリ API より `db.select().from()` の明示的なクエリを優先すること
- すべてのクエリ関数はエラーハンドリングを含めること
- N+1クエリが発生しないよう、JOIN を活用すること
 
## 命名規約
- テーブル名: スネークケース複数形（users, posts, post_tags）
- カラム名: スネークケース（created_at, author_id）
- TypeScript 変数: キャメルケース（createdAt, authorId）
- インデックス: `{tableName}_{columnName}_idx` パターン
 
## セキュリティ
- ユーザー入力を直接クエリに挿入しない（drizzle の型安全API を使う）
- `sql` テンプレートリテラルを使う場合は必ずパラメータ化する

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c \"if echo '$TOOL_ARGS' | grep -q 'schema.*\\.ts'; then echo '⚠️ スキーマ変更を検出。npm run db:generate を実行してください'; fi\""
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/post-schema-change.sh
# スキーマファイルが変更された場合にマイグレーション生成を促す
 
CHANGED_FILE="$1"
 
if [[ "$CHANGED_FILE" == *"/schema/"* && "$CHANGED_FILE" == *".ts" ]]; then
  echo ""
  echo "📦 スキーマ変更を検出しました。"
  echo "以下のコマンドでマイグレーションファイルを生成してください:"
  echo "  npm run db:generate"
  echo ""
  echo "生成後のマイグレーションファイルを確認し、問題なければ:"
  echo "  npm run db:migrate"
fi

// src/db/utils/explain.ts
import { db } from "../index";
import { sql } from "drizzle-orm";
 
// クエリの実行計画を取得するユーティリティ
export async function explainQuery(queryStr: string) {
  const result = await db.execute(
    sql`EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) ${sql.raw(queryStr)}`
  );
  return result.rows[0];
}
 
// 使用例
const plan = await explainQuery(`
  SELECT p.*, u.display_name
  FROM posts p
  JOIN users u ON p.author_id = u.id
  WHERE p.status = 'published'
  ORDER BY p.published_at DESC
  LIMIT 10
`);
console.log(JSON.stringify(plan, null, 2));

// src/db/schema/posts.ts — 高度なインデックス設計
import { pgTable, ..., sql as pgSql } from "drizzle-orm/pg-core";
 
export const posts = pgTable(
  "posts",
  {
    // ... フィールド定義
  },
  (table) => ({
    // 公開済み記事のみを対象とした部分インデックス
    // WHERE status = 'published' のクエリが劇的に高速化
    publishedPostsIdx: index("posts_published_idx")
      .on(table.publishedAt)
      .where(pgSql`status = 'published'`),
 
    // ソフトデリート対応の部分インデックス
    activePostsIdx: index("posts_active_idx")
      .on(table.authorId, table.createdAt)
      .where(pgSql`deleted_at IS NULL`),
  })
);

// src/db/edge.ts — Cloudflare Workers 向け設定
import { drizzle } from "drizzle-orm/neon-http";
import { neon } from "@neondatabase/serverless";
import * as schema from "./schema";
 
// Cloudflare Workers での環境変数アクセス
export function createDb(env: { DATABASE_URL: string }) {
  const sql = neon(env.DATABASE_URL);
  return drizzle(sql, { schema });
}
 
// Cloudflare Workers のハンドラー
export default {
  async fetch(request: Request, env: { DATABASE_URL: string }) {
    const db = createDb(env);
 
    // エッジで直接データベースクエリを実行
    const latestPosts = await db
      .select({
        id: schema.posts.id,
        title: schema.posts.title,
        slug: schema.posts.slug,
      })
      .from(schema.posts)
      .where(eq(schema.posts.status, "published"))
      .limit(10);
 
    return Response.json({ posts: latestPosts });
  },
};

// Cloudflare Hyperdrive を使った本番グレードの接続
import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
 
export function createDbWithHyperdrive(
  env: { HYPERDRIVE: Hyperdrive }
) {
  // Hyperdrive が自動的にコネクションプーリングを処理
  const pool = new Pool({
    connectionString: env.HYPERDRIVE.connectionString,
  });
  return drizzle(pool, { schema });
}

// 対処: コネクションプールの設定を見直す
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 10,  // デフォルト10に下げる
  idleTimeoutMillis: 10000,
  connectionTimeoutMillis: 3000,
});

# 対処: マイグレーション履歴を確認
npm run db:check
 
# 競合するマイグレーションファイルを削除してやり直す
npm run db:drop

// 原因: pgEnum の値が TypeScript に認識されていない
// 対処: as const を使って型を絞り込む
 
const status = "published" as const;
// または
type PostStatus = typeof postStatusEnum.enumValues[number];