PostgreSQL + Drizzle ORM

PostgreSQL 18 と Drizzle ORM を使用した型安全なデータベースアプリケーション。

重要なコマンド

npx drizzle-kit generate   # スキーマ変更からマイグレーションを生成
npx drizzle-kit migrate    # 保留中のマイグレーションを適用
npx drizzle-kit push       # スキーマを直接プッシュ (開発時のみ!)
npx drizzle-kit studio     # データベースブラウザを開く

クイック判断ツリー

「この関連性をどうモデル化するか?」

関連性の種類?
├─ 一対多 (ユーザーが投稿を持つ)      → FK を"多"側に + relations()
├─ 多対多 (投稿がタグを持つ)          → ジャンクションテーブル + relations()
├─ 一対一 (ユーザーがプロフィールを持つ) → FK と unique 制約
└─ 自己参照 (コメント)                 → 同じテーブルへの FK

「なぜクエリが遅いのか?」

クエリが遅い?
├─ WHERE/JOIN 列のインデックスが不足    → インデックスを追加
├─ ループ内の N+1 クエリ               → リレーショナルクエリ API を使用
├─ フルテーブルスキャン                → EXPLAIN ANALYZE、インデックスを追加
├─ 大きな結果セット                    → ページネーションを追加 (limit/offset)
└─ コネクション オーバーヘッド          → コネクションプーリングを有効化

「どの drizzle-kit コマンド?」

何が必要か?
├─ スキーマが変更、SQL マイグレーションが必要 → drizzle-kit generate
├─ マイグレーションをデータベースに適用      → drizzle-kit migrate
├─ 開発の高速イテレーション (マイグレーション不要) → drizzle-kit push
└─ ビジュアルでデータを閲覧/編集            → drizzle-kit studio

ディレクトリ構造

src/db/
├── schema/
│   ├── index.ts          # すべてのテーブルを再エクスポート
│   ├── users.ts          # テーブル + リレーション
│   └── posts.ts          # テーブル + リレーション
├── db.ts                 # プーリング付きコネクション
└── migrate.ts            # マイグレーションランナー
drizzle/
└── migrations/           # 生成された SQL ファイル
drizzle.config.ts         # drizzle-kit 設定

スキーマパターン

タイムスタンプ付きの基本テーブル

export const users = pgTable('users', {
  id: uuid('id').primaryKey().defaultRandom(),
  email: varchar('email', { length: 255 }).notNull().unique(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
});

インデックス付きの外部キー

export const posts = pgTable('posts', {
  id: uuid('id').primaryKey().defaultRandom(),
  userId: uuid('user_id').notNull().references(() => users.id),
  title: varchar('title', { length: 255 }).notNull(),
}, (table) => [
  index('posts_user_id_idx').on(table.userId), // 常に FK にインデックスを付ける
]);

リレーション

export const usersRelations = relations(users, ({ many }) => ({
  posts: many(posts),
}));

export const postsRelations = relations(posts, ({ one }) => ({
  author: one(users, { fields: [posts.userId], references: [users.id] }),
}));

クエリパターン

リレーショナルクエリ (N+1 を回避)

// ✓ ネストされたデータを含む単一クエリ
const usersWithPosts = await db.query.users.findMany({
  with: { posts: true },
});

フィルタリングされたクエリ

const activeUsers = await db
  .select()
  .from(users)
  .where(eq(users.status, 'active'));

トランザクション

await db.transaction(async (tx) => {
  const [user] = await tx.insert(users).values({ email }).returning();
  await tx.insert(profiles).values({ userId: user.id });
});

パフォーマンスチェックリスト

優先度	チェック項目	影響
重大	すべての外部キーにインデックスを付ける	JOIN でのフルテーブルスキャンを防止
重大	ネストされたデータにはリレーショナルクエリを使用	N+1 を回避
高	本番環境ではコネクションプーリングを使用	コネクションオーバーヘッドを削減
高	遅いクエリで EXPLAIN ANALYZE を実行	不足しているインデックスを特定
中	フィルタリング対象のサブセット用にパーシャルインデックスを使用	より小さく高速なインデックス
中	PK に UUIDv7 を使用 (PG18+)	インデックスのロケーション性を改善

アンチパターン (重大)

アンチパターン	問題	解決策
FK インデックスなし	遅い JOIN、フルスキャン	すべての FK 列にインデックスを追加
ループ内の N+1	行ごとにクエリ	with: リレーショナルクエリを使用
プーリングなし	リクエストごとのコネクション	@neondatabase/serverless 等を使用
本番環境での push	データ損失のリスク	常に generate + migrate を使用
JSON をテキストとして保存	検証なし、悪いクエリ	jsonb() 列型を使用

リファレンスドキュメント

ファイル	目的
references/SCHEMA.md	列型、制約
references/QUERIES.md	演算子、join、集計
references/RELATIONS.md	一対多、多対多
references/MIGRATIONS.md	drizzle-kit ワークフロー
references/POSTGRES.md	PG18 機能、RLS、パーティショニング
references/PERFORMANCE.md	インデックス、最適化
references/CHEATSHEET.md	クイックリファレンス

リソース

Drizzle ORM

• 公式ドキュメント: https://orm.drizzle.team
• GitHub リポジトリ: https://github.com/drizzle-team/drizzle-orm
• Drizzle Kit (マイグレーション): https://orm.drizzle.team/kit-docs/overview

PostgreSQL

• 公式ドキュメント: https://www.postgresql.org/docs/
• SQL コマンドリファレンス: https://www.postgresql.org/docs/current/sql-commands.html
• パフォーマンスのヒント: https://www.postgresql.org/docs/current/performance-tips.html
• インデックスタイプ: https://www.postgresql.org/docs/current/indexes-types.html
• JSON 関数: https://www.postgresql.org/docs/current/functions-json.html
• 行レベルセキュリティ: https://www.postgresql.org/docs/current/ddl-rowsecurity.html