データベース運用

Speakeasy は 2 つの PostgreSQL データベース（Cellar, Vault）を Cloudflare Hyperdrive 経由で利用しています。

データベース構成

ORM: Drizzle ORM v1.0 beta

項目	内容
バージョン	v1.0 beta
パッケージ	`@speakeasy/cellar`, `@speakeasy/vault`
Relations	Relations V2 (`defineRelations`)
クエリ	RQBv2（Relational Query Builder v2）

マイグレーション管理

マイグレーションワークフロー

コマンド

cd packages/cellar

# 1. スキーマファイルを編集後、マイグレーションを生成
bun run generate

# 2. dev 環境に適用
bun run migrate:dev

# 3. 本番環境に適用
bun run migrate:deploy

マイグレーションファイル

マイグレーションファイルは packages/cellar/drizzle/ に生成されます。Drizzle Kit が差分を検出し、SQL ファイルを自動生成します。

Drizzle Studio

ブラウザベースの DB 管理ツールで、データの閲覧・編集が可能です。

cd packages/cellar

# dev 環境に接続
bun run studio:dev

# 本番環境に接続（注意して操作）
bun run studio

パフォーマンス最適化

Hyperdrive によるコネクション管理

Hyperdrive が自動的にコネクションプーリングとクエリキャッシュを行います:

機能	説明
コネクションプーリング	Workers ↔ DB 間の接続を再利用
クエリキャッシュ	同一クエリの結果をキャッシュ（有効時）
Smart Placement	DB に近いリージョンで Worker を実行

スロークエリの特定

Penthouse の SQL Explorer（/admin/sql）で:

「スロークエリ」タブを確認
「時間帯別統計」で負荷の集中を特定
「エンドポイント別」で問題のある API を特定

インデックス確認

Drizzle スキーマでインデックスが定義されています。新しいクエリパターンを追加する場合は、対応するインデックスの追加を検討してください。

// スキーマ定義でのインデックス例
export const chatMessage = pgTable(
  'chat_message',
  {
    // ...
  },
  (table) => [
    index('idx_chat_message_room_id').on(table.roomId),
    index('idx_chat_message_sent_at').on(table.sentAt)
  ]
);

N+1 問題の回避

RQBv2 の with 句を活用して関連データを一括取得:

// OK — JOIN で一括取得
const rooms = await db.query.chatRoom.findMany({
  with: {
    messages: { limit: 1, orderBy: desc(chatMessage.sentAt) },
    contact: true
  }
});

// NG — ループ内で個別クエリ（N+1）
for (const room of rooms) {
  const messages = await db.query.chatMessage.findMany({
    where: eq(chatMessage.roomId, room.id)
  });
}

Analytics Engine

DB オペレーションの計測に Analytics Engine を使用:

// クエリ実行時に自動計測
env.ANALYTICS.writeDataPoint({
  blobs: [serviceName, operationType, modelName],
  doubles: [durationMs]
});

データは Penthouse の管理ダッシュボード（/admin/database）で可視化されます。

バックアップ

Prisma Postgres

Prisma Postgres を使用している場合、自動バックアップが提供されます。復元が必要な場合は Prisma Console から操作します。

手動エクスポート

緊急時のデータエクスポート:

# Drizzle Studio 経由でデータを CSV エクスポート
bun run studio:dev
# ブラウザから対象テーブルのデータをエクスポート

日常運用チェックリスト

毎日

Cloudflare Dashboard でエラー率を確認
DLQ（Dead Letter Queue）にメッセージがないか確認

毎週

Penthouse の管理ダッシュボードでコスト推移を確認
スロークエリの有無を確認
Workers の CPU 使用量推移を確認

毎月

Cloudflare の利用量がプラン制限に近づいていないか確認
DB のストレージ使用量を確認
R2 バケットのストレージ使用量を確認