Fix deployment issue, see DEPLOYMENT_MIGRATION_GUIDE_en.md

DEPLOYMENT_MIGRATION_GUIDE.md

@@ -0,0 +1,187 @@
+# 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依存関係の問題を回避し、安全にデプロイが可能になります。