rogaining_srv/DEPLOYMENT_MIGRATION_GUIDE.md

# Deploy先でのMigration手順ガイド

## 推奨手順（安全なアプローチ）

### パターンA: 新規クリーンDeployment（推奨）

```bash
# 1. 旧DBのバックアップ作成
pg_dump rogaining_db > backup_$(date +%Y%m%d_%H%M%S).sql

# 2. Git pullで最新コード取得
git pull origin main

# 3. migration_simple_reset.pyで一括リセット（推奨）
docker compose exec app python migration_simple_reset.py --full

# 4. 必要に応じてデータ復元スクリプト実行
# （既存データがある場合）
```

### パターンB: 段階的Migration修正

```bash
# 1. 旧DBのバックアップ作成
pg_dump rogaining_db > backup_$(date +%Y%m%d_%H%M%S).sql

# 2. Git pullで最新コード取得
git pull origin main

# 3. 問題のあるmigrationファイルを一時的に削除
rm rog/migrations/0011_auto_20250827_1459.py

# 4. 正常なmigrationまで適用
docker compose exec app python manage.py migrate

# 5. migration_simple_reset.pyでクリーンアップ
docker compose exec app python migration_simple_reset.py --reset-only
docker compose exec app python migration_simple_reset.py --apply-only
```

## ⚠️ 元の提案手順の問題点

```bash
１）旧DBをリストア ✅ OK
２）Git pull で最新コード設置 ✅ OK  
３）migrate してDB更新 ❌ 問題: 依存関係エラーで失敗する
４）migration_simple_reset.py実行 ✅ OK
```

**問題**: ステップ3で`NodeNotFoundError`が発生し、migrationが失敗します。

## 具体的なDeployment手順（本番推奨）

### 事前準備
```bash
# 本番環境への接続確認
docker compose ps

# 現在のmigration状態確認
docker compose exec app python manage.py showmigrations
```

### 実行手順

#### Step 1: バックアップ作成
```bash
# データベースバックアップ
docker compose exec postgres-db pg_dump -U admin rogaining_db > deploy_backup_$(date +%Y%m%d_%H%M%S).sql

# 現在のmigrationファイルバックアップ
cp -r rog/migrations rog/migrations_backup_deploy_$(date +%Y%m%d_%H%M%S)
```

#### Step 2: コード更新
```bash
# 最新コード取得
git pull origin main

# migration_simple_reset.pyが存在することを確認
ls -la migration_simple_reset.py
```

#### Step 3: Migration リセット実行
```bash
# 全体的なリセット（推奨）
docker compose exec app python migration_simple_reset.py --full
```

または段階的実行：
```bash
# バックアップのみ
docker compose exec app python migration_simple_reset.py --backup-only

# リセットのみ
docker compose exec app python migration_simple_reset.py --reset-only

# 適用のみ
docker compose exec app python migration_simple_reset.py --apply-only
```

#### Step 4: 結果確認
```bash
# Migration状態確認
docker compose exec app python manage.py showmigrations

# アプリケーション動作確認
docker compose exec app python manage.py check
```

#### Step 5: サービス再起動
```bash
# アプリケーション再起動
docker compose restart app

# 全サービス再起動（必要に応じて）
docker compose restart
```

## トラブルシューティング

### Migration失敗時の対処

```bash
# 1. migration_simple_reset.pyでクリーンアップ
docker compose exec app python migration_simple_reset.py --reset-only

# 2. 手動でmigration状態確認
docker compose exec app python manage.py showmigrations

# 3. 必要に応じて個別migration適用
docker compose exec app python manage.py migrate rog 0001 --fake
```

### バックアップからの復元

```bash
# データベース復元
docker compose exec postgres-db psql -U admin -d rogaining_db < backup_file.sql

# migrationファイル復元
rm -rf rog/migrations
cp -r rog/migrations_backup_deploy_YYYYMMDD_HHMMSS rog/migrations
```

## 重要な注意事項

### ✅ 実行前チェックリスト
- [ ] データベースバックアップ作成済み
- [ ] migrationファイルバックアップ作成済み
- [ ] migration_simple_reset.pyが最新版
- [ ] Docker環境が正常動作中
- [ ] 十分なディスク容量確保

### ⚠️ 避けるべき操作
- `python manage.py migrate`を最初に実行（依存関係エラーの原因）
- バックアップなしでの作業
- 本番環境での実験的操作

### 🔄 ロールバック計画
```bash
# 問題発生時の緊急復元
docker compose down
docker compose exec postgres-db psql -U admin -d rogaining_db < backup_file.sql
cp -r rog/migrations_backup_deploy_YYYYMMDD_HHMMSS rog/migrations
docker compose up -d
```

## 結論

**推奨される最終手順:**

```bash
# 1. バックアップ作成
pg_dump rogaining_db > backup_$(date +%Y%m%d_%H%M%S).sql

# 2. 最新コード取得
git pull origin main

# 3. Migration一括リセット（問題を回避）
docker compose exec app python migration_simple_reset.py --full

# 4. 動作確認
docker compose exec app python manage.py check
docker compose restart app
```

この手順により、Migration依存関係の問題を回避し、安全にデプロイが可能になります。