
【IT】MacのHomebrewでPostgreSQLを14から17にアップグレードする方法
皆さま、こんにちは
ローカル上のPostgreSQLにHerokuDBのデータリストア検証
をしていたときのことです。
ローカルのPostgreSQLのバージョンが古く、
以下のエラーとなりまた。
$ pg_restore --verbose --clean --no-owner --no-privileges -d "$PGURL" ./test.dump
pg_restore: error: unsupported version (1.16) in file header今回は、ローカル上のPostgreSQLのバージョンを
14→17へアップグレードしていきます。
はじめに
Mac で Homebrew を使って PostgreSQL を管理している方に向けて、
バージョン 14 → 17 へアップグレードする手順をまとめました。
単純に `brew upgrade` ではうまくいかず、最悪データを失う可能性もあります。
この記事では、バックアップを取ってから pg_upgrade で安全に移行する方法を紹介します。
1. 現在の環境を確認
まずはインストールされているバージョンを確認します。
今回は、Version14のみ表示されます。
psql --version
brew list --versions postgresql postgresql@14 postgresql@17
brew services list | grep postgresql例:
postgresql@14 14.192. バックアップを取る(必須)
アップグレード作業前に必ずバックアップを取りましょう。
論理バックアップ
pg_dumpall -U "$USER" -f ~/pg_backup_all_$(date +%F).sql
ls -l ~/pg_backup_all_$(date +%F).sql
-rw-r--r--@ 1 test staff 19573 7 20 08:25 /Users/test/pg_backup_all_2025-07-20.sqlデータディレクトリの確認
echo $(brew --prefix)/var/postgresql@14
/opt/homebrew/var/postgresql@14必要ならこのディレクトリごとコピーして物理バックアップを残しておくのも安心です。
3. PostgreSQL 14 を停止
brew services stop postgresql@14
lsof -i :5432 || true # ポート使用状況の確認4. PostgreSQL 17 をインストール
brew update
brew install postgresql@175. 新しいデータディレクトリを初期化
BREW_PREFIX=$(brew --prefix)
NEW=$BREW_PREFIX/var/postgresql@17
$(brew --prefix)/opt/postgresql@17/bin/initdb -D "$NEW" -E UTF8 --locale=C6. データをアップグレード(pg_upgrade)
最も速く安全なのは pg_upgrade を使う方法です。
BREW_PREFIX=$(brew --prefix)
"$BREW_PREFIX/opt/postgresql@17/bin/pg_upgrade" \
-b "$BREW_PREFIX/opt/postgresql@14/bin" \
-B "$BREW_PREFIX/opt/postgresql@17/bin" \
-d "$BREW_PREFIX/var/postgresql@14" \
-D "$BREW_PREFIX/var/postgresql@17"完了後に表示されるスクリプトを実行します。
/opt/homebrew/opt/postgresql@17/bin/vacuumdb --all --analyze-in-stages7. PostgreSQL17 をデフォルトにして起動
brew unlink postgresql@14
brew link postgresql@17
brew services start postgresql@17
psql --version # → psql (PostgreSQL) 17.x起動後の確認
pgAdmin4等で接続し、DBが正常移行出来ているか確認します。

旧クラスターのデータファイルが削除
Version17が正常に起動出来たら旧環境のデータファイルを削除します。
./delete_old_cluster.sh8. もし失敗したら?
旧DBを再度起動:
brew services stop postgresql@17
brew services start postgresql@14バックアップからリストア:
psql -U "$USER" -f ~/pg_backup_all_YYYY-MM-DD.sqlよくあるハマりどころ
ポート競合: 旧DBが5432を掴んでいると新DBが起動できない。旧を止めるか、旧側の `postgresql.conf` を変更。
拡張機能(postgisなど): 新バージョンに対応したものを再インストールしてから `CREATE EXTENSION` し直す。
設定ファイル: 丸ごとコピーせず、必要な設定だけ移植する。
まとめ
バックアップは必須
pg_upgrade を使うと高速・安全に移行可能
設定ファイルや拡張機能は新環境に合わせて再構築が必要
PostgreSQL はメジャーアップデートのたびに注意が必要ですが、
手順を踏めば問題なく移行できます。
👉 実際にやってみると、作業自体は 10〜20分程度 で終わります。
ただし、拡張を多用している環境では追加の調整が必要になるので、停止時間には余裕を持って作業ください。
では
また!