# バッチ設計書 8-migrateFresh

## 概要

本ドキュメントは、Payloadのデータベース再構築処理「migrateFresh」の設計仕様を定義する。このバッチは、全テーブルを削除し全マイグレーションを再実行する責務を担う。

### 本バッチの処理概要

migrateFreshバッチは、データベースを完全に初期化し、全てのマイグレーションを最初から適用し直す破壊的な操作である。Drizzleアダプター固有の実装として提供される。

**業務上の目的・背景**：開発環境のリセット、テスト環境の初期化、または深刻なデータ破損からの復旧など、データベースを完全にクリーンな状態から再構築する必要がある場合に使用される。本番環境での使用は通常推奨されない。

**バッチの実行タイミング**：CLIコマンド（`payload migrate:fresh`）による手動実行。実行前に確認プロンプトが表示される。

**主要な処理内容**：
1. 警告メッセージの表示と確認プロンプト（forceAcceptWarning=false時）
2. データベースの完全削除（dropDatabase）
3. 拡張機能の再作成（PostgreSQL等の場合）
4. 全マイグレーションファイルの読み込み
5. 全マイグレーションの順次実行（up関数）
6. 各マイグレーションをbatch=1として記録

**前後の処理との関連**：migrateResetとは異なり、データベース自体を削除して再作成する。migrateはこの後に実行する必要がない（既に全マイグレーションが適用される）。

**影響範囲**：データベース全体（全テーブル・データが削除される）。

## バッチ種別

データマイグレーション処理（データベース再構築）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 手動（必要時のみ） |
| 実行時刻 | 手動実行時 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | CLIコマンド |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Drizzleアダプター使用 | DrizzleAdapter（Postgres/SQLite）を使用していること |
| DB接続 | データベースに接続可能であること |
| 確認応答 | ユーザーが確認プロンプトに同意すること（または forceAcceptWarning=true） |

### 実行可否判定

確認プロンプトへの同意、または forceAcceptWarning=true が必要。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| forceAcceptWarning | boolean | No | false | trueの場合、確認プロンプトをスキップ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| migrations/ | ファイル | マイグレーションファイル（TypeScript/JavaScript） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| payload-migrations | DB | 全マイグレーション記録（batch=1） |
| データベーススキーマ | DB | 再構築されたスキーマ |

### 出力ファイル仕様

ファイル出力なし（データベース更新のみ）

## 処理フロー

### 処理シーケンス

```
1. 確認プロンプト表示（forceAcceptWarning=false時）
   └─ ユーザーが同意しない場合はprocess.exit(0)
2. データベース削除
   └─ dropDatabase()でデータベースを完全削除
3. 拡張機能の再作成（PostgreSQL等）
   └─ createExtensions()が存在する場合
4. マイグレーションファイルの読み込み
   └─ readMigrationFiles()
5. 各マイグレーションの実行
   └─ トランザクション開始 → up関数実行 → 記録作成 → コミット
6. エラー発生時はロールバックとプロセス終了
   └─ killTransaction(), process.exit(1)
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{forceAcceptWarning?}
    B -->|No| C[確認プロンプト表示]
    C --> D{ユーザー同意?}
    D -->|No| E[process.exit 0]
    D -->|Yes| F[データベース削除]
    B -->|Yes| F
    F --> G{createExtensions存在?}
    G -->|Yes| H[拡張機能再作成]
    G -->|No| I[マイグレーションファイル読み込み]
    H --> I
    I --> J[次のマイグレーション取得]
    J --> K[トランザクション開始]
    K --> L[up関数実行]
    L --> M{成功?}
    M -->|Yes| N[マイグレーション記録作成 batch=1]
    N --> O[トランザクションコミット]
    O --> P{次のマイグレーションあり?}
    M -->|No| Q[トランザクションロールバック]
    Q --> R[process.exit 1]
    P -->|Yes| J
    P -->|No| S[処理完了]
```

## データベース操作仕様

### 操作別データベース影響一覧

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| DB削除 | 全テーブル | DROP | データベース全体の削除 |
| 拡張作成 | - | CREATE EXTENSION | PostgreSQL拡張の再作成 |
| マイグレーション実行 | 各種テーブル | DDL/DML | up関数による変更 |
| 記録作成 | payload-migrations | INSERT | 全マイグレーション記録（batch=1） |

### テーブル別操作詳細

#### payload-migrations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | マイグレーションファイル名 | |
| INSERT | batch | 1 | 全マイグレーションがbatch=1 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | DB削除エラー | データベース削除に失敗 | 権限確認、手動削除 |
| - | マイグレーションエラー | up関数内でエラー発生 | ログ確認、修正後再実行 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（手動で再実行） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

1. エラーログを確認
2. データベース接続・権限を確認
3. 必要に応じてデータベースを手動で削除
4. 再実行

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | マイグレーション単位 |
| コミットタイミング | 各マイグレーション完了後 |
| ロールバック条件 | up関数内でエラー発生時 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 全マイグレーションファイル数 |
| 目標処理時間 | マイグレーション内容とデータ量に依存 |
| メモリ使用量上限 | 制限なし |

## 排他制御

- データベース削除中は他の接続を切断
- 再構築中は他のプロセスからのアクセスを禁止

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 情報ログ | DB削除時 | `Dropping database.` |
| デバッグログ | ファイル検出時 | `Found ${count} migration files.` |
| 開始ログ | マイグレーション開始時 | `Migrating: ${name}` |
| 完了ログ | マイグレーション完了時 | `Migrated: ${name} (${time}ms)` |
| エラーログ | エラー発生時 | `Error running migration ${name}. Rolling back` |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 実行失敗 | 1件以上 | 開発チーム |

## 備考

- **破壊的操作**：本番環境での使用は推奨されない
- **Drizzleアダプター固有**：packages/drizzle/src/migrateFresh.ts に実装
- **確認プロンプト**：`WARNING: This will drop your database and run all migrations. Are you sure you want to proceed?`
- forceAcceptWarning=trueで確認をスキップ可能（CI/CD環境等）
- 全マイグレーションがbatch=1として記録される
- PostgreSQL等では拡張機能（uuid-ossp等）が再作成される
- promptsライブラリを使用した対話的確認
