Drizzle ORM と NestJS を使用した API の構築: 完全ガイド

Drizzle ORM は、最も急速に成長している TypeScript ORM として登場し、完全な型安全性とランタイム オーバーヘッドのない SQL のような構文を提供します。 NestJS と組み合わせることで、開発者にとって使いやすく、パフォーマンスの高い運用 API を構築するための強力なスタックを作成します。

重要なポイント

• Drizzle は、完全な TypeScript 推論による SQL のようなクエリを提供します -- コード生成ステップは必要ありません
• NestJS 依存関係の注入は Drizzle データベース接続ときれいに統合されます
• スキーマ主導の開発により、データベースと TypeScript タイプの同期が確保されます
• Drizzle プッシュおよび移行コマンドは、ダウンタイムなしでスキーマの進化を処理します

---

プロジェクトのセットアップ

インストール

NestJS プロジェクトから始めて、Drizzle の依存関係を追加します。

npm install drizzle-orm postgres
npm install -D drizzle-kit @types/pg

パフォーマンスの観点から、postgres.js ドライバーをお勧めします。運用環境での接続プーリングについては、PgBouncer またはサーバーレスに最適化されたドライバーを検討してください。

データベース接続モジュール

依存関係注入を通じて Drizzle インスタンスを提供するグローバル データベース モジュールを作成します。 DATABASE_URL から postgres クライアントを作成し、drizzle(client, \\\\\\\\{ schema \\\\\\\\}) を返す useFactory を使用して DB_TOKEN プロバイダーを定義します。トークンをエクスポートすると、どのサービスでも @Inject("DRIZZLE_DB") を使用してトークンを注入できます。

---

スキーマ定義

Drizzle テーブル ビルダーを使用してデータベース テーブルを定義します。各テーブルは、uuid、varchar、timestamp、boolean、およびその他の列タイプを使用した列定義を含む pgTable() で作成された const をエクスポートします。列は、デフォルト (defaultRandom、defaultNow)、制約 (notNull、unique)、および関係をサポートします。

リレーションの定義

Drizzle 関係は、タイプセーフな熱心な読み込みを提供します。 relationship() 関数を使用してリレーションを定義し、many() で 1 対多を指定し、one() で多対 1 を指定します。参照列は、外部キーを親テーブルの主キーにマップします。

---

クエリの構築

クエリの選択

Drizzle クエリは SQL のように読み取りながら、完全な型推論を提供します。

• 単純な選択: db.select().from(users)
• フィルター済み: db.select().from(users).where(and(eq(users.role, "admin"), eq(users.isActive, true)))
• 結合あり: db.select().from(users).leftJoin(orders, eq(users.id,orders.userId))
• 関係の読み込み: db.query.users.findMany(\\\\\\\\{ with: {orders: true \\\\\\\\}, limit: 20 })

挿入、更新、削除

// Insert with returning
const [newUser] = await this.db
  .insert(users)
  .values({ email: "[email protected]", name: "New User" })
  .returning();

// Update
await this.db
  .update(users)
  .set({ role: "admin", updatedAt: new Date() })
  .where(eq(users.id, userId));

// Delete
await this.db.delete(users).where(eq(users.id, userId));

---

トランザクション

Drizzle トランザクションにより、アトミックな操作が保証されます。トランザクション オブジェクト (tx) を受信する非同期コールバックを使用して db.transaction() を呼び出します。コールバック内のすべてのクエリはアトミックに実行されます。失敗した場合は、トランザクション全体がロールバックされます。

一般的な使用例には、親レコードと子レコードを一緒に作成する、注文処理時に在庫を更新する、アカウント間で資金を移動するなどがあります。

---

移行

スキーマプッシュ (開発)

開発中、drizzle-kit プッシュを使用してスキーマ変更を直接プッシュします。これにより、スキーマ ファイルがデータベースと比較され、変更が適用されます。開発には高速ですが、運用には適していません。

移行ファイル (本番環境)

運用環境の場合は、drizzle-kit Generate を使用してバージョン管理された SQL 移行ファイルを生成し、drizzle-kit Migrate を使用してそれらを適用します。移行ファイルは、ステージングで確認、テストし、CI/CD パイプラインに適用できます。

---

NestJS 統合パターン

サービスパターン

サービスは Drizzle データベースを挿入し、動的フィルターを使用してクエリを構築します。

@Injectable()
export class ProductsService {
  constructor(@Inject("DRIZZLE_DB") private db: DrizzleDB) {}

  async findAll(filters: ProductFilters) {
    const conditions = [];
    if (filters.category)
      conditions.push(eq(products.category, filters.category));
    if (filters.minPrice)
      conditions.push(gte(products.price, filters.minPrice));

    return this.db
      .select()
      .from(products)
      .where(conditions.length ? and(...conditions) : undefined)
      .orderBy(desc(products.createdAt))
      .limit(filters.limit || 20)
      .offset(filters.offset || 0);
  }
}

マルチテナンシー

SaaS アプリケーションの場合、すべてのクエリをorganizationIdでフィルタリングする必要があります。すべてのデータベース操作でテナントの分離を保証する基本サービスまたはミドルウェアを作成します。クライアントが提供する組織 ID を決して信頼しないでください。認証されたセッションに対して検証します。

パラメータ化されたクエリ

Drizzle はデフォルトでパラメータ化されたクエリを使用し、SQL インジェクションを防ぎます。ユーザー入力では sql.raw() を決して使用しないでください。代わりに、補間された値を自動的にパラメータ化する SQL テンプレート リテラルを使用します。

---

パフォーマンスのベスト プラクティス

1. 必要な列のみを選択: すべての列を選択する代わりに、.select(\\\\\\\\{ id: users.id, name: users.name \\\\\\\\}) を使用します。
2. インデックスを使用: 頻繁にフィルターされる列にデータベース インデックスがあることを確認します。
3. 結果を制限する: リスト クエリでは常に .limit() を使用します。
4. バッチ挿入: ループの代わりに .values([...array]) を一括挿入に使用します。
5. 接続プーリング: ワークロードに適したプール サイズを構成します。
6. 遅延接続: プロキシ パターンを使用して、最初のクエリまで接続を延期します。

---

よくある質問

Q: Drizzle と NestJS の Prisma を比較するとどうですか?

Drizzle はより SQL 指向であり、実行時のオーバーヘッドがありません (クエリ エンジンがありません)。 Prisma は独自のクエリ言語を使用し、生成されたクライアントを必要とします。 Drizzle はバンドル サイズが小さく、コールド スタートが高速ですが、Prisma はより大きなエコシステムとより多くのツールを備えています。

Q: Drizzle は複雑な生の SQL を処理できますか?

はい。 SQL テンプレート リテラルは、パラメーター化された安全性を維持しながら、生のクエリをサポートします。 Drizzle はクエリに文字列連結を使用しないため、SQL インジェクションを防ぎます。

Q: 実稼働環境での接続プーリングについてはどうですか?

アプリケーションの外部で PgBouncer を使用するか、最大接続制限を使用して postgres.js ドライバーを構成します。サーバーレス環境の場合は、プールが組み込まれたサーバーレスに最適化されたドライバーを使用します。

Q: ダウンタイムを発生させずにスキーマ変更を処理するにはどうすればよいですか?

移行ファイルを生成し、SQL を確認し、ステージングでテストしてから、実稼働環境に適用します。 PostgreSQL のほとんどの ALTER TABLE ステートメントは、排他ロックなしで実行されます。ピーク時間帯にはテーブルの書き換えが必要な操作を避けてください。

---

次は何ですか

NestJS を使用した Drizzle ORM は、本番 API を構築するためのタイプセーフでパフォーマンスの高い基盤を提供します。 SQL に似た API は抽象化のギャップを最小限に抑え、TypeScript 推論は実行時の型エラーを排除します。

API 開発支援については ECOSIRE にお問い合わせ、カスタム API を ERP に接続するには Odoo 統合サービス をご覧ください。

---

ECOSIRE が発行 -- エンタープライズ ソフトウェア ソリューションによるビジネスの拡大を支援します。