# バッチ設計書 10-db:rollback

## 概要

本ドキュメントはMedusa CLIのdb:rollbackコマンドについて、その設計内容を記述したバッチ設計書です。本コマンドは指定されたモジュールのデータベースマイグレーションをロールバック（巻き戻し）します。

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

db:rollbackは、指定されたモジュールのデータベースマイグレーションを1つ前の状態に戻すCLIコマンドです。誤ったマイグレーションの適用や、問題が発生した場合のリカバリに使用されます。

**業務上の目的・背景**：データベースマイグレーションの適用後に問題が発見された場合や、開発中にスキーマ変更を取り消したい場合があります。db:rollbackコマンドは、安全にマイグレーションを巻き戻すための手段を提供します。各モジュールのMikroORMマイグレーションは、upメソッドとdownメソッドを持ち、ロールバックではdownメソッドが実行されます。これにより、変更前の状態に戻すことができます。

**バッチの実行タイミング**：問題発生時や開発中の変更取り消し時に、手動でCLI経由で実行します。

**主要な処理内容**：
1. データベースの存在確認
2. プラグイン設定のマージ
3. リンク定義のロード
4. マイグレーションテーブルの確保
5. 指定モジュールのマイグレーションロールバック

**前後の処理との関連**：db:migrateで適用されたマイグレーションを取り消します。複数回実行すると、その回数分だけマイグレーションが巻き戻されます。

**影響範囲**：指定されたモジュールのデータベーステーブルが変更されます。リンクテーブルの同期は行われないため、必要に応じて手動で対応が必要です。

## バッチ種別

CLIコマンド / データベースロールバック

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（問題発生時・開発時） |
| 実行時刻 | 手動実行 |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | `npx medusa db:rollback -m <module>`コマンド |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| データベース接続設定 | 有効なデータベース接続設定が存在すること |
| マイグレーション履歴 | ロールバック対象のマイグレーションが実行済みであること |
| Node.js環境 | Node.jsランタイムが利用可能であること |

### 実行可否判定

- 指定されたモジュールが存在しない場合はエラー
- 巻き戻すマイグレーションがない場合は処理なし

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| directory | string | Yes | カレントディレクトリ | プロジェクトのルートディレクトリ |
| modules | string[] | No | - | ロールバック対象のモジュール名リスト |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| mikro_orm_migrations | DB | マイグレーション履歴 |
| モジュールマイグレーション | TypeScript/JavaScript | 各モジュールのマイグレーションファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| データベーステーブル | DB | ロールバック適用後のスキーマ |
| mikro_orm_migrations | DB | ロールバックされたマイグレーション削除 |

### 出力ファイル仕様

ファイル出力なし

## 処理フロー

### 処理シーケンス

```
1. 環境設定
   └─ MEDUSA_WORKER_MODE = "server"
2. コンテナ初期化
   └─ initializeContainer(directory)
3. データベース確認
   └─ ensureDbExists(container)
4. プラグインロード
   └─ getResolvedPlugins → mergePluginModules
5. リンク定義ロード
   └─ LinkLoader(linksSourcePaths).load()
6. マイグレーションテーブル確保
   └─ migrator.ensureMigrationsTable()
7. マイグレーションロールバック実行
   └─ medusaAppLoader.runModulesMigrations({
        moduleNames: modules,
        action: "revert"
      })
```

### フローチャート

```mermaid
flowchart TD
    A[コマンド開始] --> B[コンテナ初期化]
    B --> C[ensureDbExists]
    C --> D[プラグインロード]
    D --> E[リンク定義ロード]
    E --> F[マイグレーションテーブル確保]
    F --> G[runModulesMigrations revert]
    G --> H{成功?}
    H -->|Yes| I[Migrations reverted]
    H -->|No| J{エラータイプ?}
    J -->|UNKNOWN_MODULES| K[モジュール一覧表示]
    J -->|その他| L[エラー表示]
    K --> M[process.exit 1]
    L --> M
    I --> N[process.exit 0]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| DB確認 | データベース自体 | 確認 | 存在確認 |
| マイグレーションテーブル確保 | mikro_orm_migrations | CREATE TABLE | 履歴テーブル確保 |
| ロールバック実行 | 各モジュールテーブル | ALTER/DROP | スキーマ巻き戻し |
| マイグレーション削除 | mikro_orm_migrations | DELETE | 実行記録削除 |

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

#### mikro_orm_migrations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | name | ロールバック対象のマイグレーション名 | ロールバック完了時 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UNKNOWN_MODULES | MedusaError | 指定モジュールが存在しない | 利用可能なモジュール一覧を表示 |
| - | データベースエラー | ロールバック失敗 | エラー内容を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

- UNKNOWN_MODULESエラー時は利用可能なモジュール一覧を表示
- その他のエラーはlogger.errorでエラー出力
- process.exit(1)で異常終了

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | モジュール単位 |
| コミットタイミング | 各モジュールロールバック完了時 |
| ロールバック条件 | ロールバック処理自体の失敗時 |

## パフォーマンス要件

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

## 排他制御

- ロールバック実行中は他のマイグレーション/ロールバック実行を避ける（手動管理）

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 情報ログ | 処理開始時 | `Reverting migrations...` |
| 区切り線 | 処理完了時 | ターミナル幅のダッシュ |
| 情報ログ | ロールバック完了時 | `Migrations reverted` |
| エラーログ | UNKNOWN_MODULES時 | エラーメッセージ + 利用可能モジュール一覧 |
| エラーログ | その他エラー時 | エラー内容 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 非0 | 呼び出し元 |

## 備考

- MedusaAppLoaderのrunModulesMigrationsをaction: "revert"で呼び出し
- moduleNamesパラメータで対象モジュールを指定
- UNKNOWN_MODULES時のallModulesプロパティで利用可能モジュールを取得可能
- リンクテーブルの同期は行われないため、必要に応じてdb:sync-linksを実行
- 終了後にprocess.exit()を明示的に呼び出し（非同期処理の完了を待つため）
- 実装箇所: `packages/medusa/src/commands/db/rollback.ts`
- 注意: ロールバックはデータの損失を伴う可能性があるため、慎重に実行すること
