pg_restore — 從 pg_dump 建立的封存檔還原 PostgreSQL 資料庫
pg_restore [連線選項...] [選項...] [檔案名稱]
pg_restore 是一個工具程式，用於從 pg_dump 以非純文字格式建立的封存檔還原 PostgreSQL 資料庫。 它會發出重建資料庫到儲存時狀態所需的命令。 封存檔還允許 pg_restore 選擇性地還原內容，甚至在還原之前重新排序項目。 封存檔設計為可在架構之間移植。
pg_restore 可以在兩種模式下運作。 如果指定了資料庫名稱，pg_restore 會連線到該資料庫並將封存內容直接還原到資料庫中。 否則，會建立一個包含重建資料庫所需的 SQL 命令的腳本，並將其寫入檔案或標準輸出。 此腳本輸出等同於 pg_dump 的純文字輸出格式。 因此，控制輸出的一些選項類似於 pg_dump 選項。
顯然，pg_restore 無法還原封存檔中不存在的資訊。 例如，如果封存檔是使用「將資料傾印為 INSERT 命令」選項建立的，則 pg_restore 將無法使用 COPY 陳述式載入資料。
pg_restore 接受以下命令列引數。
filename指定要還原的封存檔 (或目錄，對於目錄格式封存檔) 的位置。 如果未指定，則使用標準輸入。
-a--data-only僅還原資料，不還原綱要 (資料定義)。 如果封存檔中存在，則會還原表格資料、大型物件和序列值。
此選項與指定 --section=data 類似，但由於歷史原因並不相同。
-c--clean在還原資料庫物件之前，發出命令來 DROP 所有將被還原的物件。 此選項對於覆寫現有資料庫非常有用。 如果任何物件在目標資料庫中不存在，除非也指定了 --if-exists，否則會報告可忽略的錯誤訊息。
-C--create在還原到資料庫之前先建立資料庫。 如果也指定了 --clean，則在連線到目標資料庫之前先捨棄並重新建立目標資料庫。
使用 --create，pg_restore 還會還原資料庫的註解 (如果有的話)，以及特定於此資料庫的任何組態變數設定，也就是提及此資料庫的任何 ALTER DATABASE ... SET ... 和 ALTER ROLE ... IN DATABASE ... SET ... 命令。 除非指定了 --no-acl，否則也會還原資料庫本身的存取權限。
使用此選項時，使用 -d 命名的資料庫僅用於發出初始 DROP DATABASE 和 CREATE DATABASE 命令。 所有資料都會還原到封存檔中出現的資料庫名稱中。
-d dbname--dbname=dbname連線到資料庫 dbname 並直接還原到資料庫中。 dbname 可以是連線字串。 如果是這樣，連線字串參數將覆寫任何衝突的命令列選項。
-e--exit-on-error如果在將 SQL 命令傳送到資料庫時遇到錯誤，則退出。 預設是繼續，並在還原結束時顯示錯誤計數。
-f filename--file=filename指定產生腳本的輸出檔案，或與 -l 一起使用時用於清單。 對於 stdout，請使用 -。
--filter=filename指定一個檔案名稱，從該檔案中讀取物件的模式，這些物件會從還原中排除或包含。 這些模式的解譯方式與 -n/--schema 用於包含綱要中的物件，-N/--exclude-schema 用於排除綱要中的物件，-P/--function 用於還原命名的函式，-I/--index 用於還原命名的索引，-t/--table 用於還原命名的表格，或 -T/--trigger 用於還原觸發器相同。 若要從 STDIN 讀取，請使用 - 作為檔案名稱。--filter 選項可以與上述列出的用於包含或排除物件的選項結合使用，也可以多次指定以用於多個篩選檔案。
檔案每列列出一個資料庫樣式，格式如下：
{ include | exclude } { function | index | schema | table | trigger } PATTERN
第一個關鍵字指定是否包含或排除符合樣式的物件。第二個關鍵字指定要使用樣式篩選的物件類型。
function：函式，作用類似於 -P/--function 選項。此關鍵字只能與 include 關鍵字一起使用。
index：索引，作用類似於 -I/--indexes 選項。此關鍵字只能與 include 關鍵字一起使用。
schema：結構描述，作用類似於 -n/--schema 和 -N/--exclude-schema 選項。
table：表格，作用類似於 -t/--table 選項。此關鍵字只能與 include 關鍵字一起使用。
trigger：觸發程序，作用類似於 -T/--trigger 選項。此關鍵字只能與 include 關鍵字一起使用。
以 # 開頭的行被視為註解並忽略。註解也可以放在物件樣式列之後。空白行也會被忽略。有關如何在樣式中執行引用的說明，請參閱樣式。
-F format--format=format指定封存檔的格式。 沒有必要指定格式，因為pg_restore會自動判斷格式。如果指定，它可以是以下之一
ccustom封存檔採用pg_dump的自訂格式。
ddirectory封存檔是目錄封存檔。
ttar封存檔是tar封存檔。
-I index--index=index僅還原指定名稱索引的定義。可以使用多個 -I 參數指定多個索引。
-j number-of-jobs--jobs=number-of-jobs同時執行pg_restore中最耗時的步驟 - 那些載入資料、建立索引或建立約束的步驟 - 使用最多 number-of-jobs 個並行會話。此選項可以顯著減少將大型資料庫還原到在多處理器機器上運行的伺服器的時間。當發出腳本而不是直接連接到資料庫伺服器時，此選項會被忽略。
每個任務是一個進程或一個線程，取決於作業系統，並使用與伺服器的單獨連接。
此選項的最佳值取決於伺服器、用戶端和網路的硬體設定。因素包括 CPU 核心的數量和磁碟設定。一個好的起點是伺服器上的 CPU 核心數量，但在許多情況下，大於該值的數也可能導致更快的還原時間。當然，太高的值會由於抖動而導致效能下降。
此選項僅支援自訂和目錄封存檔格式。輸入必須是常規檔案或目錄（例如，不是管道或標準輸入）。此外，多個任務不能與 --single-transaction 選項一起使用。
-l--list列出封存檔的目錄。此操作的輸出可以用作 -L 選項的輸入。請注意，如果將 -n 或 -t 等篩選開關與 -l 一起使用，它們將限制列出的項目。
-L list-file--use-list=list-file僅還原list-file中列出的那些封存檔元素，並按照它們在檔案中出現的順序還原它們。請注意，如果將 -n 或 -t 等篩選開關與 -L 一起使用，它們將進一步限制還原的項目。
list-file 通常是透過編輯先前 -l 操作的輸出建立的。可以移動或刪除行，也可以透過在行的開頭放置分號（;）來註釋掉行。有關範例，請參閱下文。
-n schema--schema=schema僅還原位於指定結構描述中的物件。可以使用多個 -n 參數指定多個結構描述。這可以與 -t 選項結合使用，以僅還原特定的表格。
-N schema--exclude-schema=schema不要還原位於指定結構描述中的物件。可以使用多個 -N 參數指定要排除的多個結構描述。
當對同一個結構描述名稱同時指定 -n 和 -N 時，-N 參數優先，並且該結構描述會被排除。
-O--no-owner不要輸出用於設定物件所有權以匹配原始資料庫的命令。預設情況下，pg_restore會發出 ALTER OWNER 或 SET SESSION AUTHORIZATION 語句來設定已建立結構描述元素的所有權。除非透過超級使用者（或與腳本中擁有所有物件的用戶相同的用戶）建立到資料庫的初始連線，否則這些語句將失敗。使用 -O，任何使用者名稱都可以用於初始連線，並且此用戶將擁有所有已建立的物件。
-P function-name(argtype [, ...])--function=function-name(argtype [, ...])僅還原指定名稱的函式。請仔細拼寫函數名稱和參數，使其與傾印檔案目錄中顯示的完全相同。可以使用多個 -P 參數指定多個函數。
-R--no-reconnect此選項已過時，但仍為向後相容性所接受。
-s--schema-only只還原綱要（資料定義），不還原資料，前提是封存檔中存在綱要條目。
此選項與 --data-only 相反。它類似於指定 --section=pre-data --section=post-data，但由於歷史原因並不完全相同。
（請勿將此選項與 --schema 選項混淆，後者以不同的含義使用「schema」這個詞彙。）
-S username--superuser=username指定停用觸發器時要使用的超級使用者名稱。 只有在使用 --disable-triggers 時才相關。
-t table--table=table僅還原指定表格的定義和/或資料。 在此目的下，「table」包括視窗 (views)、物化視窗 (materialized views)、序列 (sequences) 和外部表格 (foreign tables)。 可以透過撰寫多個 -t 開關來選取多個表格。 此選項可以與 -n 選項結合使用，以指定特定綱要中的表格。
當指定 -t 時，pg_restore 不會嘗試還原所選表格可能依賴的任何其他資料庫物件。 因此，無法保證將特定表格還原到乾淨的資料庫會成功。
此旗標的行為與 pg_dump 的 -t 旗標不同。 目前在 pg_restore 中沒有任何提供萬用字元比對的功能，也無法在其 -t 中包含綱要名稱。 而且，雖然 pg_dump 的 -t 旗標也會傾印所選表格的附屬物件（例如索引），但 pg_restore 的 -t 旗標不包含此類附屬物件。
在 PostgreSQL 9.6 之前的版本中，此旗標僅比對表格，而不比對任何其他類型的關聯。
-T trigger--trigger=trigger僅還原指定名稱的觸發器。可以使用多個 -T 開關指定多個觸發器。
-v--verbose指定詳細模式。 這將導致 pg_restore 將詳細的物件註解和開始/停止時間輸出到輸出檔案，並將進度訊息輸出到標準錯誤。 重複該選項會導致額外的偵錯層級訊息出現在標準錯誤上。
-V--version列印 pg_restore 版本並結束。
-x--no-privileges--no-acl防止還原存取權限（grant/revoke 指令）。
-1--single-transaction以單一交易執行還原（也就是說，將發出的指令包裝在 BEGIN/COMMIT 中）。 這可確保所有指令都成功完成，或者不套用任何變更。 此選項表示 --exit-on-error。
--disable-triggers此選項僅在執行僅限資料還原時才相關。 它指示 pg_restore 執行指令以在還原資料時暫時停用目標表格上的觸發器。 如果表格上有您不想在資料還原期間調用的參考完整性檢查或其他觸發器，請使用此選項。
目前，為 --disable-triggers 發出的指令必須以超級使用者身分執行。 因此，您還應該使用 -S 指定超級使用者名稱，或者最好以 PostgreSQL 超級使用者身分執行 pg_restore。
--enable-row-security此選項僅在還原具有資料列安全性的表格內容時才相關。 預設情況下，pg_restore 會將 row_security 設為關閉，以確保所有資料都還原到表格中。 如果使用者沒有足夠的權限來繞過資料列安全性，則會拋出錯誤。 此參數指示 pg_restore 改為將 row_security 設為開啟，允許使用者嘗試在啟用資料列安全性的情況下還原表格內容。 如果使用者沒有權限將傾印中的資料列插入表格中，這仍然可能失敗。
請注意，此選項目前還需要傾印採用 INSERT 格式，因為 COPY FROM 不支援資料列安全性。
--if-exists使用 DROP ... IF EXISTS 指令以在 --clean 模式下刪除物件。 這會抑制原本可能報告的「不存在」錯誤。 除非也指定了 --clean，否則此選項無效。
--no-comments即使封存檔包含註解，也不輸出指令來還原註解。
--no-data-for-failed-tables預設情況下，即使表格的建立指令失敗（例如，因為它已存在），也會還原表格資料。 使用此選項，將跳過此類表格的資料。 如果目標資料庫已包含所需的表格內容，則此行為很有用。 例如，PostgreSQL 擴充功能（例如 PostGIS）的輔助表格可能已載入到目標資料庫中；指定此選項可防止重複或過時的資料載入到其中。
此選項僅在直接還原到資料庫時有效，而不是在產生 SQL 指令碼輸出時有效。
--no-publications即使封存檔包含發佈，也不輸出指令來還原發佈。
--no-security-labels即使封存檔包含安全標籤，也不輸出指令來還原安全標籤。
--no-subscriptions即使封存檔包含訂閱，也不輸出指令來還原訂閱。
--no-table-access-method不輸出用於選擇表格存取方法的指令。 使用此選項，所有物件都將使用還原期間預設的表格存取方法建立。
--no-tablespaces不輸出用於選擇表格空間的指令。 使用此選項，所有物件都將在還原期間預設的表格空間中建立。
--section=sectionname僅還原指定的區段。區段名稱可以是 pre-data、data 或 post-data。此選項可以多次指定以選擇多個區段。預設是還原所有區段。
data 區段包含實際的表格資料以及大型物件定義。Post-data 項目包含索引、觸發器、規則和限制的定義，但不包含經過驗證的 check 限制。Pre-data 項目包含所有其他資料定義項目。
--strict-names要求每個 schema (-n/--schema) 和表格 (-t/--table) 限定詞在備份檔案中至少匹配一個 schema/表格。
--transaction-size=N將還原操作作為一系列交易執行，每個交易最多處理 N 個資料庫物件。此選項隱含 --exit-on-error。
--transaction-size 提供了一個介於預設行為（每個 SQL 指令一個交易）和 -1/--single-transaction（所有還原物件一個交易）之間的折衷方案。雖然 --single-transaction 的額外開銷最少，但對於大型資料庫來說可能不切實際，因為交易會鎖定每個還原的物件，可能耗盡伺服器的鎖定表格空間。使用 --transaction-size 並將大小設定為幾千個物件，可以在限制所需鎖定表格空間量的同時，提供幾乎相同的效能優勢。
--use-set-session-authorization輸出 SQL 標準的 SET SESSION AUTHORIZATION 指令，而不是 ALTER OWNER 指令來確定物件的所有權。這使傾印更符合標準，但根據傾印中物件的歷史記錄，可能無法正確還原。
-?--help顯示關於 pg_restore 命令列引數的說明，然後結束。
pg_restore 也接受以下用於連線參數的命令列引數
-h host--host=host指定伺服器執行的機器的主機名稱。如果值以斜線開頭，則將其用作 Unix 網域套接字的目錄。預設值取自 PGHOST 環境變數（如果已設定），否則將嘗試 Unix 網域套接字連線。
-p port--port=port指定伺服器正在偵聽連線的 TCP 埠或本機 Unix 網域套接字檔案延伸名。預設為 PGPORT 環境變數（如果已設定）或編譯時的預設值。
-U username--username=username要連線的使用者名稱。
-w--no-password永遠不要發出密碼提示。如果伺服器需要密碼驗證，並且無法透過其他方式（例如 .pgpass 檔案）取得密碼，則連線嘗試將會失敗。此選項在批次作業和沒有使用者輸入密碼的腳本中非常有用。
-W--password強制 pg_restore 在連線到資料庫之前提示輸入密碼。
此選項並非總是必要的，因為如果伺服器要求密碼驗證，pg_restore 會自動提示輸入密碼。但是，pg_restore 會浪費一次連線嘗試來確認伺服器需要密碼。在某些情況下，值得輸入 -W 以避免額外的連線嘗試。
--role=rolename指定用於執行還原的角色名稱。此選項會導致 pg_restore 在連線到資料庫後發出 SET ROLE rolename 指令。當經過驗證的使用者（由 -U 指定）缺少 pg_restore 所需的權限，但可以切換到具有所需權限的角色時，此選項很有用。某些安裝具有禁止直接以超級使用者身分登入的策略，並且使用此選項可以執行還原，而不會違反該策略。
PGHOSTPGOPTIONSPGPORTPGUSER預設連線參數
PG_COLOR指定是否在診斷訊息中使用顏色。可能的值為 always、auto 和 never。
與大多數其他 PostgreSQL 公用程式一樣，此公用程式也使用 libpq 支援的環境變數（請參閱 第 32.15 節）。但是，當未提供資料庫名稱時，它不會讀取 PGDATABASE。
當使用 -d 選項指定直接資料庫連線時，pg_restore 會在內部執行SQL陳述式。如果您在執行 pg_restore 時遇到問題，請確保您可以使用 psql（例如，psql）從資料庫中選擇資訊。此外，libpq 前端函式庫使用的任何預設連線設定和環境變數都將適用。
如果您的安裝在 template1 資料庫中有任何本地新增項目，請小心將 pg_restore 的輸出載入到一個真正空的資料庫中；否則，您可能會由於新增物件的重複定義而收到錯誤。要建立一個沒有任何本地新增項目的空資料庫，請從 template0 而不是 template1 複製，例如
CREATE DATABASE foo WITH TEMPLATE template0;
pg_restore 的限制如下詳述。
當將資料還原到預先存在的表格並且使用 --disable-triggers 選項時，pg_restore 會發出指令以在插入資料之前停用使用者表格上的觸發器，然後在插入資料後發出指令以重新啟用它們。如果在還原過程中停止，系統目錄可能會處於錯誤狀態。
pg_restore 無法選擇性地還原大型物件；例如，僅還原特定表格的大型物件。如果封存檔包含大型物件，則會還原所有大型物件，或者，如果透過 -L、-t 或其他選項排除它們，則不會還原任何大型物件。
另請參閱 pg_dump 文件，以取得有關 pg_dump 限制的詳細資訊。
還原後，明智的做法是對每個還原的表格執行 ANALYZE，以便最佳化工具擁有有用的統計資訊；請參閱 第 24.1.3 節 和 第 24.1.6 節 以取得更多資訊。
假設我們已將名為 mydb 的資料庫傾印到自訂格式的傾印檔案中
$pg_dump -Fc mydb > db.dump
要刪除資料庫並從傾印檔案重新建立它
$dropdb mydb$pg_restore -C -d postgres db.dump
在 -d 交換器中命名的資料庫可以是叢集中存在的任何資料庫；pg_restore 僅使用它來發出 CREATE DATABASE 命令給 mydb。使用 -C 時，資料始終會還原到傾印檔案中出現的資料庫名稱中。
要將傾印檔案還原到名為 newdb 的新資料庫中
$createdb -T template0 newdb$pg_restore -d newdb db.dump
請注意，我們不使用 -C，而是直接連線到要還原到的資料庫。另請注意，我們從 template0（而不是 template1）複製新的資料庫，以確保它最初是空的。
要重新排序資料庫項目，首先需要傾印封存檔的目錄
$pg_restore -l db.dump > db.list
清單檔案包含一個標頭和每一項的一行，例如
; ; Archive created at Mon Sep 14 13:55:39 2009 ; dbname: DBDEMOS ; TOC Entries: 81 ; Compression: 9 ; Dump Version: 1.10-0 ; Format: CUSTOM ; Integer: 4 bytes ; Offset: 8 bytes ; Dumped from database version: 8.3.5 ; Dumped by pg_dump version: 8.3.8 ; ; ; Selected TOC Entries: ; 3; 2615 2200 SCHEMA - public pasha 1861; 0 0 COMMENT - SCHEMA public pasha 1862; 0 0 ACL - public pasha 317; 1247 17715 TYPE public composite pasha 319; 1247 25899 DOMAIN public domain0 pasha
分號開始一個註解，並且行首的數字指的是分配給每個項目的內部封存 ID。
可以註解掉、刪除和重新排序檔案中的行。例如
10; 145433 TABLE map_resolutions postgres ;2; 145344 TABLE species postgres ;4; 145359 TABLE nt_header postgres 6; 145402 TABLE species_records postgres ;8; 145416 TABLE ss_old postgres
可以用作 pg_restore 的輸入，並且只會按該順序還原項目 10 和 6
$pg_restore -L db.list db.dump
如果您在文件中發現任何不正確、與您使用特定功能的經驗不符或需要進一步澄清的地方，請使用此表單來報告文件問題。