# バッチ設計書 27-db:migrate:up

## 概要

本ドキュメントは、Rails標準Rakeタスク `db:migrate:up` の設計仕様を定義するものである。

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

`db:migrate:up` は、指定されたバージョンのマイグレーションの `up` メソッド（または `change` メソッドの順方向）のみを実行するRakeタスクである。

**業務上の目的・背景**：通常の `db:migrate` は未実行のすべてのマイグレーションを順次実行するが、特定のマイグレーションのみを選択的に実行したい場合がある。例えば、マイグレーションの開発中に特定バージョンのみをテストする場合や、何らかの理由でスキップされたマイグレーションを個別に適用する場合に使用する。

**バッチの実行タイミング**：マイグレーション開発・テスト時、特定バージョンの再適用時、またはスキップされたマイグレーションの手動適用時に随時実行される。

**主要な処理内容**：
1. VERSION環境変数の検証
2. 指定バージョンのマイグレーションファイル特定
3. up方向でのマイグレーション実行
4. schema_migrationsへの記録
5. スキーマファイルのダンプ

**前後の処理との関連**：`db:migrate:down` と対になるタスク。`db:migrate:redo` の内部でVERSION指定時に使用される。実行後は `db:schema:dump` が呼び出される（設定による）。

**影響範囲**：指定されたマイグレーションに関連するテーブル・カラム・インデックスなど。

## バッチ種別

データベース管理 / 個別マイグレーション実行

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| config/database.yml | データベース設定ファイルが存在すること |
| データベース存在 | 対象データベースが作成済みであること |
| VERSION指定 | VERSION環境変数が必須 |
| マイグレーションファイル | 指定バージョンのマイグレーションファイルが存在すること |
| シングルDB構成 | マルチDB構成の場合は個別タスクを使用 |

### 実行可否判定

- VERSION環境変数が未指定または空の場合はエラー
- マルチデータベース構成の場合は `raise_for_multi_db` により実行が拒否される
- VERSIONの形式が不正な場合はエラー

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| VERSION | Integer | Yes | なし | 実行するマイグレーションのバージョン（タイムスタンプ） |
| VERBOSE | Boolean | No | true | 詳細出力の有効化 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| config/database.yml | YAML | データベース接続設定ファイル |
| db/migrate/[VERSION]_*.rb | Ruby | 指定バージョンのマイグレーションファイル |
| schema_migrations | DB | 実行済みマイグレーション記録 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | マイグレーション実行状況 |
| schema_migrations | DB | 実行済みバージョンの追加 |
| db/schema.rb | Ruby | スキーマダンプファイル（設定による） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | schema.rb または structure.sql |
| 出力先 | db/ |
| 文字コード | UTF-8 |
| 内容 | 更新後のスキーマ定義 |

## 処理フロー

### 処理シーケンス

```
1. load_config
   └─ database.ymlから設定を読み込み
2. raise_for_multi_db
   └─ マルチDB構成チェック
3. VERSION検証
   └─ 必須チェック、形式チェック
4. check_target_version
   └─ バージョン形式の妥当性確認
5. migration_context.run(:up, target_version)
   └─ 指定バージョンのupを実行
6. schema_migrations更新
   └─ バージョンを記録
7. _dump
   └─ スキーマファイルをダンプ
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[load_config実行]
    B --> C[raise_for_multi_db]
    C --> D{マルチDB構成?}
    D -->|Yes| E[エラー: マルチDB非対応]
    E --> F[異常終了]
    D -->|No| G{VERSION指定あり?}
    G -->|No| H[エラー: VERSION is required]
    H --> F
    G -->|Yes| I{VERSION空文字?}
    I -->|Yes| H
    I -->|No| J[check_target_version]
    J --> K{VERSION形式OK?}
    K -->|No| L[エラー: Invalid format]
    L --> F
    K -->|Yes| M[migration_context.run :up]
    M --> N{マイグレーション成功?}
    N -->|No| O[マイグレーションエラー]
    O --> F
    N -->|Yes| P[schema_migrations更新]
    P --> Q[スキーマダンプ]
    Q --> R[バッチ終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| run :up | マイグレーション定義による | CREATE/ALTER等 | スキーマ変更 |
| record_version | schema_migrations | INSERT | バージョン記録の追加 |

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

#### schema_migrations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | version | 指定されたVERSION | 14桁のタイムスタンプ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | RuntimeError | VERSION未指定 | VERSION環境変数を指定 |
| - | RuntimeError | VERSION空文字 | 正しいVERSION値を指定 |
| - | RuntimeError | マルチDB構成での実行 | 個別DBタスクを使用 |
| - | InvalidVersion | VERSION形式が不正 | 正しい形式（数値）でVERSIONを指定 |
| - | MigrationError | マイグレーション実行失敗 | マイグレーションファイルを修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

1. マイグレーション失敗時：
   - エラーメッセージを確認
   - マイグレーションファイルを修正
   - 必要に応じて手動でスキーマを調整後、再実行

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | マイグレーション全体（アダプタ依存） |
| コミットタイミング | マイグレーション完了時 |
| ロールバック条件 | マイグレーション内でのエラー発生時 |

## パフォーマンス要件

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

## 排他制御

同時実行は避けるべき。特に同一バージョンの同時実行は予期しない結果を招く。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | マイグレーション開始時 | "== [timestamp] MigrationName: migrating ====" |
| 操作ログ | 各DDL操作時 | "-- create_table(:table_name)" 等 |
| 完了ログ | マイグレーション完了時 | "== [timestamp] MigrationName: migrated (Xs) ===" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | マイグレーション内容に依存 | 該当なし |
| エラー発生 | 該当なし | 標準エラー出力 |

## 備考

- 既に実行済みのバージョンを指定しても、再度実行される（冪等性なし）
- マルチデータベース構成の場合は `db:migrate:up:[database_name]` を使用
- `db:migrate:down` でロールバック可能
- VERSION形式は14桁のタイムスタンプ（例: 20240315123456）
