マイグレーション管理

Speakeasy のデータベースマイグレーションは Drizzle Kit を使用して管理しています。Cellar（業務DB）と Vault（認証DB）それぞれに独立したマイグレーション管理があります。

---

マイグレーション設定

Cellar DB

packages/cellar/drizzle.config.ts

import { defineConfig } from 'drizzle-kit';

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

Vault DB

packages/vault/drizzle.config.ts

import { defineConfig } from 'drizzle-kit';

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

---

マイグレーションコマンド

Cellar DB（業務データ）

cd packages/cellar

# マイグレーションファイル生成
bun run generate

# 開発環境にマイグレーション適用
bun run migrate:dev

# 本番環境にマイグレーション適用
bun run migrate:deploy

# Drizzle Studio（GUI）で DB を確認
bun run studio       # 本番
bun run studio:dev   # 開発

Vault DB（認証データ）

cd packages/vault

# マイグレーションファイル生成
bun run generate

# 開発環境にマイグレーション適用
bun run migrate:dev

# 本番環境にマイグレーション適用
bun run migrate:deploy

# Drizzle Studio で DB を確認
bun run studio       # 本番
bun run studio:dev   # 開発

---

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

1. スキーマ変更

Drizzle ORM のスキーマファイルを編集します。

packages/cellar/src/schema/contact.ts

export const contact = p.pgTable('contact', {
  // ... 既存カラム
  newColumn: p.text('newColumn') // 新規カラム追加
});

2. マイグレーション生成

cd packages/cellar
bun run generate

drizzle/ ディレクトリにマイグレーション SQL ファイルが生成されます。

3. 開発環境で検証

bun run migrate:dev

4. 本番環境にデプロイ

bun run migrate:deploy

---

注意事項

better-auth テーブルの変更

Vault DB の多くのテーブルは better-auth が管理しています。これらのテーブルを変更する場合:

1. better-auth プラグインの設定変更 が必要な場合がある
2. スキーマの同期 — better-auth が期待するスキーマと Drizzle スキーマを一致させる
3. カスタムカラムの追加 — better-auth の core テーブルにカスタムカラムを追加する場合は、マイグレーションで直接追加

Relations V2

リレーション定義（defineRelations）はマイグレーションの対象外です。リレーション定義は ORM のクエリビルダー（RQBv2）のためのメタデータであり、データベースの外部キー制約とは独立しています。

Hyperdrive との互換性

Cloudflare Hyperdrive は接続プーリングを行うため、以下の制約があります:

• トランザクション: Hyperdrive 経由ではロングランニングトランザクションを避ける
• DDL 実行: マイグレーションは Hyperdrive ではなく直接接続で実行する

環境変数

マイグレーション実行には DATABASE_URL 環境変数が必要です。各パッケージの .dev.vars ファイルまたは環境変数で設定します。