# バッチ設計書 6-migrate

## 概要

本ドキュメントは、Payloadのデータベースマイグレーション処理「migrate」の設計仕様を定義する。このバッチは、未実行のマイグレーションファイルを検出し順次適用する責務を担う。

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

migrateバッチは、データベースのスキーマ変更やデータ変換を管理するマイグレーション処理である。マイグレーションファイルをファイルシステムから読み込み、未実行のものを順次適用する。

**業務上の目的・背景**：アプリケーションの進化に伴い、データベーススキーマやデータ構造の変更が必要になる。マイグレーションシステムは、これらの変更を追跡可能、再現可能、ロールバック可能な形で管理することで、開発・ステージング・本番環境間でのデータベース整合性を保証する。

**バッチの実行タイミング**：通常はデプロイ時、またはCLIコマンド（`payload migrate`）による手動実行。Payload起動時に自動実行されることもある（設定による）。

**主要な処理内容**：
1. マイグレーションファイルの読み込み（readMigrationFiles）
2. payload-migrationsコレクションから既存のマイグレーション記録を取得
3. 未実行のマイグレーションを特定
4. 各マイグレーションに対してup関数を実行
5. 成功したマイグレーションをpayload-migrationsに記録
6. エラー発生時はトランザクションロールバック

**前後の処理との関連**：migrateDownによるロールバック、migrateResetによる全リセット、migrateFreshによる再構築と連携。

**影響範囲**：データベーススキーマ全体、payload-migrationsコレクション。

## バッチ種別

データマイグレーション処理（スキーマ・データ変更）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | デプロイ時/手動 |
| 実行時刻 | デプロイ時または手動実行時 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | CLIコマンド/デプロイプロセス |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| マイグレーションファイル存在 | migrationsディレクトリにマイグレーションファイルが存在すること |
| DB接続 | データベースに接続可能であること |
| payload-migrations | payload-migrationsコレクションが利用可能であること |

### 実行可否判定

未実行のマイグレーションが存在する場合に実行。既に全てのマイグレーションが適用済みの場合は何も実行しない。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| migrations | MigrationFile[] | No | - | 適用するマイグレーションファイル配列（省略時はファイルシステムから読み込み） |

### 入力データソース

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

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| payload-migrations | DB | 新規マイグレーション記録 |
| データベーススキーマ | DB | 変更されたスキーマ |

### 出力ファイル仕様

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

## 処理フロー

### 処理シーケンス

```
1. マイグレーションファイルの読み込み
   └─ readMigrationFiles()でファイルシステムから取得
2. 既存マイグレーション記録の取得
   └─ getMigrations()でpayload-migrationsから取得
3. 新規バッチ番号の算出
   └─ latestBatch + 1
4. 各マイグレーションファイルのループ
   └─ 既存記録と照合し、未実行のもののみ処理
5. トランザクション開始
   └─ initTransaction()
6. up関数の実行
   └─ migration.up({ payload, req, session })
7. マイグレーション記録の作成
   └─ payload.create({ collection: 'payload-migrations', ... })
8. トランザクションコミット
   └─ commitTransaction()
9. エラー発生時はロールバック
   └─ killTransaction()
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[マイグレーションファイル読み込み]
    B --> C[既存マイグレーション記録取得]
    C --> D[新規バッチ番号算出]
    D --> E{未実行マイグレーション存在?}
    E -->|No| F[処理完了]
    E -->|Yes| G[次の未実行マイグレーション取得]
    G --> H[トランザクション開始]
    H --> I[up関数実行]
    I --> J{成功?}
    J -->|Yes| K[マイグレーション記録作成]
    K --> L[トランザクションコミット]
    L --> M{次のマイグレーションあり?}
    J -->|No| N[トランザクションロールバック]
    N --> O[エラースロー]
    M -->|Yes| G
    M -->|No| F
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 既存記録取得 | payload-migrations | SELECT | マイグレーション履歴の取得 |
| マイグレーション実行 | 各種テーブル | DDL/DML | up関数による変更 |
| 記録作成 | payload-migrations | INSERT | 新規マイグレーション記録 |

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

#### payload-migrations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, batch | 全件取得 | getMigrations() |
| INSERT | name | マイグレーションファイル名 | |
| INSERT | batch | newBatch（latestBatch + 1） | |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | マイグレーションエラー | up関数内でエラー発生 | ロールバック、エラーログ確認、修正後再実行 |
| - | DB接続エラー | データベース接続失敗 | 接続設定確認 |

### リトライ仕様

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

### 障害時対応

1. エラーログを確認（`Error running migration ${migration.name}`）
2. 該当マイグレーションの修正
3. 必要に応じてmigrateDownで前のマイグレーションまでロールバック
4. 修正後、migrate再実行

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

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

## パフォーマンス要件

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

## 排他制御

- トランザクションによる整合性保証
- payload-migrationsへの記録により二重実行を防止

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | マイグレーション開始時 | `Migrating: ${migration.name}` |
| 完了ログ | マイグレーション完了時 | `Migrated: ${migration.name} (${time}ms)` |
| エラーログ | エラー発生時 | `Error running migration ${migration.name}` |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| マイグレーション失敗 | 1件以上 | 開発チーム |
| 処理時間 | 設定による | 運用チーム |

## 備考

- マイグレーションファイルはTypeScriptまたはJavaScriptで記述
- 各ファイルには`up`関数と`down`関数をエクスポート
- バッチ番号により、同時に適用されたマイグレーションをグループ化
- 処理時間はログに記録される（ミリ秒単位）
- sessionパラメータによりトランザクション内で実行
