PostgreSQL を使用した ORM の霧雨: 完全ガイド

Drizzle ORM は TypeScript データベースエコシステムの中で独自の位置を占めています。ORM は実際にはクエリビルダーにすぎず、読み取り可能な SQL を生成するコードとしてのスキーマと、データベースを信頼できる情報源のように扱う移行システムを備えています。 Prisma と TypeORM を何年も使用した後、Drizzle は生の SQL に戻ってきたように感じますが、完全な TypeScript 推論と実行時のオーバーヘッドはゼロです。

このガイドでは、初期セットアップから運用パターン、65 を超える Drizzle スキーマファイルを含むコードベースからの描画、マルチテナントクエリ、Next.js と NestJS の両方のコンテキストで確実に動作する遅延プロキシ接続パターンまで、すべてを説明します。

重要なポイント

DB 接続には遅延プロキシを使用します。モジュールのロード時に積極的な接続を作成しないでください。

システムインストールとの競合を避けるために、ローカル PostgreSQL はデフォルト以外のポート (5433) で実行する必要があります。

マルチテナンシーにはすべてのテーブルに organizationId が必要です — スキーマレベルで強制します

Drizzle 列挙型の比較では、型を絞り込むために明示的な TypeScript キャストが必要です

sql.raw() は決して使用しないでください。パラメーター化された値を持つ sql テンプレートリテラルを常に使用してください。

リレーションは外部キーとは別のものです - 完全な型安全性のために両方を定義します

トランザクションは複数ステップの操作をラップします。 tx オブジェクトをサービスに渡します

移行が機能するためには、スキーマインデックス (schema/index.ts) がすべてのテーブルをエクスポートする必要があります

インストールとセットアップ

Drizzle には、コア ORM とデータベースドライバーの 2 つのパッケージが必要です。

pnpm add drizzle-orm pg
pnpm add -D drizzle-kit @types/pg

移行とスタジオを含むフルスタックの場合:

pnpm add drizzle-orm postgres
pnpm add -D drizzle-kit

postgres パッケージ (pg とは異なります) は、最新の TypeScript プロジェクトにおける Drizzle の推奨ドライバーです。接続プーリング、プリペアドステートメントをサポートし、より優れた TypeScript 型を備えています。

遅延プロキシパターン

Next.js または NestJS モノリポジトリで Drizzle を使用する場合のアーキテクチャ上の最も重要な決定は、積極的なデータベース接続を決して作成しないことです。モジュールのロード時に積極的に接続すると、次の問題が発生します。

Next.js: モジュールはビルドプロセス中にインポートされますが、利用可能な DB はありません
NestJS: 環境変数が読み込まれる前にパッケージのインポートが行われます。
サーバーレス: 接続オーバーヘッドによりコールドスタートが遅延する

Lazy Proxy パターンはこれらすべてを解決します。

// packages/db/src/index.ts
import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';
import * as schema from './schema';

let _db: ReturnType<typeof drizzle> | null = null;

function getDb() {
  if (!_db) {
    const connectionString = process.env.DATABASE_URL;
    if (!connectionString) {
      throw new Error('DATABASE_URL environment variable is not set');
    }

    const client = postgres(connectionString, {
      max: 10, // connection pool size
      idle_timeout: 20,
      connect_timeout: 10,
    });

    _db = drizzle(client, { schema });
  }
  return _db;
}

// Export a Proxy that initializes the connection on first use
export const db = new Proxy({} as ReturnType<typeof drizzle>, {
  get(_, prop) {
    return getDb()[prop as keyof ReturnType<typeof drizzle>];
  },
});

export * from './schema';

このパターンは、@ecosire/db をインポートしてもデータベース接続が開かれないことを意味します。接続は、最初のクエリが実行されたときにのみ作成されます。

スキーマ設計

Drizzle スキーマは、テーブル定義をエクスポートするプレーンな TypeScript ファイルです。ここでの原則は、関連するテーブルを同じファイル内に保持し、中央のインデックスを通じてすべてをエクスポートすることです。

// packages/db/src/schema/contacts.ts
import {
  pgTable,
  uuid,
  text,
  varchar,
  timestamp,
  pgEnum,
  boolean,
  index,
} from 'drizzle-orm/pg-core';

export const contactTypeEnum = pgEnum('contact_type', ['individual', 'company', 'partner']);

export const contacts = pgTable(
  'contacts',
  {
    id: uuid('id').defaultRandom().primaryKey(),
    organizationId: uuid('organization_id').notNull(), // Multi-tenancy
    name: varchar('name', { length: 255 }).notNull(),
    email: varchar('email', { length: 255 }),
    phone: varchar('phone', { length: 50 }),
    type: contactTypeEnum('type').default('individual').notNull(),
    isActive: boolean('is_active').default(true).notNull(),
    notes: text('notes'),
    createdAt: timestamp('created_at').defaultNow().notNull(),
    updatedAt: timestamp('updated_at').defaultNow().notNull(),
  },
  (table) => ({
    organizationIdx: index('contacts_organization_idx').on(table.organizationId),
    emailIdx: index('contacts_email_idx').on(table.email),
  })
);

export type Contact = typeof contacts.$inferSelect;
export type NewContact = typeof contacts.$inferInsert;

$inferSelect 型と $inferInsert 型を使用すると、完全な TypeScript 推論が可能になります。Drizzle は、スキーマの制約に基づいて、挿入時にどのフィールドが必須であるかオプションであるかを認識します。

// packages/db/src/schema/index.ts
export * from './contacts';
export * from './orders';
export * from './licenses';
export * from './products';
// ... all tables

インデックスファイルは、drizzle-kit のすべてのテーブルをエクスポートして、移行の生成中にそれらのテーブルを取得する必要があります。

関係

Drizzle は、外部キー制約 (PostgreSQL によって強制される) をリレーション定義 (Drizzle のリレーショナルクエリ API によって使用される) から分離します。両方が必要です:

// packages/db/src/schema/relations.ts
import { relations } from 'drizzle-orm';
import { contacts } from './contacts';
import { orders } from './orders';
import { orderItems } from './order-items';
import { products } from './products';

export const contactsRelations = relations(contacts, ({ many }) => ({
  orders: many(orders),
}));

export const ordersRelations = relations(orders, ({ one, many }) => ({
  contact: one(contacts, {
    fields: [orders.contactId],
    references: [contacts.id],
  }),
  items: many(orderItems),
}));

export const orderItemsRelations = relations(orderItems, ({ one }) => ({
  order: one(orders, {
    fields: [orderItems.orderId],
    references: [orders.id],
  }),
  product: one(products, {
    fields: [orderItems.productId],
    references: [products.id],
  }),
}));

リレーションを定義すると、Drizzle のリレーショナルクエリ API を使用できます。

// Fetch order with contact and items in one query
const order = await db.query.orders.findFirst({
  where: eq(orders.id, orderId),
  with: {
    contact: true,
    items: {
      with: {
        product: true,
      },
    },
  },
});

Drizzle は単一の JOIN クエリを生成します。N+1 の問題はありません。

タイプセーフなクエリ

Drizzle のクエリ API は完全にタイプセーフです。選択タイプは、含める列に基づいて絞り込まれます。

import { db } from '@ecosire/db';
import { contacts } from '@ecosire/db/schema';
import { eq, and, like, sql, count } from 'drizzle-orm';

// Full select — returns Contact[]
const allContacts = await db
  .select()
  .from(contacts)
  .where(eq(contacts.organizationId, orgId))
  .limit(50);

// Partial select — returns only specified columns
const contactNames = await db
  .select({
    id: contacts.id,
    name: contacts.name,
    email: contacts.email,
  })
  .from(contacts)
  .where(
    and(
      eq(contacts.organizationId, orgId),
      eq(contacts.isActive, true)
    )
  );

// Count query
const [{ total }] = await db
  .select({ total: count() })
  .from(contacts)
  .where(eq(contacts.organizationId, orgId));

// Search with ILIKE (case-insensitive)
const searchResults = await db
  .select()
  .from(contacts)
  .where(
    and(
      eq(contacts.organizationId, orgId),
      like(contacts.name, `%${searchTerm}%`)
    )
  )
  .limit(20);

動的な where 句 (UI からのフィルター) の場合は、条件付きで条件を構築します。

import { SQL } from 'drizzle-orm';

async function searchContacts(orgId: string, filters: {
  search?: string;
  type?: 'individual' | 'company';
  isActive?: boolean;
}) {
  const conditions: SQL[] = [eq(contacts.organizationId, orgId)];

  if (filters.search) {
    conditions.push(like(contacts.name, `%${filters.search}%`));
  }

  if (filters.type) {
    // Enum comparisons need explicit casting
    conditions.push(eq(contacts.type, filters.type as 'individual' | 'company' | 'partner'));
  }

  if (filters.isActive !== undefined) {
    conditions.push(eq(contacts.isActive, filters.isActive));
  }

  return db
    .select()
    .from(contacts)
    .where(and(...conditions))
    .limit(100);
}

enum 値の明示的なキャストに注意してください: filters.type as 'individual' | 'company' | 'partner'。 Drizzle の列挙型は、キャストなしでは、より狭い文字列サブタイプを自動的に受け入れません。

挿入、更新、および削除

import { db } from '@ecosire/db';
import { contacts, NewContact } from '@ecosire/db/schema';
import { eq, and } from 'drizzle-orm';

// Insert with RETURNING
async function createContact(data: NewContact) {
  const [created] = await db
    .insert(contacts)
    .values(data)
    .returning();

  return created; // Fully typed as Contact
}

// Upsert (insert or update on conflict)
async function upsertContact(data: NewContact) {
  const [result] = await db
    .insert(contacts)
    .values(data)
    .onConflictDoUpdate({
      target: [contacts.organizationId, contacts.email],
      set: {
        name: data.name,
        updatedAt: new Date(),
      },
    })
    .returning();

  return result;
}

// Update with RETURNING
async function updateContact(
  id: string,
  orgId: string,
  updates: Partial<NewContact>
) {
  const [updated] = await db
    .update(contacts)
    .set({ ...updates, updatedAt: new Date() })
    .where(
      and(
        eq(contacts.id, id),
        eq(contacts.organizationId, orgId) // Always filter by org
      )
    )
    .returning();

  return updated;
}

// Soft delete (recommended over hard delete)
async function deleteContact(id: string, orgId: string) {
  return db
    .update(contacts)
    .set({ isActive: false, updatedAt: new Date() })
    .where(
      and(
        eq(contacts.id, id),
        eq(contacts.organizationId, orgId)
      )
    );
}

INSERT および UPDATE ステートメントでは常に .returning() を使用します。これにより、作成/更新されたレコードを取得するための 2 回目の SELECT ラウンドトリップが回避されます。

トランザクション

同時に成功または失敗する必要がある複数ステップの操作にはトランザクションが必要です。

async function createOrderWithItems(
  orderData: NewOrder,
  items: NewOrderItem[]
) {
  return db.transaction(async (tx) => {
    // Create the order
    const [order] = await tx
      .insert(orders)
      .values(orderData)
      .returning();

    // Create order items
    const createdItems = await tx
      .insert(orderItems)
      .values(items.map((item) => ({ ...item, orderId: order.id })))
      .returning();

    // Update inventory (must succeed or entire transaction rolls back)
    for (const item of items) {
      await tx
        .update(products)
        .set({
          stock: sql`${products.stock} - ${item.quantity}`,
        })
        .where(eq(products.id, item.productId));
    }

    return { order, items: createdItems };
  });
}

トランザクションコンテキストをサービスメソッドに渡す場合:

// Service accepts optional transaction for composability
async function activateLicense(
  licenseId: string,
  tx?: typeof db | Parameters<Parameters<typeof db.transaction>[0]>[0]
) {
  const queryRunner = tx || db;

  return queryRunner
    .update(licenses)
    .set({ status: 'active', activatedAt: new Date() })
    .where(eq(licenses.id, licenseId))
    .returning();
}

drizzle-kit を使用した移行

drizzle-kit CLI は、スキーマ変更から移行を生成します。

// drizzle.config.ts
import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  schema: './src/schema/index.ts',
  out: './src/migrations',
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
  verbose: true,
  strict: true,
});

ワークフロー:

# Generate migration SQL from schema changes
npx drizzle-kit generate

# Apply migrations to database
npx drizzle-kit migrate

# Push schema directly (dev only — skips migration files)
npx drizzle-kit push

# Open Drizzle Studio (visual database browser)
npx drizzle-kit studio

運用環境では、常に migrate (push ではない) を使用してください。 push コマンドはローカル開発反復用です。移行ファイルは作成されないため、変更は追跡されません。

ページネーションパターン

効率的なページネーションには、データクエリとカウントクエリの両方が必要です。

interface PaginationParams {
  page: number;
  pageSize: number;
}

async function getContactsPaginated(orgId: string, { page, pageSize }: PaginationParams) {
  const offset = (page - 1) * pageSize;

  const [data, [{ total }]] = await Promise.all([
    db
      .select()
      .from(contacts)
      .where(eq(contacts.organizationId, orgId))
      .limit(pageSize)
      .offset(offset)
      .orderBy(contacts.createdAt),
    db
      .select({ total: count() })
      .from(contacts)
      .where(eq(contacts.organizationId, orgId)),
  ]);

  return {
    data,
    pagination: {
      page,
      pageSize,
      total,
      totalPages: Math.ceil(total / pageSize),
    },
  };
}

Promise.all を使用して両方のクエリを並行して実行すると、順次実行に比べて応答時間が半分になります。

よくある落とし穴と解決策

落とし穴 1: 動的クエリに sql.raw() を使用する

// Dangerous — SQL injection vulnerability
const results = await db.execute(
  sql.raw(`SELECT * FROM contacts WHERE name = '${userInput}'`)
);

// Safe — parameterized
const results = await db.execute(
  sql`SELECT * FROM contacts WHERE name = ${userInput}`
);

落とし穴 2: 頻繁にクエリされる列のインデックスが欠落している

フィルターに使用する列には必ずインデックスを追加してください。最も一般的な欠落インデックスは次のとおりです。

(table) => ({
  organizationIdx: index('contacts_org_idx').on(table.organizationId),
  emailIdx: index('contacts_email_idx').on(table.email),
  compositeIdx: index('contacts_org_active_idx').on(
    table.organizationId,
    table.isActive
  ),
})

落とし穴 3: 手動リレーション読み込みによる N+1 クエリ

// N+1 problem — one query per order
const orders = await db.select().from(ordersTable);
for (const order of orders) {
  order.contact = await db
    .select()
    .from(contacts)
    .where(eq(contacts.id, order.contactId));
}

// Solution — use Drizzle's relational query API
const orders = await db.query.orders.findMany({
  with: { contact: true },
});

落とし穴 4: schema/index.ts から新しいテーブルをエクスポートするのを忘れる

新しいスキーマファイルを作成したが、schema/index.ts から再エクスポートするのを忘れた場合、drizzle-kit は新しいテーブルを認識せず、移行は生成されません。

よくある質問

TypeScript プロジェクトにおける Drizzle と Prisma を比較するとどうですか?

Drizzle は TypeScript 型を使用した生の SQL に近く、SQL に 1:1 でマップするクエリを作成します。 Prisma は、カスタムクエリ言語と別個のスキーマファイルを使用して、さらに抽象化します。 Drizzle は、複雑なクエリでの TypeScript 推論が優れており、実行時のオーバーヘッドが小さく、コード生成手順が必要ありません。 Prisma には、より大規模なエコシステムと、論理的な削除や監査ログなどのより多くの組み込み機能があります。 SQL に慣れている大規模なチームには、一般に Drizzle が好まれます。

drizzle-kit プッシュを使用するべきですか、それとも CI/CD で移行するべきですか?

CI/CD では常に drizzle-kit migrate を使用してください。 push コマンドは、迅速なローカル開発用です。移行ファイルを作成せずにスキーマの変更を直接適用するため、監査証跡がなく、ロールバックが困難です。デプロイメントパイプラインでは、アプリケーションを開始する前に drizzle-kit migrate を実行して、スキーマが同期されていることを確認します。

Drizzle でデータベースシードを処理するにはどうすればよいですか?

別のシードファイルを作成し、スキーマを直接インポートします。再実行時に失敗しない冪等シードには onConflictDoNothing() を使用します。簡単に更新できるようにシードデータを定数に保存し、移行後に開発セットアップスクリプトでシードを実行します。

Drizzle と PostgreSQL を使用して全文検索を実行するにはどうすればよいですか?

PostgreSQL の to_tsvector および to_tsquery 関数では、sql テンプレートリテラルを使用します。 Drizzle は全文検索を抽象化しませんが、直接記述することができます。パフォーマンスを向上させるために tsvector 列に GIN インデックスを追加し、自然言語クエリを安全に解析するためにユーザー指定の検索語に websearch_to_tsquery を使用します。

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

追加的な移行を使用します。最初に列を NULL 可能として追加し、データをバックフィルしてから、NOT NULL 制約を追加します。コードから列を削除するのと同じ移行で列を削除しないでください。順序は次のとおりです: 1) 古い列を無視するコードをデプロイし、2) 古い列を削除するために移行をデプロイします。これにより、データを損失することなく常にロールバックが可能になります。

次のステップ

適切に設計されたデータベース層は、すべての実稼働アプリケーションが構築される基盤です。 ECOSIRE のエンジニアリングチームは、Drizzle ORM と PostgreSQL を毎日使用して、複雑なマルチテナントシステム全体で 65 以上のスキーマファイルを管理しています。

データベースアーキテクチャコンサルティング、Odoo ERP 統合、または最新の TypeScript ツールで構築された完全なバックエンドシステムが必要な場合でも、当社のサービスを探索して、当社がどのようにお手伝いできるかをご確認ください。

PostgreSQL を使用した ORM の霧雨: 完全ガイド

重要なポイント

DB 接続には遅延プロキシを使用します。モジュールのロード時に積極的な接続を作成しないでください。

システムインストールとの競合を避けるために、ローカル PostgreSQL はデフォルト以外のポート (5433) で実行する必要があります。

マルチテナンシーにはすべてのテーブルに organizationId が必要です — スキーマレベルで強制します

Drizzle 列挙型の比較では、型を絞り込むために明示的な TypeScript キャストが必要です

sql.raw() は決して使用しないでください。パラメーター化された値を持つ sql テンプレートリテラルを常に使用してください。

リレーションは外部キーとは別のものです - 完全な型安全性のために両方を定義します

トランザクションは複数ステップの操作をラップします。 tx オブジェクトをサービスに渡します

移行が機能するためには、スキーマインデックス (schema/index.ts) がすべてのテーブルをエクスポートする必要があります

インストールとセットアップ

Drizzle には、コア ORM とデータベースドライバーの 2 つのパッケージが必要です。

pnpm add drizzle-orm pg
pnpm add -D drizzle-kit @types/pg

移行とスタジオを含むフルスタックの場合:

pnpm add drizzle-orm postgres
pnpm add -D drizzle-kit

遅延プロキシパターン

Next.js: モジュールはビルドプロセス中にインポートされますが、利用可能な DB はありません
NestJS: 環境変数が読み込まれる前にパッケージのインポートが行われます。
サーバーレス: 接続オーバーヘッドによりコールドスタートが遅延する

Lazy Proxy パターンはこれらすべてを解決します。

// packages/db/src/index.ts
import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';
import * as schema from './schema';

let _db: ReturnType<typeof drizzle> | null = null;

function getDb() {
  if (!_db) {
    const connectionString = process.env.DATABASE_URL;
    if (!connectionString) {
      throw new Error('DATABASE_URL environment variable is not set');
    }

    const client = postgres(connectionString, {
      max: 10, // connection pool size
      idle_timeout: 20,
      connect_timeout: 10,
    });

    _db = drizzle(client, { schema });
  }
  return _db;
}

// Export a Proxy that initializes the connection on first use
export const db = new Proxy({} as ReturnType<typeof drizzle>, {
  get(_, prop) {
    return getDb()[prop as keyof ReturnType<typeof drizzle>];
  },
});

export * from './schema';

スキーマ設計

// packages/db/src/schema/contacts.ts
import {
  pgTable,
  uuid,
  text,
  varchar,
  timestamp,
  pgEnum,
  boolean,
  index,
} from 'drizzle-orm/pg-core';

export const contactTypeEnum = pgEnum('contact_type', ['individual', 'company', 'partner']);

export const contacts = pgTable(
  'contacts',
  {
    id: uuid('id').defaultRandom().primaryKey(),
    organizationId: uuid('organization_id').notNull(), // Multi-tenancy
    name: varchar('name', { length: 255 }).notNull(),
    email: varchar('email', { length: 255 }),
    phone: varchar('phone', { length: 50 }),
    type: contactTypeEnum('type').default('individual').notNull(),
    isActive: boolean('is_active').default(true).notNull(),
    notes: text('notes'),
    createdAt: timestamp('created_at').defaultNow().notNull(),
    updatedAt: timestamp('updated_at').defaultNow().notNull(),
  },
  (table) => ({
    organizationIdx: index('contacts_organization_idx').on(table.organizationId),
    emailIdx: index('contacts_email_idx').on(table.email),
  })
);

export type Contact = typeof contacts.$inferSelect;
export type NewContact = typeof contacts.$inferInsert;

// packages/db/src/schema/index.ts
export * from './contacts';
export * from './orders';
export * from './licenses';
export * from './products';
// ... all tables

インデックスファイルは、drizzle-kit のすべてのテーブルをエクスポートして、移行の生成中にそれらのテーブルを取得する必要があります。

関係

// packages/db/src/schema/relations.ts
import { relations } from 'drizzle-orm';
import { contacts } from './contacts';
import { orders } from './orders';
import { orderItems } from './order-items';
import { products } from './products';

export const contactsRelations = relations(contacts, ({ many }) => ({
  orders: many(orders),
}));

export const ordersRelations = relations(orders, ({ one, many }) => ({
  contact: one(contacts, {
    fields: [orders.contactId],
    references: [contacts.id],
  }),
  items: many(orderItems),
}));

export const orderItemsRelations = relations(orderItems, ({ one }) => ({
  order: one(orders, {
    fields: [orderItems.orderId],
    references: [orders.id],
  }),
  product: one(products, {
    fields: [orderItems.productId],
    references: [products.id],
  }),
}));

リレーションを定義すると、Drizzle のリレーショナルクエリ API を使用できます。

// Fetch order with contact and items in one query
const order = await db.query.orders.findFirst({
  where: eq(orders.id, orderId),
  with: {
    contact: true,
    items: {
      with: {
        product: true,
      },
    },
  },
});

Drizzle は単一の JOIN クエリを生成します。N+1 の問題はありません。

タイプセーフなクエリ

Drizzle のクエリ API は完全にタイプセーフです。選択タイプは、含める列に基づいて絞り込まれます。

import { db } from '@ecosire/db';
import { contacts } from '@ecosire/db/schema';
import { eq, and, like, sql, count } from 'drizzle-orm';

// Full select — returns Contact[]
const allContacts = await db
  .select()
  .from(contacts)
  .where(eq(contacts.organizationId, orgId))
  .limit(50);

// Partial select — returns only specified columns
const contactNames = await db
  .select({
    id: contacts.id,
    name: contacts.name,
    email: contacts.email,
  })
  .from(contacts)
  .where(
    and(
      eq(contacts.organizationId, orgId),
      eq(contacts.isActive, true)
    )
  );

// Count query
const [{ total }] = await db
  .select({ total: count() })
  .from(contacts)
  .where(eq(contacts.organizationId, orgId));

// Search with ILIKE (case-insensitive)
const searchResults = await db
  .select()
  .from(contacts)
  .where(
    and(
      eq(contacts.organizationId, orgId),
      like(contacts.name, `%${searchTerm}%`)
    )
  )
  .limit(20);

動的な where 句 (UI からのフィルター) の場合は、条件付きで条件を構築します。

import { SQL } from 'drizzle-orm';

async function searchContacts(orgId: string, filters: {
  search?: string;
  type?: 'individual' | 'company';
  isActive?: boolean;
}) {
  const conditions: SQL[] = [eq(contacts.organizationId, orgId)];

  if (filters.search) {
    conditions.push(like(contacts.name, `%${filters.search}%`));
  }

  if (filters.type) {
    // Enum comparisons need explicit casting
    conditions.push(eq(contacts.type, filters.type as 'individual' | 'company' | 'partner'));
  }

  if (filters.isActive !== undefined) {
    conditions.push(eq(contacts.isActive, filters.isActive));
  }

  return db
    .select()
    .from(contacts)
    .where(and(...conditions))
    .limit(100);
}

挿入、更新、および削除

import { db } from '@ecosire/db';
import { contacts, NewContact } from '@ecosire/db/schema';
import { eq, and } from 'drizzle-orm';

// Insert with RETURNING
async function createContact(data: NewContact) {
  const [created] = await db
    .insert(contacts)
    .values(data)
    .returning();

  return created; // Fully typed as Contact
}

// Upsert (insert or update on conflict)
async function upsertContact(data: NewContact) {
  const [result] = await db
    .insert(contacts)
    .values(data)
    .onConflictDoUpdate({
      target: [contacts.organizationId, contacts.email],
      set: {
        name: data.name,
        updatedAt: new Date(),
      },
    })
    .returning();

  return result;
}

// Update with RETURNING
async function updateContact(
  id: string,
  orgId: string,
  updates: Partial<NewContact>
) {
  const [updated] = await db
    .update(contacts)
    .set({ ...updates, updatedAt: new Date() })
    .where(
      and(
        eq(contacts.id, id),
        eq(contacts.organizationId, orgId) // Always filter by org
      )
    )
    .returning();

  return updated;
}

// Soft delete (recommended over hard delete)
async function deleteContact(id: string, orgId: string) {
  return db
    .update(contacts)
    .set({ isActive: false, updatedAt: new Date() })
    .where(
      and(
        eq(contacts.id, id),
        eq(contacts.organizationId, orgId)
      )
    );
}

トランザクション

同時に成功または失敗する必要がある複数ステップの操作にはトランザクションが必要です。

async function createOrderWithItems(
  orderData: NewOrder,
  items: NewOrderItem[]
) {
  return db.transaction(async (tx) => {
    // Create the order
    const [order] = await tx
      .insert(orders)
      .values(orderData)
      .returning();

    // Create order items
    const createdItems = await tx
      .insert(orderItems)
      .values(items.map((item) => ({ ...item, orderId: order.id })))
      .returning();

    // Update inventory (must succeed or entire transaction rolls back)
    for (const item of items) {
      await tx
        .update(products)
        .set({
          stock: sql`${products.stock} - ${item.quantity}`,
        })
        .where(eq(products.id, item.productId));
    }

    return { order, items: createdItems };
  });
}

トランザクションコンテキストをサービスメソッドに渡す場合:

// Service accepts optional transaction for composability
async function activateLicense(
  licenseId: string,
  tx?: typeof db | Parameters<Parameters<typeof db.transaction>[0]>[0]
) {
  const queryRunner = tx || db;

  return queryRunner
    .update(licenses)
    .set({ status: 'active', activatedAt: new Date() })
    .where(eq(licenses.id, licenseId))
    .returning();
}

drizzle-kit を使用した移行

drizzle-kit CLI は、スキーマ変更から移行を生成します。

// drizzle.config.ts
import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  schema: './src/schema/index.ts',
  out: './src/migrations',
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
  verbose: true,
  strict: true,
});

ワークフロー:

# Generate migration SQL from schema changes
npx drizzle-kit generate

# Apply migrations to database
npx drizzle-kit migrate

# Push schema directly (dev only — skips migration files)
npx drizzle-kit push

# Open Drizzle Studio (visual database browser)
npx drizzle-kit studio

ページネーションパターン

効率的なページネーションには、データクエリとカウントクエリの両方が必要です。

interface PaginationParams {
  page: number;
  pageSize: number;
}

async function getContactsPaginated(orgId: string, { page, pageSize }: PaginationParams) {
  const offset = (page - 1) * pageSize;

  const [data, [{ total }]] = await Promise.all([
    db
      .select()
      .from(contacts)
      .where(eq(contacts.organizationId, orgId))
      .limit(pageSize)
      .offset(offset)
      .orderBy(contacts.createdAt),
    db
      .select({ total: count() })
      .from(contacts)
      .where(eq(contacts.organizationId, orgId)),
  ]);

  return {
    data,
    pagination: {
      page,
      pageSize,
      total,
      totalPages: Math.ceil(total / pageSize),
    },
  };
}

Promise.all を使用して両方のクエリを並行して実行すると、順次実行に比べて応答時間が半分になります。

よくある落とし穴と解決策

落とし穴 1: 動的クエリに sql.raw() を使用する

// Dangerous — SQL injection vulnerability
const results = await db.execute(
  sql.raw(`SELECT * FROM contacts WHERE name = '${userInput}'`)
);

// Safe — parameterized
const results = await db.execute(
  sql`SELECT * FROM contacts WHERE name = ${userInput}`
);

落とし穴 2: 頻繁にクエリされる列のインデックスが欠落している

フィルターに使用する列には必ずインデックスを追加してください。最も一般的な欠落インデックスは次のとおりです。

(table) => ({
  organizationIdx: index('contacts_org_idx').on(table.organizationId),
  emailIdx: index('contacts_email_idx').on(table.email),
  compositeIdx: index('contacts_org_active_idx').on(
    table.organizationId,
    table.isActive
  ),
})

落とし穴 3: 手動リレーション読み込みによる N+1 クエリ

// N+1 problem — one query per order
const orders = await db.select().from(ordersTable);
for (const order of orders) {
  order.contact = await db
    .select()
    .from(contacts)
    .where(eq(contacts.id, order.contactId));
}

// Solution — use Drizzle's relational query API
const orders = await db.query.orders.findMany({
  with: { contact: true },
});

落とし穴 4: schema/index.ts から新しいテーブルをエクスポートするのを忘れる

よくある質問

TypeScript プロジェクトにおける Drizzle と Prisma を比較するとどうですか?

drizzle-kit プッシュを使用するべきですか、それとも CI/CD で移行するべきですか?

Drizzle でデータベースシードを処理するにはどうすればよいですか?

Drizzle と PostgreSQL を使用して全文検索を実行するにはどうすればよいですか?

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

PostgreSQL を使用した Drizzle ORM: 完全ガイド

PostgreSQL を使用した ORM の霧雨: 完全ガイド

インストールとセットアップ

遅延プロキシパターン

スキーマ設計

関係

タイプセーフなクエリ

挿入、更新、および削除

トランザクション

drizzle-kit を使用した移行

ページネーションパターン

よくある落とし穴と解決策

よくある質問

次のステップ

関連記事

Drizzle ORM によるゼロダウンタイムのデータベース移行

Odoo パフォーマンスチューニング: PostgreSQL とサーバーの最適化

OpenClaw を使用した自然言語データベースクエリ

PostgreSQL を使用した Drizzle ORM: 完全ガイド

PostgreSQL を使用した ORM の霧雨: 完全ガイド

インストールとセットアップ

遅延プロキシパターン

スキーマ設計

関係

タイプセーフなクエリ

挿入、更新、および削除

トランザクション

drizzle-kit を使用した移行

ページネーションパターン

よくある落とし穴と解決策

よくある質問

次のステップ

関連記事

Drizzle ORM によるゼロダウンタイムのデータベース移行

Odoo パフォーマンスチューニング: PostgreSQL とサーバーの最適化

OpenClaw を使用した自然言語データベースクエリ

PostgreSQL を使用した Drizzle ORM: 完全ガイド

PostgreSQL を使用した ORM の霧雨: 完全ガイド

インストールとセットアップ

遅延プロキシ パターン

スキーマ設計

関係

タイプセーフなクエリ

挿入、更新、および削除

トランザクション

drizzle-kit を使用した移行

ページネーション パターン

よくある落とし穴と解決策

よくある質問

次のステップ

関連記事

Drizzle ORM によるゼロダウンタイムのデータベース移行

Odoo パフォーマンス チューニング: PostgreSQL とサーバーの最適化

OpenClaw を使用した自然言語データベース クエリ

PostgreSQL を使用した Drizzle ORM: 完全ガイド

PostgreSQL を使用した ORM の霧雨: 完全ガイド

インストールとセットアップ

遅延プロキシ パターン

スキーマ設計

関係

タイプセーフなクエリ

挿入、更新、および削除

トランザクション

drizzle-kit を使用した移行

ページネーション パターン

よくある落とし穴と解決策

よくある質問

次のステップ

関連記事

Drizzle ORM によるゼロダウンタイムのデータベース移行

Odoo パフォーマンス チューニング: PostgreSQL とサーバーの最適化

OpenClaw を使用した自然言語データベース クエリ

遅延プロキシパターン

ページネーションパターン

Odoo パフォーマンスチューニング: PostgreSQL とサーバーの最適化

OpenClaw を使用した自然言語データベースクエリ

遅延プロキシパターン

ページネーションパターン

Odoo パフォーマンスチューニング: PostgreSQL とサーバーの最適化

OpenClaw を使用した自然言語データベースクエリ