# pg_restore ## Name pg_restore?--? 從pg_dump創建的備份文件中恢復PostgreSQL數據庫 ## Synopsis `pg_restore` [`_connection-option_`...] [`_option_`...] [`_filename_`] ## 描述 pg_restore用于恢復由[pg_dump](#calibre_link-437) 轉儲的任何非純文本格式中的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` 創建數據庫對象前先清理(刪除)它們。（如果任一對象不在目標數據庫中， 這可能會產生一些無害的錯誤信息。） `-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` `--ignore-version` 一個現在已經忽略了的已廢棄的選項。 `-I` `_index_` `--index=``_index_` 只恢復命名的索引。 `-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_` 只恢復指定名字的模式里面的對象。這個選項可以和`-t`選項一起使用， 實現只轉儲一個表的數據。 `-O` `--no-owner` 不要輸出設置對象權限與最初數據庫匹配的命令。缺省時，pg_restore 發出`ALTER OWNER`或`SET SESSION AUTHORIZATION` 語句設置創建出來的模式元素的所有者權限。如果最初的數據庫連接不是由超級用戶 (或者是擁有所有創建出來的對象的同一個用戶)發起的，那么這些語句將失敗。 如果使用`-O`，那么任何用戶都可以用于初始的連接， 并且這個用戶將擁有所有創建出來的對象。 `-P` `_function-name(argtype [, ...])_` `--function=``_function-name(argtype [, ...])_` 只恢復指定的命名函數。請注意仔細拼寫函數名及其參數，應該和轉儲的內容列表中的完全一樣。 `-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_` 只恢復指定的表的定義和/或數據。可以聲明多個`-t`指定多個表。 可以和`-n`選項組合以聲明一個模式。 `-T` `_trigger_` `--trigger=``_trigger_` 只恢復指定的觸發器。 `-v` `--verbose` 聲明冗余模式。 `-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`聲明一個超級用戶名，或者更好是以超級用戶身份運行 pg_restore。 `--no-data-for-failed-tables` 缺省時，即使創建表的命令因為該表已經存在而失敗了，表中的數據仍將被恢復。 使用這個選項之后，這些表的數據就將跳過恢復操作。 如果目標數據庫已經包含所需恢復的某些表的內容時，該選項就很有用處了。 比如，用于PostgreSQL擴展的輔助表(例如PostGIS) 就可能已經在目標數據庫中恢復過了， 使用該選項就可以防止多次恢復以致重復或者覆蓋了已經恢復的數據。 該選項僅在直接向一個數據庫中恢復的時候有效，在生成 SQL 腳本輸出時無效。 `--no-security-labels` 不要輸出恢復安全標簽的命令，即使歸檔包含它們。 `--no-tablespaces` 不要輸出選擇表空間的命令。有這個選項，在恢復期間所有的對象都將在缺省表空間中創建。 `--section=``_sectionname_` 值恢復指定的章節。章節名可以是`pre-data`, `data`, 或 `post-data`。可以多次聲明這個選項以選擇多個章節。缺省是恢復所有章節。 數據章節包含實際的表數據和大對象定義。原始數據項包含索引、觸發器、規則和約束 （除了驗證檢查約束）的定義。先前的數據項包含所有其他數據定義項。 `--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支持的環境變量（參閱[Section 31.14](#calibre_link-39)）。 不過，當沒有提供數據庫名字時，并不讀取`PGDATABASE`。 ## 診斷 當使用`-d`選項聲明了直接數據庫連接時， pg_restore在內部執行SQL語句。 如果你運行pg_restore出了毛病， 請確保你能用類似[psql](#calibre_link-23)這樣的東西從數據庫中選取信息。 還有，將會應用libpq前端庫使用的任何缺省連接設置和環境變量。 ## 注意 如果你的安裝給`template1`數據庫增加了任何你自己的東西， 那么請注意把pg_restore的輸出恢復到一個真正空的數據庫中； 否則你可能會收到因為重復定義所追加的對象而造成的錯誤信息。 要制作一個沒有任何本地附屬物的數據庫，可以從`template0`而不是 `template1`拷貝，比如： ``` CREATE DATABASE foo WITH TEMPLATE template0; ``` pg_restore的局限如下： * 當向一個已經存在的表恢復數據，并且還使用了`--disable-triggers`選項時， pg_restore在插入數據前放出一些查詢關閉用戶表上的觸發器， 在數據插入完成后重新打開它們。如果恢復的中途停止，那么系統表可能處于錯誤狀態。 * pg_restore不能選擇性的的恢復大對象。 例如，只恢復指定的表。如果一個歸檔包含大對象，那么所有大對象都將被恢復， 或如果他們通過`-L`、`-t`或其他選項排除則一個也不恢復。 參閱[pg_dump](#calibre_link-437)的文擋獲取有關pg_dump的局限的細節。 一旦完成恢復，最好在每個恢復的對象上運行`ANALYZE`， 以便給優化器有用的統計。參閱[Section 23.1.3](#calibre_link-446) 和[Section 23.1.6](#calibre_link-77)獲取更多信息。 ## 例子 假定我們已經轉儲了`mydb`數據庫到一個自定義格式的文件中： ``` <samp class="literal">$</samp> <kbd class="literal">pg_dump -Fc mydb > db.dump</kbd> ``` 刪除該數據庫并從轉儲中重建： ``` <samp class="literal">$</samp> <kbd class="literal">dropdb mydb</kbd> <samp class="literal">$</samp> <kbd class="literal">pg_restore -C -d postgres db.dump</kbd> ``` 在`-d`中指定的數據庫可以是當前集群中的任意數據庫；pg_restore 僅用該名字來為`mydb`發出`CREATE DATABASE`命令。 使用`-C`可以確保數據總是會被恢復到轉儲文件中指定名字的數據庫里面。 將轉儲出來的數據重新加載到一個新建的數據庫`newdb`中： ``` <samp class="literal">$</samp> <kbd class="literal">createdb -T template0 newdb</kbd> <samp class="literal">$</samp> <kbd class="literal">pg_restore -d newdb db.dump</kbd> ``` 注意，這里沒有使用`-C`選項，而是直接鏈接到將要恢復的數據庫上。 還要注意的是，我們從`template0`而不是`template1` 創建了新數據庫以確保干凈。 要對項目重新排序，首先必須轉儲歸檔的目錄： ``` <samp class="literal">$</samp> <kbd class="literal">pg_restore -l db.dump > db.list</kbd> ``` 這個文件由一行頭和每個條目一行組成，比如： ``` ; ; 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 (以這個順序)： ``` <samp class="literal">$</samp> <kbd class="literal">pg_restore -L db.list db.dump</kbd> ``` ## 又見 [pg_dump](#calibre_link-437), [pg_dumpall](#calibre_link-439), [psql](#calibre_link-23)