drizzle-postgres

PostgreSQL + Drizzle ORM

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

基本コマンド

npx drizzle-kit generate   # Generate migration from schema changes
npx drizzle-kit migrate    # Apply pending migrations
npx drizzle-kit push       # Push schema directly (dev only!)
npx drizzle-kit studio     # Open database browser

クイック判断ツリー

「このリレーションはどのようにモデル化すればよいですか？」

Relationship type?
├─ One-to-many (user has posts)     → FK on "many" side + relations()
├─ Many-to-many (posts have tags)   → Junction table + relations()
├─ One-to-one (user has profile)    → FK with unique constraint
└─ Self-referential (comments)      → FK to same table

「クエリが遅いのはなぜですか？」

Slow query?
├─ Missing index on WHERE/JOIN columns  → Add index
├─ N+1 queries in loop                  → Use relational queries API
├─ Full table scan                      → EXPLAIN ANALYZE, add index
├─ Large result set                     → Add pagination (limit/offset)
└─ Connection overhead                  → Enable connection pooling

「どの drizzle-kit コマンドを使えばよいですか？」

What do I need?
├─ Schema changed, need SQL migration   → drizzle-kit generate
├─ Apply migrations to database         → drizzle-kit migrate
├─ Quick dev iteration (no migration)   → drizzle-kit push
└─ Browse/edit data visually            → drizzle-kit studio

ディレクトリ構成

src/db/
├── schema/
│   ├── index.ts          # Re-export all tables
│   ├── users.ts          # Table + relations
│   └── posts.ts          # Table + relations
├── db.ts                 # Connection with pooling
└── migrate.ts            # Migration runner
drizzle/
└── migrations/           # Generated SQL files
drizzle.config.ts         # drizzle-kit config

スキーマパターン

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

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), // ALWAYS index FKs
  ],
);

リレーション

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 を回避）

// ✓ Single query with nested data
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 });
});

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

優先度	チェック項目	影響
CRITICAL	すべての外部キーにインデックスを設定する	JOIN 時のフルテーブルスキャンを防止します
CRITICAL	ネストされたデータにはリレーショナルクエリを使う	N+1 を回避します
HIGH	本番環境でコネクションプーリングを使う	コネクションのオーバーヘッドを削減します
HIGH	遅いクエリに EXPLAIN ANALYZE を使う	不足しているインデックスを特定します
MEDIUM	フィルタリングされたサブセットに部分インデックスを使う	より小さく、高速なインデックスになります
MEDIUM	PK に UUIDv7 を使う（PG18+）	インデックスの局所性が向上します

アンチパターン（CRITICAL）

アンチパターン	問題	対処
外部キーのインデックスがない	JOIN が遅く、フルスキャンが発生します	すべての外部キー列にインデックスを追加します
ループ内の N+1	行ごとにクエリが実行されます	with: リレーショナルクエリを使います
プーリングがない	リクエストごとにコネクションを作成します	@neondatabase/serverless などを使います
本番環境での push	データ損失のリスクがあります	必ず generate + migrate を使います
JSON をテキストとして保存	検証できず、クエリの質も低下します	jsonb() 列型を使います

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

ファイル	用途
references/SCHEMA.md	列の型、制約
references/QUERIES.md	演算子、結合、集約
references/RELATIONS.md	1対多、多対多
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