# 機能設計書 7-マイグレーション

## 概要

本ドキュメントは、Laravel Frameworkのマイグレーション機能について、その設計思想、処理フロー、および実装詳細を記述したものである。データベーススキーマのバージョン管理機能の設計を定義する。

### 本機能の処理概要

マイグレーション機能は、データベーススキーマの変更をPHPコードで管理し、チームでの共有やバージョン管理を可能にする機能である。up/downメソッドで変更と復元を定義し、順序付けされたマイグレーションを実行・ロールバックできる。

**業務上の目的・背景**：データベーススキーマの変更をSQLファイルで管理すると、適用順序や環境間の同期が困難になる。マイグレーションはスキーマ変更をコードとして管理し、Gitでのバージョン管理、自動デプロイ、環境間同期を容易にする。

**機能の利用シーン**：
- 新規テーブル作成
- カラムの追加・変更・削除
- インデックスの作成・削除
- 外部キー制約の追加・削除
- 本番環境へのスキーマ変更デプロイ
- スキーマ変更のロールバック

**主要な処理内容**：
1. マイグレーションファイルの読み込みと解決
2. 実行済みマイグレーションの管理（migrationsテーブル）
3. up()メソッドでの変更適用
4. down()メソッドでのロールバック
5. バッチ番号による一括ロールバック
6. pretend（ドライラン）機能

**関連システム・外部連携**：
- Schema Builder（DDL実行）
- Connection（クエリ実行）
- Filesystem（マイグレーションファイル読み込み）
- Event Dispatcher（マイグレーションイベント）

**権限による制御**：マイグレーションは通常、開発者・運用者のみが実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLI機能のため直接関連画面なし |

## 機能種別

データベース管理 / スキーマ管理 / バージョン管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| paths | array/string | No | マイグレーションファイルパス | - |
| step | int | No | ロールバックするステップ数 | - |
| pretend | bool | No | ドライランモード | - |

### 入力データソース

- database/migrationsディレクトリ
- migrationsテーブル（実行済み記録）
- Artisan CLI（migrate, migrate:rollback等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| migrations | array | 実行されたマイグレーション一覧 |

### 出力先

- データベーススキーマ（DDL実行）
- migrationsテーブル（実行記録）
- Console出力（実行状況）

## 処理フロー

### 処理シーケンス

```
1. マイグレーション読み込み
   └─ getMigrationFiles()でファイル一覧取得
2. 実行済み確認
   └─ repository->getRan()で実行済み一覧取得
3. 未実行抽出
   └─ pendingMigrations()で未実行を抽出
4. 順次実行
   └─ runUp()/runDown()で各マイグレーション実行
5. 実行記録
   └─ repository->log()でmigrationsテーブルに記録
6. イベント発火
   └─ MigrationsStarted/MigrationsEndedイベント
```

### フローチャート

```mermaid
flowchart TD
    A[migrate実行] --> B[getMigrationFiles()]
    B --> C[repository->getRan()]
    C --> D[pendingMigrations()]
    D --> E{未実行あり?}
    E -->|No| F[NoPendingMigrationsイベント]
    E -->|Yes| G[getNextBatchNumber()]
    G --> H[MigrationsStartedイベント]
    H --> I[foreach migrations]
    I --> J[runUp()]
    J --> K[resolvePath()]
    K --> L{pretend?}
    L -->|Yes| M[pretendToRun()]
    L -->|No| N[runMigration()]
    N --> O[migration->up()]
    O --> P[repository->log()]
    P --> Q{次あり?}
    Q -->|Yes| I
    Q -->|No| R[MigrationsEndedイベント]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 実行順序 | ファイル名のタイムスタンプ順に実行 | migrate実行時 |
| BR-02 | バッチ管理 | 同一migrate実行は同じバッチ番号 | migrate実行時 |
| BR-03 | ロールバック順序 | 新しいマイグレーションから逆順に実行 | rollback実行時 |
| BR-04 | スキップ判定 | shouldRun()がfalseの場合はスキップ | 各マイグレーション実行時 |

### 計算ロジック

- マイグレーション名: ファイル名から拡張子とパスを除去
- バッチ番号: 現在の最大バッチ番号 + 1

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| log() | migrations | INSERT | 実行記録の追加 |
| delete() | migrations | DELETE | ロールバック時の記録削除 |
| getRan() | migrations | SELECT | 実行済み一覧取得 |
| getMigrations() | migrations | SELECT | バッチ指定でマイグレーション取得 |

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

#### migrationsテーブル

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | migration, batch | マイグレーション名, バッチ番号 | migrate時 |
| DELETE | migration | 対象マイグレーション名 | rollback時 |
| SELECT | migration | - | 実行済み確認 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Exception | マイグレーション実行エラー | up/downメソッドを確認 |
| - | ClassNotFoundException | マイグレーションクラスが見つからない | ファイル名とクラス名を確認 |

### リトライ仕様

マイグレーションにリトライ機能はない。失敗時は手動で対処。

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

各マイグレーションはwithinTransaction設定でトランザクション内実行が可能（デフォルト: true、PostgreSQL以外）。

## パフォーマンス要件

- マイグレーションは通常、デプロイ時のみ実行
- 大量のスキーマ変更は分割を推奨

## セキュリティ考慮事項

- 本番環境でのマイグレーションは権限を制限
- migrate:freshは本番環境では使用禁止を推奨
- マイグレーションファイルにパスワードなど機密情報を含めない

## 備考

- `migrate:fresh`で全テーブル削除後に再マイグレーション
- `migrate:refresh`でロールバック後に再マイグレーション
- `migrate:status`で実行状況確認
- `--isolated`オプションでロック機能を使用可能

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Migration.php | `src/Illuminate/Database/Migrations/Migration.php` | マイグレーション基底クラス |
| 1-2 | MigrationRepositoryInterface.php | `src/Illuminate/Database/Migrations/MigrationRepositoryInterface.php` | リポジトリインターフェース |

**読解のコツ**: Migrationクラスはシンプルで、up()とdown()メソッドを持つだけ。$connectionでDB指定、$withinTransactionでトランザクション制御。

#### Step 2: Migratorを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Migrator.php | `src/Illuminate/Database/Migrations/Migrator.php` | マイグレーション実行エンジン |

**主要処理フロー**:
- **105-115行目**: コンストラクタ（repository, resolver, files, dispatcher）
- **124-141行目**: run()メソッド - マイグレーション実行のエントリポイント
- **150-160行目**: pendingMigrations()で未実行マイグレーション抽出
- **181-221行目**: runPending()で未実行マイグレーションを順次実行
- **231-259行目**: runUp()で個別マイグレーションを実行
- **269-287行目**: rollback()でロールバック実行

#### Step 3: DatabaseMigrationRepositoryを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | DatabaseMigrationRepository.php | `src/Illuminate/Database/Migrations/DatabaseMigrationRepository.php` | migrationsテーブル操作 |

**読解ポイント**:
- getRan(): 実行済みマイグレーション一覧
- log(): 実行記録の追加
- delete(): ロールバック時の記録削除
- getNextBatchNumber(): 次のバッチ番号

#### Step 4: Schema Builderを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Builder.php | `src/Illuminate/Database/Schema/Builder.php` | スキーマビルダ |
| 4-2 | Blueprint.php | `src/Illuminate/Database/Schema/Blueprint.php` | テーブル定義 |

### プログラム呼び出し階層図

```
php artisan migrate
    │
    └─ MigrateCommand::handle()
           │
           └─ Migrator::run($paths, $options)
                  │
                  ├─ getMigrationFiles($paths)
                  │      └─ glob($path.'/*_*.php')
                  │
                  ├─ requireFiles($migrations)
                  │      └─ files->requireOnce($file)
                  │
                  └─ runPending($migrations, $options)
                         │
                         ├─ fireMigrationEvent(MigrationsStarted)
                         │
                         └─ foreach($migrations as $file)
                                │
                                └─ runUp($file, $batch, $pretend)
                                       │
                                       ├─ resolvePath($file)
                                       │      └─ new MigrationClass
                                       │
                                       ├─ runMigration($migration, 'up')
                                       │      └─ $migration->up()
                                       │
                                       └─ repository->log($name, $batch)
```

### データフロー図

```
[入力]                    [処理]                         [出力]

database/migrations/ ───▶ Migrator ─────────────────────▶ スキーマ変更
                              │
                              ▼
                        Migration Files
                              │
                              ▼
                        Repository (migrations table)
                              │
                              ├── getRan() ◀───────────── SELECT
                              ├── log() ──────────────── INSERT
                              └── delete() ────────────── DELETE
                              │
                              ▼
                        Schema Builder ─────────────────▶ DDL実行
                              │
                              ▼
                        Events ──────────────────────────▶ Event Dispatcher
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Migrator.php | `src/Illuminate/Database/Migrations/Migrator.php` | ソース | マイグレーション実行エンジン |
| Migration.php | `src/Illuminate/Database/Migrations/Migration.php` | ソース | マイグレーション基底クラス |
| DatabaseMigrationRepository.php | `src/Illuminate/Database/Migrations/DatabaseMigrationRepository.php` | ソース | 実行記録リポジトリ |
| MigrationCreator.php | `src/Illuminate/Database/Migrations/MigrationCreator.php` | ソース | マイグレーションファイル生成 |
| Builder.php | `src/Illuminate/Database/Schema/Builder.php` | ソース | スキーマビルダ |
| Blueprint.php | `src/Illuminate/Database/Schema/Blueprint.php` | ソース | テーブル定義 |
| MigrateCommand.php | `src/Illuminate/Database/Console/Migrations/MigrateCommand.php` | ソース | migrateコマンド |
| RollbackCommand.php | `src/Illuminate/Database/Console/Migrations/RollbackCommand.php` | ソース | rollbackコマンド |
| MigrationStarted.php | `src/Illuminate/Database/Events/MigrationStarted.php` | ソース | マイグレーション開始イベント |
| MigrationEnded.php | `src/Illuminate/Database/Events/MigrationEnded.php` | ソース | マイグレーション終了イベント |
