PostgreSQL アップグレードガイドを追加

yasulab · yasulab · commit ac4d148eb868 · 2026-01-21T12:58:07.000+09:00
- pg_upgrade によるデータ保持アップグレード
- インストール方法
- トラブルシューティングなど
diff --git a/doc/how_to_upgrade_postgresql.md b/doc/how_to_upgrade_postgresql.md
@@ -0,0 +1,346 @@
+# PostgreSQL アップグレードガイド
+
+## 背景
+
+`heroku pg:pull` でデータベースをプルする際、**本番環境とローカル環境の PostgreSQL メジャーバージョンが一致している必要があります**。
+
+バージョンが異なると、以下のようなエラーが発生します：
+
+```
+pg_dump: エラー: サーバーバージョンの不一致のため処理を中断します
+pg_dump: 詳細: サーバーバージョン: X.Y、pg_dump バージョン: X.Y (Homebrew)
+```
+
+**例**（2026年1月時点）：
+- 本番環境: PostgreSQL 17.6
+- ローカル環境: PostgreSQL 16.9
+- 結果: バージョン不一致でエラー
+
+## 本番環境のバージョンを確認
+
+まず、本番環境（Heroku）の PostgreSQL バージョンを確認します：
+
+```bash
+heroku pg:info --app coderdojo-japan | grep "PG Version"
+```
+
+## 現在のローカルバージョンを確認
+
+```bash
+psql --version
+```
+
+本番環境と同じメジャーバージョン（例: 両方とも 17.x）であれば問題ありません。異なる場合はアップグレードが必要です。
+
+## アップグレード方法
+
+どちらのオプションを選ぶべきか：
+- **他のプロジェクトのデータベースも保持したい** → **オプション1（pg_upgrade）を推奨**
+- **すべてのデータベースを本番から再プルできる** → オプション2（クリーンインストール）が簡単
+
+### オプション1: データを保持してアップグレード（pg_upgrade 使用）
+
+既存のローカル DB データを保持したい場合、PostgreSQL の `pg_upgrade` ツールを使用します。
+
+**このオプションの利点**:
+- すべてのデータベース（複数プロジェクト）を一度に移行できる
+- データ損失のリスクがない
+- 移行後すぐに作業を再開できる
+
+**このオプションの欠点**:
+- 手順が複雑（10ステップ）
+- 互換性チェックやデータディレクトリの準備が必要
+
+```bash
+# 1. 新しいバージョンをインストール
+brew install postgresql@<新しいバージョン>
+
+# 2. 古いバージョンを停止
+brew services stop postgresql@<古いバージョン>
+
+# 3. 互換性チェック（安全確認、データは変更されない）
+/opt/homebrew/opt/postgresql@<新しいバージョン>/bin/pg_upgrade \
+  --old-datadir /opt/homebrew/var/postgresql@<古いバージョン> \
+  --new-datadir /opt/homebrew/var/postgresql@<新しいバージョン> \
+  --old-bindir /opt/homebrew/opt/postgresql@<古いバージョン>/bin \
+  --new-bindir /opt/homebrew/opt/postgresql@<新しいバージョン>/bin \
+  --check
+
+# 4. データディレクトリの準備（brew install で自動初期化されるため）
+mv /opt/homebrew/var/postgresql@<新しいバージョン> \
+   /opt/homebrew/var/postgresql@<新しいバージョン>.initial
+mkdir -p /opt/homebrew/var/postgresql@<新しいバージョン>
+/opt/homebrew/opt/postgresql@<新しいバージョン>/bin/initdb \
+  -D /opt/homebrew/var/postgresql@<新しいバージョン> \
+  --locale=en_US.UTF-8 -E UTF-8
+
+# 5. 実際のアップグレード実行（--check フラグなし）
+/opt/homebrew/opt/postgresql@<新しいバージョン>/bin/pg_upgrade \
+  --old-datadir /opt/homebrew/var/postgresql@<古いバージョン> \
+  --new-datadir /opt/homebrew/var/postgresql@<新しいバージョン> \
+  --old-bindir /opt/homebrew/opt/postgresql@<古いバージョン>/bin \
+  --new-bindir /opt/homebrew/opt/postgresql@<新しいバージョン>/bin
+
+# 6. 新しいバージョンを起動
+brew services start postgresql@<新しいバージョン>
+
+# 7. PATH を更新（新しいターミナルで有効化）
+echo 'export PATH="/opt/homebrew/opt/postgresql@<新しいバージョン>/bin:$PATH"' >> ~/.zshrc
+
+# 8. 現在のセッションで PATH を更新
+export PATH="/opt/homebrew/opt/postgresql@<新しいバージョン>/bin:$PATH"
+
+# 9. オプティマイザ統計を更新（pg_upgrade 推奨）
+/opt/homebrew/opt/postgresql@<新しいバージョン>/bin/vacuumdb --all --analyze-in-stages
+
+# 10. バージョン確認
+psql --version
+```
+
+**Intel Mac の場合**: `/opt/homebrew` を `/usr/local` に置き換えてください。
+
+### オプション2: クリーンインストール（簡単だが注意が必要）
+
+**⚠️ 警告**: このオプションでは、古いバージョンの**すべてのデータベース**が削除されます。他の Rails プロジェクトのデータベースも含まれます。
+
+**このオプションが適している場合**:
+- すべてのプロジェクトのデータベースを本番から再プルできる
+- ローカルに重要なデータベースがない
+- または、必要なデータベースを事前にバックアップ済み
+
+**手順**:
+
+```bash
+# 0. 重要なデータベースをバックアップ（必要に応じて）
+psql -l  # 現在のデータベース一覧を確認
+pg_dump <データベース名> > backup_<データベース名>.sql
+
+# 1. 古いバージョンを停止・アンインストール
+brew services stop postgresql@<古いバージョン>
+brew uninstall postgresql@<古いバージョン>
+
+# 2. 新しいバージョンをインストール
+brew install postgresql@<新しいバージョン>
+
+# 3. 新しいバージョンを起動
+brew services start postgresql@<新しいバージョン>
+
+# 4. PATH を更新（新しいターミナルで有効化）
+echo 'export PATH="/opt/homebrew/opt/postgresql@<新しいバージョン>/bin:$PATH"' >> ~/.zshrc
+
+# 5. 現在のセッションで PATH を更新
+export PATH="/opt/homebrew/opt/postgresql@<新しいバージョン>/bin:$PATH"
+
+# 6. バージョン確認
+psql --version
+
+# 7. バックアップから復元（必要に応じて）
+createdb <データベース名>
+psql <データベース名> < backup_<データベース名>.sql
+```
+
+**Intel Mac の場合**: `/opt/homebrew` を `/usr/local` に置き換えてください。
+
+**推奨**: 他のプロジェクトのデータベースも保持したい場合は、**オプション1（pg_upgrade）を使用してください**。すべてのデータベースを安全に移行できます。
+
+## アップグレード後の確認
+
+```bash
+# 1. PostgreSQL サービスの状態確認
+brew services list | grep postgresql
+# 期待される出力: postgresql@<新しいバージョン> started
+
+# 2. 古いバージョンが動いていないか確認（重要）
+# 複数バージョンが "started" の場合、古いバージョンに接続される可能性あり
+# 古いバージョンが動いている場合: brew services stop postgresql@<古いバージョン>
+
+# 3. psql のバージョン確認
+psql --version
+
+# 4. 実際に接続してサーバーバージョンを確認
+psql -d postgres -c "SELECT version();"
+# クライアント（psql）とサーバーのバージョンが一致しているか確認
+```
+
+## 本番データベースのプル
+
+アップグレード後、本番環境のデータベースをローカルにプルできます：
+
+```bash
+# ローカル DB を削除してから本番データをプル
+RAILS_ENV=development DISABLE_DATABASE_ENVIRONMENT_CHECK=1 bundle exec rails db:drop
+heroku pg:pull DATABASE_URL coderdojo_jp_development --app coderdojo-japan
+
+# マイグレーションを実行（必要に応じて）
+bundle exec rails db:migrate
+
+# ローカルサーバーを起動して確認
+bundle exec rails server
+```
+
+## トラブルシューティング
+
+### 複数バージョンが起動していて接続先が間違う
+
+**症状**: `psql --version` は新しいバージョンを表示するが、`SELECT version()` で古いバージョンに接続される
+
+**原因**: 複数の PostgreSQL サービスが同時に起動している
+
+**解決方法**:
+```bash
+# すべての PostgreSQL サービスの状態を確認
+brew services list | grep postgresql
+
+# 古いバージョンをすべて停止
+brew services stop postgresql@<古いバージョン>
+
+# 新しいバージョンを再起動
+brew services restart postgresql@<新しいバージョン>
+
+# 接続先を確認
+psql -d postgres -c "SELECT version();"
+```
+
+### heroku pg:pull でバージョン不一致エラーが出る
+
+**症状**: `psql --version` は正しいが、`heroku pg:pull` で「pg_dump バージョン: <古い>」エラー
+
+**原因**: Heroku CLI が古い pg_dump を使用している（PATH を無視）
+
+**解決方法**:
+```bash
+# 1. ターミナルを完全に再起動（PATH を完全にリロード）
+# または
+# 2. 新しいターミナルウィンドウを開く
+
+# 3. それでもダメな場合、Heroku CLI を再インストール
+brew reinstall heroku/brew/heroku
+```
+
+### PATH が正しく設定されていない
+
+**症状**: `psql --version` が古いバージョンを表示
+
+**解決方法**:
+```bash
+# 現在の psql のパスを確認
+which psql
+
+# 期待されるパス（Apple Silicon）
+# /opt/homebrew/opt/postgresql@<新しいバージョン>/bin/psql
+
+# 期待されるパス（Intel Mac）
+# /usr/local/opt/postgresql@<新しいバージョン>/bin/psql
+
+# 現在のセッションで PATH を更新
+export PATH="/opt/homebrew/opt/postgresql@<新しいバージョン>/bin:$PATH"
+
+# 新しいターミナルで確認
+psql --version
+```
+
+### PostgreSQL サービスが起動しない
+
+```bash
+# サービスの状態を確認
+brew services list | grep postgresql
+
+# エラー状態の場合、ログを確認
+tail -f /opt/homebrew/var/log/postgresql@<バージョン>.log
+
+# サービスを再起動
+brew services restart postgresql@<バージョン>
+
+# データディレクトリの権限を確認
+ls -la /opt/homebrew/var/postgresql@<バージョン>
+```
+
+## アップグレード完了後のクリーンアップ（オプション）
+
+**⚠️ 重大な警告**: クリーンアップは非常に危険な操作です。**他のプロジェクトのデータベースも削除される可能性があります**。
+
+### クリーンアップ前の必須確認（絶対に省略しないでください）
+
+アップグレードで使用しなかった**すべての PostgreSQL バージョン**に、重要なデータベースが残っていないか確認してください。
+
+```bash
+# 1. インストールされているすべての PostgreSQL バージョンを確認
+brew list | grep postgresql
+
+# 2. 各バージョンのデータベースを確認（重要！）
+# 例: PostgreSQL 14, 15, 16 など、アップグレードに使用しなかったバージョン
+
+# PostgreSQL 14 のデータベース一覧を確認
+/opt/homebrew/opt/postgresql@14/bin/psql -l 2>/dev/null
+
+# PostgreSQL 15 のデータベース一覧を確認
+/opt/homebrew/opt/postgresql@15/bin/psql -l 2>/dev/null
+
+# 3. 重要なデータベースが見つかった場合、必ずバックアップを取る
+/opt/homebrew/opt/postgresql@<バージョン>/bin/pg_dump <データベース名> > ~/backup_<データベース名>_$(date +%Y%m%d).sql
+
+# 4. すべてのプロジェクトで使用されていないことを確認
+# 例: ~/project1, ~/project2 などの config/database.yml を確認
+```
+
+### クリーンアップの安全な手順
+
+すべてのデータベースを確認し、必要なバックアップを取った後のみ実行してください。
+
+```bash
+# 1. 新しいバージョンが正常に動作していることを確認
+psql -d postgres -c "SELECT version();"
+brew services list | grep postgresql
+
+# 2. 削除対象のデータベースを最終確認（再度確認！）
+echo "以下のデータベースが削除されます："
+/opt/homebrew/opt/postgresql@<削除するバージョン>/bin/psql -l
+
+# 3. 本当に削除して良いか、もう一度確認してください
+# バックアップは取りましたか？
+# 他のプロジェクトで使用していませんか？
+
+# 4. 古いバージョンのサービスを停止
+brew services stop postgresql@<削除するバージョン>
+
+# 5. データディレクトリを削除
+rm -rf /opt/homebrew/var/postgresql@<削除するバージョン>
+
+# 6. pg_upgrade で作成されたバックアップも削除（オプション1を使用した場合）
+rm -rf /opt/homebrew/var/postgresql@<新しいバージョン>.initial
+
+# 7. Homebrew パッケージをアンインストール
+brew uninstall postgresql@<削除するバージョン>
+
+# 8. クリーンアップされた状態を確認
+brew services list | grep postgresql
+du -sh /opt/homebrew/var/postgresql@* 2>/dev/null
+```
+
+### 実際に発生した災害事例
+
+**ケース**: 複数の Rails プロジェクトで異なる PostgreSQL バージョンを使用していた環境で、PostgreSQL 16 → 17 へのアップグレード後、PostgreSQL 14 のデータディレクトリを確認せずに削除してしまった。
+
+**結果**:
+- PostgreSQL 14 を使用していた他の商用プロジェクトのデータベースがすべて失われた
+- 本番環境からの再プルが必要になり、復旧に時間がかかった
+- 本番環境がないプロジェクトのデータは完全に失われた
+
+**教訓**:
+1. クリーンアップ前に**すべての PostgreSQL バージョン**のデータベースを確認する
+2. `rm -rf` を実行する前に必ずバックアップを取る
+3. 疑わしい場合は削除しない（ディスク容量は後で整理できる）
+4. 複数プロジェクトを管理している場合、特に注意が必要
+
+**推奨**: クリーンアップを急ぐ必要はありません。数週間運用して問題がないことを確認してから削除しても遅くありません。
+
+## 参考情報
+
+- Heroku の PostgreSQL バージョン: https://devcenter.heroku.com/articles/heroku-postgresql#version-support-and-legacy-infrastructure
+- Homebrew PostgreSQL: https://formulae.brew.sh/formula/postgresql
+- PostgreSQL バージョン一覧: https://www.postgresql.org/support/versioning/
+- pg_upgrade 公式ドキュメント: https://www.postgresql.org/docs/current/pgupgrade.html
+
+## 更新履歴
+
+- 2026-01-21: 初版作成、pg_upgrade の正しい手順を追加、実際の経験に基づく改善
