# バッチ設計書 29-runmigrations

## 概要

本ドキュメントは、メンテナンスモードでデータベースマイグレーションを実行するDjango管理コマンド「runmigrations」の設計仕様を定義する。

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

このコマンドは、InvenTreeシステムの保留中のデータベースマイグレーションをメンテナンスモードで安全に実行し、データベーススキーマを最新の状態に更新する。

**業務上の目的・背景**：InvenTreeのバージョンアップやプラグインの更新に伴い、データベーススキーマの変更（マイグレーション）が必要になることがある。マイグレーション実行中にユーザーがシステムにアクセスすると、データ不整合やエラーが発生する可能性がある。本コマンドは、マイグレーションを安全に実行するための標準的な手順を提供する。

**バッチの実行タイミング**：手動実行（CLI）。システムアップデート時や保留中のマイグレーションがある場合に実行される。

**主要な処理内容**：
1. 保留中のマイグレーションを確認
2. 必要に応じてメンテナンスモードを有効化
3. Django標準のmigrateコマンドを実行
4. マイグレーション完了後、メンテナンスモードを解除

**前後の処理との関連**：システムアップデートプロセスの一部として実行される。check_for_migrations（スケジュールタスク）から呼び出されることもある。

**影響範囲**：データベーススキーマの変更、アプリケーション全体の一時停止に影響する。

## バッチ種別

データベース管理 / スキーマ更新 / CLIコマンド

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動） |
| 実行時刻 | メンテナンス時間帯 |
| 実行曜日 | 不定 |
| 実行日 | 不定 |
| トリガー | CLIコマンド: `python manage.py runmigrations` |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| データベース接続 | InvenTreeデータベースに正常に接続できること |
| 保留中マイグレーション | 適用すべきマイグレーションファイルが存在すること |
| 管理者権限 | データベーススキーマ変更権限があること |

### 実行可否判定

特別な実行可否判定はなく、コマンド実行時に即座に処理を開始する。保留中のマイグレーションがない場合も正常終了する。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 本コマンドは入力パラメータを受け取らない |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| django_migrations | DB | 適用済みマイグレーション履歴 |
| マイグレーションファイル | Python | 各アプリのmigrationsディレクトリ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| データベーススキーマ | DB | スキーマ変更 |
| django_migrations | DB | 適用済みマイグレーション記録 |
| ログ | Log | マイグレーション実行ログ |

### 出力ファイル仕様

本コマンドはファイル出力を行わない。

## 処理フロー

### 処理シーケンス

```
1. マイグレーション確認開始
   └─ logger.info('Checking for pending database migrations')
2. check_for_migrations関数を呼び出し
   └─ check_for_migrations(force=True, reload_registry=False)
3. check_for_migrations内部処理
   └─ 保留中マイグレーションを取得
   └─ メンテナンスモードを有効化
   └─ call_command('migrate', interactive=False) を実行
   └─ メンテナンスモードを無効化
4. 完了ログ出力
   └─ logger.info('Database migrations complete')
```

### フローチャート

```mermaid
flowchart TD
    A[コマンド開始] --> B[Checking for pending database migrations ログ出力]
    B --> C[check_for_migrations呼び出し]
    C --> D{保留中マイグレーションあり?}
    D -->|なし| E[マイグレーション不要]
    D -->|あり| F[メンテナンスモード有効化]
    F --> G[migrate コマンド実行]
    G --> H{成功?}
    H -->|Yes| I[メンテナンスモード無効化]
    H -->|No| J[エラーログ出力]
    J --> I
    I --> K[Database migrations complete ログ出力]
    E --> K
    K --> L[コマンド終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| マイグレーション履歴確認 | django_migrations | SELECT | 適用済みマイグレーション確認 |
| スキーマ変更 | 各テーブル | ALTER/CREATE/DROP | マイグレーション内容に依存 |
| マイグレーション記録 | django_migrations | INSERT | 適用済みマイグレーション記録 |

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

#### django_migrations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | app, name | 全件 | 適用済み確認 |
| INSERT | app, name, applied | マイグレーション情報 | 適用後に記録 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | NotSupportedError | SQLite制限による操作不可 | SQLiteの場合はログ出力して継続 |
| - | Exception | その他のマイグレーションエラー | エラーログ出力、メンテナンスモード解除 |

### リトライ仕様

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

### 障害時対応

マイグレーション失敗時はメンテナンスモードが有効なまま残る可能性がある。手動でメンテナンスモードを解除し、マイグレーションの問題を調査・修正後に再実行する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 各マイグレーションファイルごと |
| コミットタイミング | 各マイグレーション成功後 |
| ロールバック条件 | 個別マイグレーションでのエラー発生時 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数件〜数十件のマイグレーション |
| 目標処理時間 | マイグレーション内容に依存（数秒〜数分） |
| メモリ使用量上限 | 通常のDjangoプロセス制限内 |

## 排他制御

メンテナンスモードにより、処理中は他のユーザーからのアクセスをブロックする。これにより、マイグレーション中のデータ不整合を防止する。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 処理開始時 | "Checking for pending database migrations" |
| 情報ログ | 各マイグレーション実行時 | マイグレーション名 |
| エラーログ | エラー発生時 | エラー詳細 |
| 終了ログ | 処理完了時 | "Database migrations complete" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | マイグレーション内容に依存 | システム管理者 |
| エラー発生 | 1件以上 | システム管理者 |

## 備考

- 本コマンドはDjango管理コマンド（BaseCommand）として実装されている
- 実行方法: `python manage.py runmigrations`
- 内部的にInvenTree.tasks.check_for_migrations関数を呼び出す
- force=Trueにより、INVENTREE_AUTO_UPDATE設定に関係なく実行
- reload_registry=Falseにより、プラグインレジストリの再読み込みをスキップ
- メンテナンスモードはmaintenance_modeパッケージを使用
- SQLiteの場合、一部のスキーマ変更操作がサポートされない場合がある
- structlogを使用したログ出力
