Drizzle ORM パターン

概要

Drizzle ORM を使用した型安全なデータベースアプリケーションの構築に関する専門家向けガイドです。スキーマ定義、リレーション、クエリ、トランザクション、マイグレーションをすべてのサポートされているデータベースで説明します。

使用シーン

• テーブル、カラム、制約を含むデータベーススキーマの定義
• テーブル間のリレーション定義（1対1、1対多、多対多）
• 型安全な CRUD クエリの作成
• 複雑な JOIN と集計の実装
• ロールバック機能付きのデータベーストランザクション管理
• Drizzle Kit によるマイグレーションのセットアップ
• PostgreSQL、MySQL、SQLite、MSSQL、CockroachDB での作業

クイックリファレンス

データベース	テーブル関数	インポート
PostgreSQL	pgTable()	drizzle-orm/pg-core
MySQL	mysqlTable()	drizzle-orm/mysql-core
SQLite	sqliteTable()	drizzle-orm/sqlite-core
MSSQL	mssqlTable()	drizzle-orm/mssql-core

操作	メソッド	例
挿入	db.insert()	db.insert(users).values({...})
選択	db.select()	db.select().from(users).where(eq(...))
更新	db.update()	db.update(users).set({...}).where(...)
削除	db.delete()	db.delete(users).where(...)
トランザクション	db.transaction()	db.transaction(async (tx) => {...})

手順

1. データベース方言を特定 - PostgreSQL、MySQL、SQLite、MSSQL、または CockroachDB を選択
2. スキーマを定義 - 適切なテーブル関数（pgTable、mysqlTable など）を使用
3. リレーションをセットアップ - relations() または defineRelations() を使用してリレーションを定義
4. データベースクライアントを初期化 - 適切な認証情報を使用して Drizzle クライアントを作成
5. クエリを作成 - クエリビルダーを使用して型安全な CRUD 操作を実行
6. トランザクションを処理 - 必要に応じて複数ステップの操作をトランザクション内にラップ
7. マイグレーションをセットアップ - スキーマ管理のために Drizzle Kit を設定

サンプル

サンプル 1: 基本的なスキーマとクエリ

import { pgTable, serial, text } from 'drizzle-orm/pg-core';
import { drizzle } from 'drizzle-orm/node-postgres';
import { eq } from 'drizzle-orm';

export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  name: text('name').notNull(),
  email: text('email').notNull().unique(),
});

const db = drizzle(process.env.DATABASE_URL);

const [user] = await db.select().from(users).where(eq(users.id, 1));

サンプル 2: CRUD 操作

import { eq } from 'drizzle-orm';

// 挿入
const [newUser] = await db.insert(users).values({
  name: 'John',
  email: 'john@example.com',
}).returning();

// 更新
await db.update(users)
  .set({ name: 'John Updated' })
  .where(eq(users.id, 1));

// 削除
await db.delete(users).where(eq(users.id, 1));

サンプル 3: ロールバック付きトランザクション

await db.transaction(async (tx) => {
  const [from] = await tx.select().from(accounts)
    .where(eq(accounts.userId, fromId));

  if (from.balance < amount) {
    tx.rollback();
  }

  await tx.update(accounts)
    .set({ balance: sql`${accounts.balance} - ${amount}` })
    .where(eq(accounts.userId, fromId));
});

詳細なトランザクションパターンは references/transactions.md を参照してください。

ベストプラクティス

1. 型安全性: 常に TypeScript を使用し、$inferInsert / $inferSelect を活用
2. リレーション: relations() API を使用してネストされたクエリのためにリレーションを定義
3. トランザクション: 一緒に成功する必要がある複数ステップの操作にはトランザクションを使用
4. マイグレーション: 本番環境では generate + migrate を使用し、開発環境では push を使用
5. インデックス: 頻繁にクエリされるカラムと外部キーにインデックスを追加
6. ソフト削除: 可能な限りハード削除の代わりに deletedAt タイムスタンプを使用
7. ページネーション: 大規模なデータセットにはカーソルベースのページネーションを使用
8. クエリの最適化: .limit() と .where() を使用して必要なデータのみを取得

制約と警告

• 外部キー制約: 循環依存の問題を避けるために、常にアロー関数 () => table.column を使用してリファレンスを定義
• トランザクションのロールバック: tx.rollback() を呼び出すと例外がスロー - 必要に応じて try/catch を使用
• Returning 句: すべてのデータベースが .returning() をサポートしているわけではない - 方言の互換性を確認
• バッチ操作: 大規模なバッチ挿入はデータベース制限に達する可能性がある - より小さなバッチに分割
• 本番環境でのマイグレーション: 本番環境に適用する前に、常にステージング環境でマイグレーションをテスト

参照

コアコンセプト

• references/schema-definition.md - すべてのデータベース（PostgreSQL、MySQL、SQLite）の完全なスキーマ定義、カラムタイプ、インデックス、制約
• references/relations.md - 1対1、1対多、多対多リレーション（v1 および v2 シンタックス）
• references/queries-joins-aggregations.md - CRUD 操作、クエリ演算子、JOIN、集計、ページネーション

高度なトピック

• references/transactions.md - トランザクションパターン、ロールバック処理、ネストされたトランザクション
• references/migrations.md - Drizzle Kit 設定、CLI コマンド、マイグレーションワークフロー
• references/common-patterns.md - ソフト削除、アップサート、バッチ操作、全文検索、監査ログ