pg_restore
名稱
pg_restore – 從一個由pg_dump創建的歸檔文件恢復一個PostgreSQL數據庫
大綱
pg_restore [connection-option…] [option…] [filename]
描述
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
在重新創建數據庫對象之前清除（丟棄）它們（除非使用了–if-exists，如果有對象在目標數據庫中不存在，這可能會生成一些無害的錯誤消息）。
-C
–create
在恢復一個數據庫之前先創建它。如果還指定了–clean，在連接到目標數據庫之前丟棄並且重建它。
在使用這個選項時，-d提到的數據庫只被用於發出初始的DROP DATABASE和CREATE DATABASE命令。所有要恢復到該數據庫名中的數據都出現在歸檔中。
-d dbname
–dbname=dbname
連接到數據庫dbname並且直接恢復到該數據庫中。
-e
–exit-on-error
在發送 SQL 命令到該數據庫期間如果碰到一個錯誤就退出。默認行爲是繼續並且在恢復結束時顯示一個錯誤計數。
-f filename
–file=filename
爲生成的腳本或列表（當使用-l時）指定輸出文件。默認是標準輸出。
-F format
–format=format
指定歸檔的格式。並不一定要指定該格式，因爲pg_restore將會自動決定格式。如果指定，可以是下列之一：
c
custom
歸檔是pg_dump的自定義格式。
d
directory
歸檔是一個目錄歸檔。
t
tar
歸檔是一個tar歸檔。
-I index
–index=index
只恢復提及的索引的定義。可以通過寫多個-I開關指定多個索引。
-j number-of-jobs
–jobs=number-of-jobs
使用併發任務運行pg_restore中最耗時的部分 — 載入數據、創建索引或者創建約束。對於一個運行在多處理器機器上的服務器，這個選項能夠大幅度減少恢復一個大型數據庫的時間。
每一個任務是一個進程或者一個線程，這取決於操作系統，它們都使用一個獨立的服務器連接。
這個選項的最佳值取決於服務器、客戶端以及網絡的硬件設置。因素包括 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 namespace
–schema=schema
只恢復在被提及的模式中的對象。可以用多個-n開關來指定多個模式。這可以與-t選項組合在一起只恢復一個指定的表。
-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"包括視圖、物化視圖、序列和外部表。可以寫上多個-t開關可以選擇多個表。這個選項可以和-n選項結合在一起指定一個特定模式中的表。
注意: 在指定-t時，pg_restore不會嘗試恢復所選表可能依賴的任何其他數據庫對象。因此，無法確保能成功地把一個特定表恢復到一個乾淨的數據庫中。
注意: 這個標誌的行爲和pg_dump的-t標誌不一樣。在pg_restore中當前沒有任何通配符匹配的規定，也不能在其-t選項中包括模式的名稱。
注意: 在PostgreSQL 9.6之前的版本中，這個標誌只匹配表，而並不匹配其他類型的關係。
-T trigger
–trigger=trigger
只恢復所提及的觸發器。可以用多個-T開關指定多個觸發器。
-v
–verbose
指定冗長模式。
-V
–version
打印該pg_restore的版本並退出。
-x
–no-privileges
–no-acl
阻止恢復訪問特權（授予/收回命令）。
-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設置爲 off 來確保所有數據都被恢復到表中。如果用戶不擁有足夠繞過行安全性的特權，那麼會拋出一個錯誤。這個參數指示pg_restore把row_security設置爲 on允許用戶嘗試恢復啓用了行安全性的表的內容。如果用戶沒有從轉儲向表中插入行的權限，這仍將失敗。
注意當前這個選項還要求轉儲處於INSERT格式，因爲COPY TO不支持行安全性。
–if-exists
在清理數據庫對象時使用條件命令（即增加一個IF EXISTS子句）。只有指定了–clean時，這個選項纔有效。
–no-data-for-failed-tables
默認情況下，即便表的創建命令失敗（例如因爲表已經存在），表數據也會被恢復。通過這個選項，對這類表的數據會被跳過。如果目標數據庫已經包含了想要的表內容，這種行爲又很有有用。例如，PostgreSQL擴展（如PostGIS）的輔助表可能已經被載入到目標數據庫中，指定這個選項就能阻止把重複的或者廢棄的數據載入到這些表中。
只有當直接恢復到一個數據庫中時這個選項纔有效，在產生 SQL腳本輸出時這個選項不會產生效果。
–no-security-labels
不要輸出恢復安全標籤的命令，即使歸檔中包含安全標籤。
–no-tablespaces
不輸出命令選擇表空間。通過這個選項，所有的對象都會被創建在恢復時的默認表空間中。
–section=sectionname
只恢復提及的小節。小節的名稱可以是pre-data、data或者post-data。可以把這個選項指定多次來選擇多個小節。默認值是恢復所有小節。
數據小節包含實際的表數據以及大對象定義。Post-data 項由索引定義、觸發器、規則和除已驗證的檢查約束之外的約束構成。Pre-data 項由所有其他數據定義項構成。
–strict-names
要求每一個模式（-n/–schema）以及表（-t/–table）限定詞匹配備份文件中至少一個模式/表。
–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所需的特權但是能夠切換到一個具有所需權利的角色時，這個選項很有用。一些安裝有針對直接作爲超級用戶登錄的策略，使用這個選項可以讓轉儲在不違反該策略的前提下完成。
環境
PGHOST
PGOPTIONS
PGPORT
PGUSER
默認連接參數
和大部分其他PostgreSQL工具相似，這個工具也使用libpq（見第 32.14 節）支持的環境變量。
診斷
當使用-d選項指定一個直接數據庫連接時，pg_restore在內部執行SELECT語句。如果你運行pg_restore時出現問題，確定你能夠從正在使用的數據庫中選擇信息，例如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只會用它來爲mydb發出CREATE DATABASE命令。通過-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，並且先恢復 10 再恢復 6。
$ pg_restore -L db.list db.dump