drizzle-orm-patterns

Drizzle ORM パターン

概要

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

使用する場面

• テーブル、カラム、制約を含むデータベーススキーマを定義する
• テーブル間のリレーション（一対一、一対多、多対多）を作成する
• 型安全な CRUD クエリを記述する
• 複雑な結合や集計を実装する
• ロールバックに対応したデータベーストランザクションを管理する
• 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';

// Insert
const [newUser] = await db.insert(users).values({
  name: 'John',
  email: '[email protected]',
}).returning();

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

// Delete
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 - v1 および v2 構文による一対一、一対多、多対多のリレーション
• references/queries-joins-aggregations.md - CRUD 操作、クエリ演算子、結合、集計、ページネーション

高度なトピック

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