drizzle-orm

Drizzle ORM 開発者ガイド

このスキルでは、このプロジェクトで Drizzle ORM を使用する際のガイドライン、パターン、ベストプラクティスを紹介します。

クイックスタート

詳しい開発ガイドライン、パターン、コード例については、references/patterns.md を参照してください。

基本方針

• デフォルトで型安全: TypeScript と Drizzle の型推論を活用し、コンパイル時にデータベースのエラーを検出します
• パフォーマンスを最優先: プリペアドステートメントとクエリ最適化の手法を使用します
• SQL の透明性: SQL クエリを読みやすく保ち、過度な抽象化を避けます
• オーバーヘッドを最小限に: Drizzle は薄いレイヤーです。不要な複雑さを加えず、適切に使用してください

よくあるタスク

スキーマの定義

スキーマはドメインごとに分けて、別々のファイルに整理します。流暢な制約のチェーンを使用し、頻繁にクエリされるカラムにはインデックスを追加します。

export const users = pgTable('users', {
  id: uuid('id').primaryKey().defaultRandom(),
  email: varchar('email', { length: 255 }).notNull().unique(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
});

型のエクスポート

アプリケーションで使用するテーブル型は、必ずエクスポートしてください。

export type User = typeof users.$inferSelect;
export type NewUser = typeof users.$inferInsert;

プリペアドステートメント

頻繁に実行するクエリには、パフォーマンスを大幅に向上させるため、プリペアドステートメントを使用します。

export const getUserById = db
  .select()
  .from(users)
  .where(eq(users.id, sql.placeholder('id')))
  .prepare();

// Usage
const user = await getUserById.execute({ id: userId });

トランザクション

データの一貫性を保つため、複数ステップの操作にはトランザクションを使用します。

return db.transaction(async (tx) => {
  const [user] = await tx.insert(users).values(userData).returning();
  const [profile] = await tx.insert(profiles).values({ userId: user.id, ...profileData }).returning();
  return { user, profile };
});

マイグレーションコマンド

重要: マイグレーションには、必ずパッケージスクリプトを使用してください。drizzle-kit を直接呼び出さないでください。

• Backend: pnpm run db:generate（マイグレーションを生成）
• Backend: pnpm run db:migrate（マイグレーションを適用）
• Landing: pnpm run db:generate（マイグレーションを生成）
• Landing: pnpm run db:migrate（マイグレーションを適用）

コードの構成

db/
  index.ts           (Drizzle client initialization)
  schema/
    users.ts         (User table & relations)
    posts.ts         (Post table & relations)
  queries/
    users.ts         (User query functions)
    posts.ts         (Post query functions)
  migrations/        (Auto-generated migration files)

避けるべきよくある落とし穴

1. インデックスの不足: WHERE、JOIN、ORDER BY 句で使用するカラムには、必ずインデックスを設定してください
2. 件数に上限のないクエリ: ユーザー向けのクエリでは、必ず limit() と offset() を使用してください
3. 安全でない生 SQL: ユーザー入力を生 SQL に連結しないでください。sql.placeholder() を使用してください
4. N+1 クエリ: with() によるイーガーローディング、またはバッチクエリを使用してください
5. トランザクションの不足: 複数ステップの操作はトランザクションで囲んでください

検証チェックリスト

Drizzle ORM が関わるタスクを完了する前に、次の点を確認してください。

• スキーマ定義で、クエリ対象のカラムに適切なインデックスが設定されている
• 繰り返し実行するクエリでプリペアドステートメントが使用されている
• 複数ステップの操作がトランザクションで囲まれている
• マイグレーションにパッケージスクリプトを使用している（drizzle-kit を直接呼び出さない）
• 型チェック（pnpm run typecheck）とテスト（pnpm run test）を実行している

詳しいルールとコード例については、references/patterns.md を参照してください。