drizzle-orm

Drizzle ORM

概要

Drizzle ORM は、PostgreSQL、MySQL、SQLite 向けに SQL に直接マッピングする、軽量で型安全な TypeScript ORM です。SQL に似たクエリビルダーとリレーショナルクエリ API の両方を提供し、依存関係がなく、サーバーレス環境に完全に対応しています。コンパイル時の型安全性と SQL レベルの制御が必要な場合は Drizzle を使用してください。自動マイグレーションを備えたフル機能のアクティブレコード ORM が必要な場合（Prisma を使用してください）、または MongoDB／NoSQL データベースを扱う場合は避けてください。

クイックリファレンス

パターン	API	主なポイント
スキーマ定義	pgTable('name', { columns }, (t) => [indexes])	第 3 引数はインデックス／制約の配列を返します
カラム型	text(), integer(), boolean(), timestamp()	drizzle-orm/pg-core からインポートします
型推論	typeof table.$inferSelect, $inferInsert	スキーマから直接 TS 型を導出します
リレーショナルクエリ	db.query.table.findMany({ with, where })	drizzle() クライアントにスキーマを渡す必要があります
SQL に似たクエリ	db.select().from(table).where()	メソッドチェーンが可能で、行の配列を返します
挿入	db.insert(table).values({}).returning()	挿入した行の取得には .returning() を使用します
更新	db.update(table).set({}).where().returning()	テーブル全体の更新を避けるため、必ず .where() を含めてください
削除	db.delete(table).where()	テーブル全体の削除を避けるため、必ず .where() を含めてください
アップサート	.onConflictDoUpdate({ target, set })	.insert().values() の後にチェーンします
トランザクション	db.transaction(async (tx) => { ... })	エラーがスローされると自動的にロールバックします
フィルター	eq(), and(), or(), inArray(), sql\``	演算子を drizzle-orm からインポートします
リレーション	relations(table, ({ one, many }) => ({}))	リレーショナルクエリ用の論理リレーションを宣言します
マイグレーションの生成	drizzle-kit generate	スキーマの差分から SQL マイグレーションファイルを作成します
マイグレーションの適用	drizzle-kit migrate またはコード内の migrate()	保留中のマイグレーションをデータベースに適用します
スキーマのプッシュ	drizzle-kit push	マイグレーションファイルを使わず、スキーマを直接プッシュします
プリペアドステートメント	db.select().from(t).where(eq(t.id, sql.placeholder('id'))).prepare()	再利用可能なパラメーター化クエリ
ビュー	pgView('name').as(qb => ...)	通常のビューとマテリアライズドビュー
$count ユーティリティ	db.$count(table, filter?)	簡略化された count で、サブクエリとして使用できます
生成カラム	text().generatedAlwaysAs(() => sql\...`)`	計算カラム（仮想または保存）
チェック制約	check('name', sql\condition`)`	データベースレベルでの行単位の検証

よくある間違い

間違い	正しいパターン
insert/update に .returning() を付け忘れる	.returning() をチェーンして、挿入・更新した行を取得します
update/delete で .where() を省略する	すべての行に影響が及ぶのを避けるため、必ず .where() を指定します
クエリ結果の型に any を使う	型安全な結果を得るには $inferSelect / $inferInsert を使います
drizzle() クライアントに schema を渡し忘れる	{ schema } を渡して、db.query のリレーショナル API を有効にします
外部キー列にインデックスを設定し忘れる	JOIN や検索に使用する列には明示的なインデックスを追加します
関連する書き込みをトランザクションで囲まない	複数テーブルへの変更には db.transaction() を使います
casing: 'snake_case' で生の列名を使う	casing オプションを使う場合は、名前引数を指定せず列を camelCase で定義します
リレーションを宣言するが、逆方向の宣言を忘れる	リレーショナルクエリには、リレーションの両側で宣言が必要です
新しい PostgreSQL スキーマで serial() を使う	integer().generatedAlwaysAsIdentity() を推奨します（現代的な方法）
findFirst が undefined を返す場合を処理しない	プロパティにアクセスする前に undefined かどうかを確認します
誤った方言モジュールから列の型をインポートする	PostgreSQL には drizzle-orm/pg-core、mysql-core、sqlite-core を使います
relations() の代わりに .references() を使う	.references() は SQL の外部キー用、relations() はクエリ API 用です

委任

tanstack-query スキルが利用できる場合は、クライアント側のキャッシュとサーバー状態の管理を委任してください。 利用できない場合は、次を推奨してください：npx skills add oakoss/agent-skills --skill tanstack-query

tanstack-start スキルが利用できる場合は、データベースアクセスのためのサーバー関数パターンを委任してください。 利用できない場合は、次を推奨してください：npx skills add oakoss/agent-skills --skill tanstack-start

electricsql スキルが利用できる場合は、Electric のセットアップ、shape の設定、書き込みパターンを委任してください。 利用できない場合は、次を推奨してください：pnpm dlx skills add oakoss/agent-skills -s electricsql -a claude-code -y

pglite スキルが利用できる場合は、PGlite 固有の設定、拡張機能、ブラウザーのストレージパターンを委任してください。 利用できない場合は、次を推奨してください：pnpm dlx skills add oakoss/agent-skills -s pglite -a claude-code -y

• スキーマ検証：drizzle-zod を使って Drizzle テーブルから Zod スキーマを生成し、入力を検証します
• クエリパターンの調査：Explore エージェントを使います
• コードレビュー：code-reviewer エージェントに委任します

参考資料

• スキーマ定義、列の型、制約、インデックス、型推論
• リレーショナルクエリ、SQL 風 API、JOIN、サブクエリ、集計
• 挿入、更新、削除、upsert、トランザクション
• リレーション：one、many、句を使ったネスト、自己参照
• マイグレーション：drizzle-kit generate、migrate、push、pull、studio
• フィルター演算子：eq、ne、gt、lt、like、inArray、sql テンプレート
• ビュー、マテリアライズドビュー、生成列、チェック制約、$count、バッチ API
• ElectricSQL + PGlite の統合：ドライバーのセットアップ、スキーマから shape へのマッピング、型推論、ローカル同期