pg_restore

Name

pg_restore --  從一個由 pg_dump 建立的備份文件中恢復 PostgreSQL 資料庫。

Synopsis

pg_restore [option...]

描述

pg_restore 是一種用於恢復由 pg_dump 建立的任何非純文本輸出格式中的 PostgreSQL 資料庫的應用。 它將發出必要的命令來重新構造資料庫,以便於把它恢復成保存它的時候的樣子。 歸檔(備份)文件還允許pg_restore 有選擇地進行恢復, 甚至在恢復前重新排列條目的順序。歸檔的文件設計成可以在不同的硬件體系之間移植。

pg_restore 可以以兩種模式操作:如果聲明了資料庫名字, 那麼歸檔是直接恢復到資料庫裡。大對像只能用直接資料庫連線進行恢復。 否則,先建立一個包含重建資料庫所必須的 SQL 命令的腳本(並且寫入到一個文件或者標準輸出), 類似 pg_dump 輸出純文本格式的時候建立的那種腳本。 因此,一些控制腳本輸出的選項就是摹擬 pg_dump 的操作。

顯然,pg_restore 無法恢復那些不存在歸檔文件中的訊息; 比如,如果歸檔是用"把資料轉儲為 INSERT命令"選項製作的, 那麼 pg_restore 將不能使用 COPY 語句裝載資料。

選項

pg_restore 接受下列命令行參數。

filename

聲明要恢復的備份文件的位置。如果沒有聲明,則使用標準輸入。

-a
--data-only

只恢復資料,而不恢復資料表模式(資料定義)。

-c
--clean

建立資料庫對像前先清理(刪除)它們。

-C
--create

在恢復資料庫之前先建立它。(如果出現了這個選項,和 -d 在一起的資料庫名只是用於發出最初的CREATE DATABASE命令。 所有資料都恢復到名字出現在歸檔中的資料庫中去。)

-d dbname
--dbname=dbname

與資料庫 dbname 連線並且直接恢復到該資料庫中。

-e
--exit-on-error

如果在向資料庫發送 SQL 命令的時候碰到錯誤,則退出。 預設是繼續執行並且在恢復結束時顯示一個錯誤計數。

-f filename
--file=filename

聲明生成的腳本的輸出文件,或者出現-l 選項時用於列資料表的文件,預設是標準輸出。

-F format
--format=format

聲明備份文件的格式。因為pg_restore 會自動判斷格式,所以如果聲明了,它可以是下面之一:

t

備份是一個 tar 歸檔。 使用這個格式允許在恢復資料庫的時候重新排序和/或把資料表模式元素排除出去。 同時還可能在恢復的時候限制裝載的資料。

c

備份的格式是來自pg_dump的客戶化格式。 這是最靈活的格式,因為它允許重新對資料排序,也允許重載資料表模式元素。 預設時這個格式是壓縮的。

-i
--ignore-version

忽略資料庫版本檢查。

-I index
--index=index

只恢復命名的索引。

-l
--list

列出備份的內容。這個操作的輸出可以用 -L 選項限制和重排所恢復的項目。

-L list-file
--use-list=list-file

只恢復在 list-file 裡面的元素,以它們在文件中出現的順序。 您可以移動各個行並且也可以透過在行開頭放 ';' 的方式註釋。(見下文獲取例子。)

-O
--no-owner

不要輸出設置對象的權限,以便與最初的資料庫匹配的命令。 預設時,pg_restore 發出 ALTER OWNERSET SESSION AUTHORIZATION 語句設置建立出來的模式元素的所有者權限。 如果最初的資料庫連接不是由超級用戶(或者是擁有所有建立出來的對象的同一個用戶)發起的,那麼這些語句將失敗。 使用 -O,那麼任何用戶都可以用於初始的連接,並且這個用戶將擁有所有建立出來的對象。

-P function-name(argtype [, ...])
--function=function-name(argtype [, ...])

只恢復指定的命名函數。請注意仔細拼寫函數名及其參數,應該和轉儲的內容列資料表中的完全一樣。

-R
--no-reconnect

這個選項已經廢棄了,但是為了保持向下兼容仍然接受。

-s
--schema-only

只恢復資料表結構(資料定義)。不恢復資料,序列值將重置。

-S username
--superuser=username

設置關閉觸發器時聲明超級用戶的用戶名。 只有在設置了 --disable-triggers 的時候才有用。

-t table
--table=table

只恢復資料表指定的資料表的定義和/或資料。

-T trigger
--trigger=trigger

只恢復指定的觸發器。

-v
--verbose

聲明冗余模式。

-x
--no-privileges
--no-acl

避免 ACL 的恢復(grant/revoke 命令)。

-X use-set-session-authorization
--use-set-session-authorization

輸出 SQL 標準的 SET SESSION AUTHORIZATION 命令,而不是 OWNER TO 命令。 這樣令轉儲與標準兼容的更好,但是根據轉儲中對象的歷史,這個轉儲可能不能恰當地恢復。

-X disable-triggers
--disable-triggers

這個選項只有在執行僅恢復資料的時候才相關。它告訴 pg_restore 在裝載資料的時候執行一些命令臨時關閉在目標資料表上的觸發器。 如果您在資料表上有完整性檢查或者其它觸發器, 而您又不希望在裝載資料的時候激活它們,那麼可以使用這個選項。

目前,為 --disable-triggers 發出的命令必須以超級用戶發出。 因此,您應該也要用 -S 聲明一個超級用戶名,或者更好是設置 --use-set-session-authorization 並且以 PostgreSQL 超級用戶身份執行 pg_restore

pg_restore 還接受下面的命令行參數做為連線參數:

-h host
--host=host

聲明伺服器執行的機器的主機名。 如果數值以斜槓開頭,那麼它被用做 Unix 域套接字的目錄。 預設是從 PGHOST 環境變量中獲取的(如果設置了), 否則將嘗試進行 Unix 域套接字。

-p port
--port=port

聲明伺服器偵聽的 TCP 連接埠或者本地的 Unix 域套接字文件擴展。 預設是環境變量 PGPORT 的值(如果設置了的話), 否則就說編譯的預設。

-U username

以給出用戶身份連線。

-W

強制給出指令提示。如果伺服器要求指令認證,那麼這個應該自動發生。

環境

PGHOST
PGPORT
PGUSER

預設連接參數。

診斷

當使用-d選項聲明了直接資料庫連線時, pg_restore 在內部執行 SQL 語句。如果您執行 pg_restore 出了毛病, 請確保您能用類似 psql 這樣的東西從資料庫中選取訊息。

注意

如果您的安裝給template1資料庫增加了任何您自己的東西, 那麼請注意把 pg_dump 的輸出恢復到一個真正空的資料庫中; 否則您可能會收到因為重複定義所追加的對象而造成的錯誤訊息。要製作一個沒有任何本地附屬物的資料庫, 可以從template0而不是template1拷貝,比如:

CREATE DATABASE foo WITH TEMPLATE = template0;

pg_restore 的局限在下面列出。

又見參閱 pg_dump的文擋獲取有關 pg_dump 的局限的細節。

一旦完成恢復,最好在每個恢復的對象上執行 ANALYZE, 以便給優化器有用的統計。

例子

把一個包含大對象的叫 mydb 的資料庫轉儲到一個tar文件:

$ pg_dump -Ft -b mydb > db.tar

把這個資料庫恢復到現有的叫 newdb 的資料庫中(連同BLOB):

$ pg_restore -d newdb db.tar

要對項目重新排序,首先必須轉儲歸檔的目錄:

$ pg_restore -l archive.file > archive.list

這個文件由一行頭和每個項目一行組成,比如。

;
; Archive created at Fri Jul 28 22:28:36 2000
;     dbname: birds
;     TOC Entries: 74
;     Compression: 0
;     Dump Version: 1.4-0
;     Format: CUSTOM
;
;
; Selected TOC Entries:
;
2; 145344 TABLE species postgres
3; 145344 ACL species
4; 145359 TABLE nt_header postgres
5; 145359 ACL nt_header
6; 145402 TABLE species_records postgres
7; 145402 ACL species_records
8; 145416 TABLE ss_old postgres
9; 145416 ACL ss_old
10; 145433 TABLE map_resolutions postgres
11; 145433 ACL map_resolutions
12; 145443 TABLE hs_old postgres
13; 145443 ACL hs_old

這裡分號是註釋分隔符,而行開頭的數字代資料表賦給每個項目的內部歸檔 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 archive.file archive.list

歷史

pg_restore 工具第一次出現在 PostgreSQL 7.1。

又見

pg_dump, pg_dumpall, psql