tech-drizzle

Drizzle ORM の型安全なデータベースアクセス

依存関係がゼロの、軽量でヘッドレスな TypeScript ORM です。Drizzle の優れた点：

• 型推論 — スキーマから完全な TypeScript 型を推論します。型の生成や個別のスキーマ言語は不要です
• リレーショナルクエリ — 手動で結合せずに、.with() でネストされたデータを取得できます
• プリペアドステートメント — クエリを事前コンパイルして繰り返し実行できます。パフォーマンスが大幅に向上します
• マイグレーション — drizzle-kit を使用した、バージョン管理されたスキーマ変更です。ロールバックにも対応しています
• トランザクション — セーブポイントを使用した、ネストされたトランザクション向けの複数操作のアトミックなコミットです

基本パターン：テーブルごとにファイルを分け、ネストされたクエリにはリレーショナル API を使い、頻繁に実行するクエリにはプリペアドステートメントを使い、一貫性のためにトランザクションを使います。

ワークフロー

Drizzle ORM を使用する際は、次の手順に従います。

1. スキーマを設計する — テーブル、カラム、制約を定義します。テーブルごとにファイルを分けます
2. リレーションを定義する — defineRelations() で 1 対多、多対多のリレーションを定義し、ネストされたクエリを可能にします
3. クエリスタイルを選択する — ネストされたデータにはリレーショナル API（推奨）、柔軟性が必要な場合は SQL ビルダーを使います
4. 頻繁に実行するクエリを最適化する — 繰り返し実行するクエリには、プレースホルダーを使ったプリペアドステートメントを使用します
5. トランザクションを処理する — 複数操作を伴う書き込みを db.transaction() でラップします
6. マイグレーションをテストする — push の前に drizzle-kit migrate:dev を実行し、生成された SQL を確認します
7. 型を抽出する — スキーマからランタイム型を取得するには InferSelectModel を使用します

ルール

パターンは関心事ごとに整理されています。

• スキーマ — テーブル設計、カラム型、制約、テーブルごとのファイル分割
• リレーショナルクエリ — ネストされたデータ、部分的なカラム、フィルタリングには with() を使用します
• クエリビルダー — 集計や複雑なクエリには SQL ビルダーを使用します
• プリペアドステートメント — パフォーマンス向上のために事前コンパイルし、パラメーターにはプレースホルダーを使用します
• マイグレーション — バージョン管理、SQL の確認、push と generate の使い分け
• トランザクション — アトミックな操作、セーブポイント、エラー処理

実装パターンと例については、rules/ を参照してください。

例

該当する例

ユーザー：「ユーザーと商品へのリレーションを持つ注文の Drizzle スキーマを定義してください。」

期待される動作：tech-drizzle のガイダンスを使用し、リレーショナルクエリと型推論を用いてスキーマを設計します。

該当しない例

ユーザー：「users テーブルにカラムを追加する生の SQL マイグレーションを書いてください。」

期待される動作：tech-drizzle を優先せず、より関連性の高いスキルを選ぶか、スキルを使わずに対応します。

• エラー：準備されていないクエリをタイトなループ内で実行する

• 原因：実行のたびにクエリをコンパイルしており、解析済み SQL を再利用していない

• 解決策：プレースホルダーを使って .prepare() を使用し、異なるパラメーターで複数回実行します

• エラー：コード内で手動で結合する、親を取得してから子を個別に取得する

• 原因：リレーショナル API を使わず、複雑な結合ロジックを記述している

• 解決策：リレーションを定義し、.with() を使用して 1 つのクエリでネストされたデータを取得します

トラブルシューティング

• エラー：リレーションから選択する際に Column not included in result が発生する

• 原因：カラムを明示的に指定せずに、ネストされたリレーションから選択している

• 解決策：columns: { id: true, name: true } を使用して、ネストされたリレーションのカラムを指定します

• エラー：トランザクションが予期せずロールバックされ、明確なエラーが表示されない

• 原因：db.transaction() 内で Promise の拒否が処理されていない

• 解決策：トランザクション操作を try/catch でラップします。すべてのエラーを捕捉する必要があります

• エラー：マイグレーション後にスキーマの型が更新されない

• 原因：drizzle-kit で型が再生成されておらず、キャッシュが古い

• 解決策：マイグレーションの変更後に drizzle-kit generate を実行します