pg_upgrade — 升級 PostgreSQL 伺服器例項
pg_upgrade -b oldbindir [-B newbindir] -d oldconfigdir -D newconfigdir [option...]
pg_upgrade (以前稱為 pg_migrator) 允許在不進行通常需要進行主版本升級的轉儲/恢復操作（例如，從 12.14 升級到 13.10 或從 14.9 升級到 15.5）的情況下，將 PostgreSQL 資料檔案中的資料升級到更高版本。對於次要版本升級（例如，從 12.7 升級到 12.8 或從 14.1 升級到 14.5），則不需要此工具。
PostgreSQL 的主要釋出版本定期會新增新功能，這些功能經常會改變系統表的佈局，但內部資料儲存格式很少改變。pg_upgrade 利用這一事實，透過建立新的系統表並簡單地重用舊的使用者資料檔案來執行快速升級。如果未來的主版本更改了資料儲存格式，導致舊資料格式不可讀，那麼 pg_upgrade 將無法用於此類升級。（社群將盡力避免這種情況。）
pg_upgrade 會盡力確保舊叢集和新叢集在二進位制相容性方面相容，例如，透過檢查相容的編譯時設定，包括 32/64 位二進位制檔案。任何外部模組也必須二進位制相容，這一點很重要，儘管 pg_upgrade 無法檢查這一點。
pg_upgrade 支援從 9.2.X 及更高版本升級到 PostgreSQL 的當前主版本，包括快照版本和 beta 版本。
升級叢集會導致目標伺服器執行源超級使用者選擇的任意程式碼。在升級前，請確保源超級使用者是受信任的。
pg_upgrade 接受以下命令列引數：
-b bindir--old-bindir=bindir舊 PostgreSQL 可執行檔案目錄；環境變數 PGBINOLD。
-B bindir--new-bindir=bindir新 PostgreSQL 可執行檔案目錄；預設是 pg_upgrade 所在的目錄；環境變數 PGBINNEW。
-c--check僅檢查叢集，不更改任何資料。
-d configdir--old-datadir=configdir舊資料庫叢集配置目錄；環境變數 PGDATAOLD。
-D configdir--new-datadir=configdir新資料庫叢集配置目錄；環境變數 PGDATANEW。
-j njobs--jobs=njobs要使用的併發連線和程序/執行緒數。
-k--link使用硬連結而不是將檔案複製到新叢集。
-N--no-sync預設情況下，pg_upgrade 會等待所有已升級叢集的檔案安全寫入磁碟。此選項導致 pg_upgrade 在不等待的情況下返回，這樣更快，但意味著後續的作業系統崩潰可能會導致資料目錄損壞。通常，此選項對測試很有用，但不應在生產環境中使用。
-o options--old-options options要直接傳遞給舊 postgres 命令的選項；多個選項呼叫會被追加。
-O options--new-options options要直接傳遞給新 postgres 命令的選項；多個選項呼叫會被追加。
-p port--old-port=port舊叢集的埠號；環境變數 PGPORTOLD。
-P port--new-port=port新叢集的埠號；環境變數 PGPORTNEW。
-r--retain即使升級成功，也保留 SQL 和日誌檔案。
-s dir--socketdir=dir升級期間用於 postmaster 套接字（socket）的目錄；預設是當前工作目錄；環境變數 PGSOCKETDIR。
-U username--username=username叢集的安裝使用者名稱；環境變數 PGUSER。
-v--verbose啟用詳細的內部日誌記錄。
-V--version顯示版本資訊，然後退出。
--clone使用高效的檔案克隆（在某些系統上稱為“reflinks”）而不是將檔案複製到新叢集。這可以實現近乎即時的複製資料檔案，提供 -k/--link 的速度優勢，同時保持舊叢集不變。
檔案克隆僅在某些作業系統和檔案系統上受支援。如果選擇了克隆但不支援，pg_upgrade 執行將報錯。目前，它支援 Linux（核心 4.5 或更高版本）上的 Btrfs 和 XFS（在建立時支援 reflink 的檔案系統上），以及 macOS 上的 APFS。
--copy將檔案複製到新叢集。這是預設選項。（另請參閱 --link、--clone、--copy-file-range 和 --swap。）
--copy-file-range使用 copy_file_range 系統呼叫進行高效複製。在某些檔案系統上，這會產生類似於 --clone 的結果，共享物理磁碟塊，而在其他檔案系統上，它可能仍然複製塊，但透過最佳化路徑進行。目前，它在 Linux 和 FreeBSD 上受支援。
--no-statistics不要將統計資訊從舊叢集還原到新叢集。
--set-char-signedness=option手動設定新叢集的預設 char 型別有符號/無符號行為。可能的值為 signed 和 unsigned。
在 C 語言中，char 型別的預設有符號/無符號行為（當未明確指定時）因平臺而異。例如，在 x86 CPU 上 char 預設為 signed char，而在 ARM CPU 上則預設為 unsigned char。
從 PostgreSQL 18 開始，資料庫叢集維護自己的預設 char 有符號/無符號設定，可用於確保在具有不同預設 char 有符號/無符號行為的平臺上實現一致的行為。預設情況下，pg_upgrade 在從現有叢集升級時會保留 char 有符號/無符號設定。但是，當從 PostgreSQL 17 或更早版本升級時，pg_upgrade 會採用其構建平臺的 char 有符號/無符號行為。
此選項允許您顯式設定新叢集的預設 char 有符號/無符號行為，從而覆蓋任何繼承的值。以下是此選項相關的兩種特定場景：
如果您計劃在升級後遷移到其他平臺，則不應使用此選項。預設行為在這種情況下是正確的。請在原始平臺上使用此標誌進行升級，然後再遷移叢集。這是推薦且最安全的方法。
如果您已將叢集遷移到具有不同 char 有符號/無符號行為的平臺（例如，從基於 x86 的系統遷移到基於 ARM 的系統），則應使用此選項指定與原始平臺預設 char 有符號/無符號行為匹配的設定。此外，在遷移資料檔案和執行 pg_upgrade 之間，不得修改任何資料檔案。pg_upgrade 應該是在新平臺上啟動叢集的第一個操作。
--swap將資料目錄從舊叢集移到新叢集。然後，用為新叢集生成的目錄替換目錄檔案。此模式的效能可能優於 --link、--clone、--copy 和 --copy-file-range，尤其是在包含大量關係（relations）的叢集中。
但是，此模式會在舊叢集中建立許多垃圾檔案，如果使用 --sync-method=syncfs，這會延長檔案同步步驟。因此，建議在 --swap 中使用 --sync-method=fsync。
此外，一旦檔案傳輸步驟開始，舊叢集將被破壞性修改，因此不再可以安全啟動。有關詳細資訊，請參閱 第 17 步。
--sync-method=method當設定為 fsync（預設值）時，pg_upgrade 將遞迴地開啟並同步已升級叢集資料目錄中的所有檔案。檔案搜尋將遵循 WAL 目錄和每個配置的表空間（tablespace）的符號連結。
在 Linux 上，還可以使用 syncfs 來請求作業系統同步包含已升級叢集資料目錄、WAL 檔案和每個表空間的整個檔案系統。有關使用 syncfs 時需要注意的注意事項，請參閱 recovery_init_sync_method。
當使用 --no-sync 時，此選項無效。
-?--help顯示幫助資訊，然後退出。
以下是使用 pg_upgrade 進行升級的步驟：
可選：移動舊叢集
如果您使用的是按版本安裝的目錄，例如 /opt/PostgreSQL/18，則不需要移動舊叢集。所有圖形安裝程式都使用按版本安裝的目錄。
如果您的安裝目錄不是按版本區分的，例如 /usr/local/pgsql，則必須移動當前的 PostgreSQL 安裝目錄，以避免與新 PostgreSQL 安裝衝突。一旦當前的 PostgreSQL 伺服器已關閉，就可以安全地重新命名 PostgreSQL 安裝目錄；假設舊目錄是 /usr/local/pgsql，您可以這樣做：
mv /usr/local/pgsql /usr/local/pgsql.old
來重新命名目錄。
對於從原始碼安裝的情況，構建新版本
使用與舊叢集相容的 configure 標誌構建新的 PostgreSQL 原始碼。pg_upgrade 將檢查 pg_controldata 以確保所有設定在開始升級前都是相容的。
安裝新的 PostgreSQL 二進位制檔案
安裝新的伺服器二進位制檔案和支援檔案。pg_upgrade 包含在預設安裝中。
對於原始碼安裝，如果您希望將新伺服器安裝在自定義位置，請使用 prefix 變數：
make prefix=/usr/local/pgsql.new install
初始化新的 PostgreSQL 叢集
使用 initdb 初始化新叢集。同樣，使用與舊叢集匹配的相容 initdb 標誌。許多預編譯的安裝程式會自動執行此步驟。無需啟動新叢集。
安裝擴充套件共享物件檔案
許多擴充套件和自定義模組，無論是來自 contrib 還是其他來源，都使用共享物件檔案（或 DLL），例如 pgcrypto.so。如果舊叢集使用了這些檔案，則必須將與新伺服器二進位制檔案匹配的共享物件檔案安裝到新叢集中，通常透過作業系統命令完成。不要載入模式定義，例如 CREATE EXTENSION pgcrypto，因為這些定義將從舊叢集複製過來。如果有可用的擴充套件更新，pg_upgrade 將報告此情況並建立一個指令碼，該指令碼稍後可以執行以更新它們。
複製自定義全文搜尋檔案
將任何自定義全文搜尋檔案（字典、同義詞、詞彙表、停用詞）從舊叢集複製到新叢集。
調整身份驗證
pg_upgrade 將連線到舊伺服器和新伺服器幾次，因此您可能希望在 pg_hba.conf 中將身份驗證設定為 peer，或者使用 ~/.pgpass 檔案（請參閱 第 32.16 節）。
停止兩個伺服器
確保兩個資料庫伺服器都已停止。在 Unix 系統上，例如使用：
pg_ctl -D /opt/PostgreSQL/12 stop pg_ctl -D /opt/PostgreSQL/18 stop
或在 Windows 上，使用正確的服務名稱：
NET STOP postgresql-12 NET STOP postgresql-18
流複製（streaming replication）和日誌寄送（log-shipping）備用伺服器在此關閉期間必須執行，以便它們接收所有更改。
準備備用伺服器升級
如果您正在使用第 11 步中概述的方法升級備用伺服器，請透過在舊主伺服器和備用伺服器叢集上執行 pg_controldata 來驗證舊備用伺服器是否已同步。驗證所有叢集中的“最新檢查點位置”值是否匹配。另外，請確保新主叢集的 postgresql.conf 檔案中的 wal_level 未設定為 minimal。
執行 pg_upgrade
始終執行新伺服器的 pg_upgrade 二進位制檔案，而不是舊伺服器的。pg_upgrade 需要指定舊叢集和新叢集的資料目錄和可執行檔案（bin）目錄。您還可以指定使用者和埠號，以及您希望資料檔案連結、克隆或交換而不是預設複製行為。
如果您使用連結模式，升級將更快（無需複製檔案）且佔用更少的磁碟空間，但在升級後啟動新集群后，您將無法訪問舊叢集。連結模式還要求舊叢集和新叢集的資料目錄在同一個檔案系統上。（表空間和 pg_wal 可以在不同的檔案系統上。）克隆模式提供相同的速度和磁碟空間優勢，但不會導致在新叢集啟動後舊叢集不可用。克隆模式也要求舊叢集和新叢集的資料目錄在同一個檔案系統上。此模式僅在某些作業系統和檔案系統上可用。如果關係很多，交換模式（swap mode）可能是最快的，但在檔案傳輸步驟開始後，您將無法訪問舊叢集。交換模式還要求舊叢集和新叢集的資料目錄在同一個檔案系統上。
將 --jobs 設定為 2 或更高，允許 pg_upgrade 並行處理多個數據庫和表空間。一個好的起點是機器上的 CPU 核心數。此選項可以顯著減少多資料庫和多表空間伺服器的升級時間。
對於 Windows 使用者，您必須登入到管理員帳戶，然後使用帶引號的目錄執行 pg_upgrade，例如：
pg_upgrade.exe
--old-datadir "C:/Program Files/PostgreSQL/12/data"
--new-datadir "C:/Program Files/PostgreSQL/18/data"
--old-bindir "C:/Program Files/PostgreSQL/12/bin"
--new-bindir "C:/Program Files/PostgreSQL/18/bin"
啟動後，pg_upgrade 將驗證兩個叢集是否相容，然後執行升級。您可以使用 pg_upgrade --check 來僅執行檢查，即使舊伺服器仍在執行。pg_upgrade --check 還會概述您在升級後需要進行的任何手動調整。如果您打算使用連結、克隆、copy-file-range 或交換模式，則應將 --link、--clone、--copy-file-range 或 --swap 選項與 --check 一起使用，以啟用特定模式的檢查。pg_upgrade 需要在當前目錄中具有寫入許可權。
顯然，在升級期間不應有人訪問叢集。pg_upgrade 預設使用埠 50432 執行伺服器，以避免意外的客戶端連線。您可以在升級時對兩個叢集使用相同的埠號，因為舊叢集和新叢集不會同時執行。但是，在檢查正在執行的舊伺服器時，舊埠號和新埠號必須不同。
如果在還原資料庫模式時發生錯誤，pg_upgrade 將退出，您必須按照下面的 第 17 步中的說明恢復到舊叢集。要再次嘗試 pg_upgrade，您需要修改舊叢集，以便 pg_upgrade 模式還原能夠成功。如果問題是 contrib 模組，您可能需要從舊叢集解除安裝 contrib 模組，並在升級後將其安裝到新叢集中，前提是該模組不用於儲存使用者資料。
升級流複製和日誌寄送備用伺服器
如果您使用了連結模式，並且擁有流複製（參見 第 26.2.5 節）或日誌寄送（參見 第 26.2 節）備用伺服器，您可以按照以下步驟快速升級它們。您不會在備用伺服器上執行 pg_upgrade，而是在主伺服器上執行 rsync。請勿啟動任何伺服器。
如果您沒有使用連結模式，或者不擁有/不想使用 rsync，或者想要一個更簡單的解決方案，請跳過本節中的說明，並在 pg_upgrade 完成且新主伺服器正在執行時重新建立備用伺服器。
在備用伺服器上安裝新的 PostgreSQL 二進位制檔案
確保在新備用伺服器上安裝了新的二進位制檔案和支援檔案。
確保新的備用伺服器資料目錄不存在
確保新的備用伺服器資料目錄不存在或為空。如果運行了 initdb，請刪除備用伺服器的新資料目錄。
安裝擴充套件共享物件檔案
在新備用伺服器上安裝與新主叢集相同的擴充套件共享物件檔案。
停止備用伺服器
如果備用伺服器仍在執行，請使用上述說明現在停止它們。
儲存配置檔案
儲存舊備用伺服器配置目錄中您需要保留的任何配置檔案，例如 postgresql.conf（及其包含的任何檔案）、postgresql.auto.conf、pg_hba.conf，因為它們將在下一步中被覆蓋或刪除。
執行 rsync
當使用連結模式時，備用伺服器可以使用 rsync 快速升級。為此，在主伺服器上高於舊叢集和新叢集資料目錄的某個目錄中，在主伺服器上為每個備用伺服器執行此命令：
rsync --archive --delete --hard-links --size-only --no-inc-recursive old_cluster new_cluster remote_dir
其中 old_cluster 和 new_cluster 相對於主伺服器上的當前目錄，而 remote_dir 是備用伺服器上高於舊叢集和新叢集目錄的目錄。主伺服器和備用伺服器上指定目錄下的目錄結構必須匹配。有關指定遠端目錄的詳細資訊，請查閱 rsync 的手冊頁，例如：
rsync --archive --delete --hard-links --size-only --no-inc-recursive /opt/PostgreSQL/12 \
/opt/PostgreSQL/18 standby.example.com:/opt/PostgreSQL
您可以使用 rsync 的 --dry-run 選項來驗證該命令將執行的操作。雖然 rsync 必須在主伺服器上至少為一個備用伺服器執行，但也可以在已升級的備用伺服器上執行 rsync 來升級其他備用伺服器，前提是已升級的備用伺服器尚未啟動。
此操作記錄了 pg_upgrade 的連結模式在主伺服器上建立的連線舊叢集和新叢集之間檔案的連結。然後，它在備用伺服器的舊叢集中查詢匹配的檔案，並在備用伺服器的新叢集中為它們建立連結。在主伺服器上未連結的檔案將從主伺服器複製到備用伺服器。（它們通常很小。）這提供了快速的備用伺服器升級。不幸的是，rsync 會不必要地複製與臨時表和未記錄表（unlogged tables）相關的檔案的連結，因為這些檔案通常在備用伺服器上不存在。
如果您有表空間，您將需要為每個表空間目錄執行類似的 rsync 命令，例如：
rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tblsp/PG_12_201909212 \
/vol1/pg_tblsp/PG_18_202307071 standby.example.com:/vol1/pg_tblsp
如果您已將 pg_wal 目錄移出資料目錄，也必須在這些目錄上執行 rsync。
配置流複製和日誌寄送備用伺服器
配置伺服器進行日誌寄送。（您不需要執行 pg_backup_start() 和 pg_backup_stop() 或進行檔案系統備份，因為備用伺服器仍與主伺服器同步。）如果舊主伺服器的版本低於 17.0，那麼主伺服器上的插槽（slots）不會複製到新備用伺服器，因此所有舊備用伺服器上的插槽都必須手動重新建立。如果舊主伺服器是 17.0 或更高版本，那麼只有主伺服器上的邏輯插槽會被複制到新備用伺服器，但舊備用伺服器上的其他插槽不會被複制，因此必須手動重新建立。
恢復 pg_hba.conf
如果您修改了 pg_hba.conf，請恢復其原始設定。可能還需要調整新叢集中的其他配置檔案以匹配舊叢集，例如 postgresql.conf（及其包含的任何檔案）、postgresql.auto.conf。
啟動新伺服器
現在可以安全地啟動新伺服器，然後啟動任何透過 rsync 複製的備用伺服器。
升級後處理
如果需要進行任何升級後處理，pg_upgrade 將在其完成時發出警告。它還將生成必須由管理員執行的指令碼檔案。指令碼檔案將連線到每個需要進行升級後處理的資料庫。每個指令碼都應使用以下命令執行：
psql --username=postgres --file=script.sql postgres
指令碼可以按任何順序執行，並且在執行後可以刪除。
通常情況下，在重建指令碼執行完成之前訪問指令碼引用的表是不安全的；這樣做可能導致不正確的結果或效能低下。未在重建指令碼中引用的表可以立即訪問。
統計資訊
除非指定了 --no-statistics 選項，否則 pg_upgrade 將將大多數最佳化器統計資訊從舊叢集傳輸到新叢集。但是，某些統計資訊可能不會被傳輸，例如那些使用 CREATE STATISTICS 顯式建立的統計資訊或擴充套件新增的自定義統計資訊。
由於 pg_upgrade 不會傳輸所有統計資訊，因此在升級結束時，您將被指示執行命令來重新生成這些資訊。您可能需要設定連線引數以匹配新叢集。
首先，使用 vacuumdb --all --analyze-in-stages --missing-stats-only 為沒有任何統計資訊的錶快速生成最小最佳化器統計資訊。然後，使用 vacuumdb --all --analyze-only 來確保所有關係都具有最新的累積統計資訊，以觸發 vacuum 和 analyze。對於這兩個命令，使用 --jobs 可以加快速度。如果 vacuum_cost_delay 設定為非零值，可以使用 PGOPTIONS 進行覆蓋以加快統計資訊生成，例如 PGOPTIONS='-c vacuum_cost_delay=0' vacuumdb ...。
刪除舊叢集
一旦您對升級滿意，就可以透過執行 pg_upgrade 完成時提到的指令碼來刪除舊叢集的資料目錄。（如果舊資料目錄中包含使用者定義的表空間，則無法自動刪除。）您還可以刪除舊的安裝目錄（例如 bin、share）。
恢復到舊叢集
如果在執行 pg_upgrade 後，您希望恢復到舊叢集，有以下幾種選擇：
如果使用了 --check 選項，舊叢集未被修改；可以重新啟動它。
如果既未使用 --link 也未使用 --swap，則舊叢集未被修改；可以重新啟動它。
如果使用了 --link 選項，則資料檔案可能在舊叢集和新叢集之間共享。
如果 pg_upgrade 在連結開始前中止，舊叢集未被修改；可以重新啟動它。
如果您沒有啟動新叢集，舊叢集未被修改，除了在連結開始時，$PGDATA/global/pg_control 追加了 .old 字尾。要重新使用舊叢集，請從 $PGDATA/global/pg_control 中刪除 .old 字尾；然後您可以重新啟動舊叢集。
如果您啟動了新叢集，它已經寫入了共享檔案，使用舊叢集是不安全的。在這種情況下，需要從備份中恢復舊叢集。
如果使用了 --swap 選項，舊叢集可能已被破壞性修改。
如果 pg_upgrade 在報告舊叢集不再安全啟動之前中止，則舊叢集未被修改；可以重新啟動它。
如果 pg_upgrade 已報告舊叢集不再安全啟動，則舊叢集已被破壞性修改。在這種情況下，需要從備份中恢復舊叢集。
一些環境變數可用於為命令列選項提供預設值：
PGBINOLD舊 PostgreSQL 可執行檔案目錄；選項 -b/--old-bindir。
PGBINNEW新 PostgreSQL 可執行檔案目錄；選項 -B/--new-bindir。
PGDATAOLD舊資料庫叢集配置目錄；選項 -d/--old-datadir。
PGDATANEW新資料庫叢集配置目錄；選項 -D/--new-datadir。
PGPORTOLD舊叢集的埠號；選項 -p/--old-port。
PGPORTNEW新叢集的埠號；選項 -P/--new-port。
PGSOCKETDIR升級期間用於 postmaster 套接字（socket）的目錄；選項 -s/--socketdir。
PGUSER叢集的安裝使用者名稱；選項 -U/--username。
pg_upgrade 在新叢集的目錄下建立各種工作檔案，如模式轉儲。pg_upgrade_output.d 目錄中，每次執行都會建立一個帶有根據 ISO 8601 格式化（%Y%m%dT%H%M%S）的時間戳的新子目錄，所有生成的檔案都儲存在那裡。pg_upgrade_output.d 及其包含的檔案將在 pg_upgrade 成功完成後自動刪除；但如果出現問題，那裡儲存的檔案可能提供有用的除錯資訊。
pg_upgrade 在舊資料目錄和新資料目錄中啟動短暫的 postmaster。用於與這些 postmaster 通訊的臨時 Unix 套接字檔案預設是在當前工作目錄中建立的。在某些情況下，當前目錄的路徑名可能太長，無法作為有效的套接字名稱。在這種情況下，您可以使用 -s 選項將套接字檔案放在一個路徑名較短的目錄中。出於安全考慮，請確保該目錄不被其他任何使用者讀取或寫入。（在 Windows 上不支援此功能。）
所有失敗、重建和重新索引的情況都會由 pg_upgrade 報告（如果它們影響您的安裝）；重建表和索引的升級後腳本將自動生成。如果您試圖自動化許多叢集的升級，您會發現具有相同資料庫模式的叢集需要對所有叢集升級執行相同的升級後步驟；這是因為升級後步驟基於資料庫模式，而不是使用者資料。
對於部署測試，請建立舊叢集的僅模式副本，插入虛擬資料，然後升級它。
pg_upgrade 不支援升級包含使用這些 reg* OID 引用系統資料型別的表列的資料庫。
regcollation |
regconfig |
regdictionary |
regnamespace |
regoper |
regoperator |
regproc |
regprocedure |
（regclass、regrole 和 regtype 可以升級。）
如果您想使用連結模式，並且不希望在新叢集啟動時修改舊叢集，可以考慮使用克隆模式。如果該模式不可用，請複製舊叢集並在連結模式下進行升級。要製作舊叢集的有效副本，請在伺服器執行時使用 rsync 建立舊叢集的髒副本，然後關閉舊伺服器並再次執行 rsync --checksum 以更新副本中的更改，使其一致。（--checksum 是必需的，因為 rsync 的檔案修改時間粒度只有一秒。）您可能需要排除某些檔案，例如 postmaster.pid，如 第 25.3.4 節中所述。如果您的檔案系統支援檔案系統快照或寫時複製（copy-on-write）檔案複製，您可以使用它來備份舊叢集和表空間，儘管快照和副本必須同時建立或在資料庫伺服器關閉期間建立。
如果您在文件中發現任何不正確之處，與您對特定功能的實際體驗不符，或者需要進一步澄清，請使用 此表格 來報告文件問題。