メインコンテンツへスキップ
見出し画像

【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.19

    2. バックアップを取る(必須)

    アップグレード作業前に必ずバックアップを取りましょう。

    論理バックアップ

    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@17

    5. 新しいデータディレクトリを初期化

    BREW_PREFIX=$(brew --prefix)
    NEW=$BREW_PREFIX/var/postgresql@17
    $(brew --prefix)/opt/postgresql@17/bin/initdb -D "$NEW" -E UTF8 --locale=C

    6. データをアップグレード(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-stages

    7. 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.sh

    8. もし失敗したら?

    • 旧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分程度 で終わります。
    ただし、拡張を多用している環境では追加の調整が必要になるので、停止時間には余裕を持って作業ください。


    では
    また!


    過去の記事


     
     
    インフラエンジニアとして実務メモを、 写真作家として写真物語を、 童話作家として物語を書いています。 写真作品は、ポートフォリオサイトとしてまとめていく予定です。

    あなたへのおすすめ