TypeScriptとPostgreSQLで実践するDrizzle ORM入門:型安全なスキーマ設計とマイグレーション

Development tutorial - IT technology blog
Development tutorial - IT technology blog

深夜2時、本番環境で突如発生したデータベース障害

深夜2時15分、けたたましく電話が鳴り響きました。PagerDutyからのアラートが止まりません。決済エンドポイントがHTTP 500を返し、エラー率は98%に急上昇。チェックアウト画面でユーザーが立ち往生し、カスタマーサポートには問い合わせが殺到していました。

急いでノートPCを開き、サーバークラスタにSSH接続してコンテナログを確認しました。

docker logs -f --tail=100 backend-api
# Error: column users.phone_number does not exist
# at PostgresQuery.run (/app/node_modules/pg/lib/query.js:123:24)

ステージング環境をすり抜けてしまった、あまりにも初歩的なミスでした。フロントエンドはキャメルケースのphoneNumberでリクエストを送り、バックエンドはそれをphone_numberにマッピングしていました。しかし、肝心のSQLマイグレーションファイルはPull Requestに残ったままで、本番データベースにはまだ適用されていなかったのです。

コードのコンパイルは問題なく通り、ユニットテストもすべてパスしていました。しかし、本番データに触れた瞬間にクラッシュしたのです。これは、アプリケーションの型定義とデータベーススキーマが乖離しているときによく起こる典型的なシナリオです。

TypeScriptとデータベースエンジンの間に潜む溝

1. SQLマイグレーションとアプリケーション型の乖離

多くの開発チームでは、生SQLファイルでマイグレーションを作成し、アプリケーション層でTypeScriptインターフェースを手動で再定義するアプローチを採用しています。

// models/user.ts
interface User {
  id: string;
  phoneNumber: string; // 実際のデータベース側は phone_number になっているか、カラム自体が未追加!
}

この運用は完全に人間の記憶力に依存しています。開発者がSQL側のカラム名を変更したのに型定義の更新を忘れたり、マイグレーションの実行前にコードをデプロイしてしまえば、即座にランタイムエラーが引き起こされます。

2. 従来のORMが抱えるパフォーマンスオーバーヘッド

以前はPrismaやTypeORMが私の第一候補でした。しかし、ServerlessやEdge Runtime(Vercel上のNext.jsやCloudflare Workers上のHonoなど)へ移行するにつれ、新たな課題が浮き彫りになってきました。

PrismaのRustバイナリ製クエリエンジンは約40MBものサイズがあります。これによりコールドスタート時間は80msから800ms〜1.2秒へと跳ね上がり、Alpineコンテナ上のRAM消費量も倍増してしまいます。

現行ソリューションの比較検討

アプローチ1:生クエリによる手動型キャスト(pg / postgres.js)

生クエリを実行し、結果をas Userのように型アサーションする方法です。実行速度は最速でバンドルサイズも極めて軽量ですが、型安全性は名ばかりに過ぎません。データベース側のカラム名を変更しても、コンパイラは一切警告を出してくれません。

アプローチ2:独自DSLを採用するORM(Prisma)

型安全性には優れています。しかし、schema.prismaファイル固有のDSL(ドメイン特化言語)を習得する必要があり、中間コード生成コマンドの実行も欠かせません。同梱されるバイナリエンジンも、イベント駆動型の軽量環境には重すぎます。

アプローチ3:Drizzle ORM – 純粋なTypeScriptによるSingle Source of Truth

Drizzleのアプローチは異なります。TypeScript自体をスキーマ定義言語として扱うため、バイナリエンジンも複雑なコード生成ステップも不要です。コードから型が自動推論され、生成されるSQLクエリも常に明確で透過的です。

PostgreSQLとDrizzle ORMの実装手順

ステップ1:依存パッケージのインストール

Next.js App RouterでもHonoによるマイクロサービスでも、必要なパッケージは以下の通りです。

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

ステップ2:型安全なスキーマの定義

src/db/schema.tsを作成します。テーブル構造、データ型、制約条件のすべてをTypeScriptで記述します。

import { pgTable, serial, text, varchar, timestamp, boolean } from 'drizzle-orm/pg-core';

export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  fullName: varchar('full_name', { length: 256 }).notNull(),
  email: text('email').notNull().unique(),
  phoneNumber: varchar('phone_number', { length: 20 }),
  isActive: boolean('is_active').default(true).notNull(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
});

// 自動型推論:スキーマを修正すれば型も自動的に追従して更新
export type User = typeof users.$inferSelect;
export type NewUser = typeof users.$inferInsert;

別途インターフェースを手作業で書く必要はありません。スキーマのカラム名を変更すれば、コードベース内で不整合を起こしている箇所がエディタ上で即座に赤くハイライトされます。

ステップ3:マイグレーション管理用Drizzle Kitの設定

プロジェクトのルートディレクトリにdrizzle.config.tsを作成します。

import { defineConfig } from 'drizzle-kit';
import * as dotenv from 'dotenv';
dotenv.config();

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

package.jsonにスクリプトを追加します。

{
  "scripts": {
    "db:generate": "drizzle-kit generate",
    "db:migrate": "tsx src/db/migrate.ts",
    "db:studio": "drizzle-kit studio"
  }
}

スキーマを変更するたびに、以下のコマンドを実行します。

npm run db:generate

Drizzle KitはTypeScriptスキーマと前回のスナップショットを比較検証し、./drizzle/migrations配下に連番のSQLマイグレーションファイルを生成します。データベースに対してどのようなDDL文が実行されるのかを100%把握できます。

ステップ4:起動時に実行する自動マイグレーションスクリプト

スキーマの不整合によるエラーを防ぐため、アプリケーションがリクエスト受付ポートを開く前にマイグレーションを自動実行させます。src/db/migrate.tsを作成します。

import { drizzle } from 'drizzle-orm/postgres-js';
import { migrate } from 'drizzle-orm/postgres-js/migrator';
import postgres from 'postgres';
import * as dotenv from 'dotenv';
dotenv.config();

const runMigrations = async () => {
  const connectionString = process.env.DATABASE_URL;
  if (!connectionString) {
    throw new Error('DATABASE_URL is not set');
  }

  // マイグレーション実行に必要な接続は1つのみ
  const sql = postgres(connectionString, { max: 1 });
  const db = drizzle(sql);

  console.log('⏳ マイグレーションを確認・適用中...');
  await migrate(db, { migrationsFolder: './drizzle/migrations' });
  console.log('✅ マイグレーションが正常に完了しました。');

  await sql.end();
  process.exit(0);
};

runMigrations().catch((err) => {
  console.error('❌ マイグレーション失敗:', err);
  process.exit(1);
});

ステップ5:Hono APIおよびNext.jsへの統合

ホットリロード時のコネクションプール枯渇を防ぐため、src/db/index.tsでシングルトンクライアントを初期化します。

import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';
import * as schema from './schema';

const connectionString = process.env.DATABASE_URL!;

const globalForDb = globalThis as unknown as { conn: postgres.Sql | undefined };
const client = globalForDb.conn ?? postgres(connectionString);
if (process.env.NODE_ENV !== 'production') globalForDb.conn = client;

export const db = drizzle(client, { schema });

Hono APIと組み合わせると、簡潔なコードで完全な型安全性を維持できます。

import { Hono } from 'hono';
import { db } from './db';
import { users } from './db/schema';
import { eq } from 'drizzle-orm';

const app = new Hono();

app.get('/users/:id', async (c) => {
  const id = Number(c.req.param('id'));
  if (Number.isNaN(id)) {
    return c.json({ error: '無効なIDです' }, 400);
  }
  
  const result = await db.select().from(users).where(eq(users.id, id)).limit(1);
  
  if (result.length === 0) {
    return c.json({ error: 'ユーザーが見つかりません' }, 404);
  }

  return c.json({ data: result[0] });
});

export default app;

Next.js Server Actionsでは、推論された型定義をそのまま再利用できます。

// app/actions/create-user.ts
'use server';

import { db } from '@/db';
import { users, type NewUser } from '@/db/schema';

export async function createUser(data: NewUser) {
  const [inserted] = await db.insert(users).values(data).returning();
  return inserted;
}

本番運用のベストプラクティス

Drizzle ORMを導入すれば、バンドルサイズを最小限に抑えつつ、コードとデータベース間の型同期問題を根本から解決できます。CI/CDパイプラインにおいては、コンテナのエントリーポイントや事前デプロイステップにnpm run db:migrateを組み込むのが推奨パターンです。スキーマ定義とデータベースが常に同期していれば、システムは安定稼働し、開発者も深夜のアラートに怯えることなく安心して眠りにつくことができます。

Share: