drizzle-best-practices

Drizzle ORM のベストプラクティス（PostgreSQL）

Drizzle ORM と PostgreSQL を使用するための包括的なベストプラクティスガイドです。8 つのカテゴリにわたるガイダンスを、正確で高パフォーマンスかつ保守しやすいデータベースコードを書くために、影響度の高い順にまとめています。

バージョンと API の確認（最初にお読みください）

Drizzle は v1 への移行の途中であり、relations とリレーショナルクエリの API は、2 つのメジャー系列で異なります。コードを書く前に、プロジェクトの package.json を確認し、適切な構文を使用してください。

インストール済みの drizzle-orm	使用する API	インストールコマンド
^1.0.0-rc または ^1.0.0-beta	v1 — このスキルでのデフォルトです。 defineRelations、オブジェクト構文のリレーショナルクエリ（where: { … }、orderBy: { … }）、drizzle-orm/zod のバリデーター	npm i drizzle-orm@rc + npm i -D drizzle-kit@rc
^0.4x（例：0.45.2）	レガシーです。 relations() ヘルパー、コールバック／演算子を使うリレーショナルクエリ、別パッケージの drizzle-zod に含まれるバリデーター	npm i drizzle-orm（0.45.2 が解決されます）

現在のリリース候補は [email protected]（@rc タグ）です。これは、ドキュメントで今も一部参照されている古い @beta タグの後継です。

エージェントがつまずきやすい点は、次の 3 つです。

• @latest はまだ v1 ではなく、0.45.2 です。 npm i drizzle-orm では v1 はインストールされません。v1 API を使用する新しいプロジェクトでは、明示的に @rc を指定する必要があります。
• SQL に似たクエリビルダーは、どのバージョンでも変わりません。 db.select().from(t).where(eq(t.id, 1))、db.insert()、db.update()、db.delete() は、0.45.x と v1 で同じように動作します。変更されたのはリレーショナルクエリ API（db.query）とリレーションの 定義 だけです。db.select() の演算子フィルターを、リレーショナルオブジェクト構文に書き換えないでください。
• v1 では、リレーショナルクエリ API（db.query）は defineRelations によって機能します。 レガシーの schema を渡しても、db.query は設定されません。既存のリレーションモジュールを移行中もコンパイルできるように、古い relations() ヘルパーは drizzle-orm/_relations から引き続きインポートできます。ただし、v1 でリレーショナルクエリを実行するには、defineRelations に変換する必要があります。（以前のベータ版では db._query という経路が公開されていましたが、1.0.0-rc.3 より前に削除されました。）詳しくは references/relations-defining.md を参照してください。

バージョンが明記されていない場合、新しいコードでは v1（RC） をデフォルトにしてください。ただし、既存のコードベースでレガシーの relations() やコールバック形式の db.query が使われている場合は、その API に合わせてください。リファレンスファイルでは、バージョン固有の違いに 「Legacy (v0.45.x)」 の注記が付いています。

適用する場面

次の作業では、これらのガイドラインを参照してください。

• pgTable を使ったテーブルスキーマの定義
• select、insert、update、delete クエリの作成
• defineRelations またはレガシーの relations API を使ったテーブル間のリレーションの設定
• マイグレーション（generate、push、pull）用の drizzle-kit の設定
• スキーマからの TypeScript 型の推論
• SQL に似た API とリレーショナルクエリ API の選択
• プリペアドステートメントや一括操作によるクエリパフォーマンスの最適化
• サーバーレスの Postgres プロバイダー（Neon、Supabase など）との Drizzle の統合

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	接頭辞
1	スキーマ設計	重大	schema-
2	クエリパターン	重大	query-
3	リレーション	高	relations-
4	マイグレーション	高	migrations-
5	型安全性	中〜高	types-
6	パフォーマンス	中	perf-
7	データベースドライバー	中	driver-
8	高度なパターン	低	advanced-

使用方法

詳しい説明とコード例については、個別のリファレンスファイルをお読みください。

references/engine-postgres.md          # Postgres-specific types, features, and patterns
references/schema-table-definitions.md
references/query-select-patterns.md
references/relations-defining.md
references/_sections.md                # Full index of all references

各リファレンスファイルには、次の内容が含まれています。

• 重要である理由の簡単な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• Drizzle の公式ドキュメントへのリンク

References

• https://orm.drizzle.team/docs/overview
• https://orm.drizzle.team/docs/sql-schema-declaration
• https://orm.drizzle.team/docs/relations-v2
• https://orm.drizzle.team/docs/perf-queries
• https://orm.drizzle.team/docs/kit-overview
• https://orm.drizzle.team/llms.txt