pg_dump

Name

pg_dump --  將一個PostgreSQL資料庫抽出到一個腳本文件或者其它歸檔文件中

Synopsis

pg_dump [option...] [dbname]

描述

pg_dump 是一個用於備份 PostgreSQL 資料庫的工具。它甚至可以在資料庫正在並發使用的時候進行完整一致的備份。 pg_dump 並不阻塞其它用戶對資料庫的訪問(讀或者寫)。

轉儲格式可以是一個腳本或者歸檔文件。 腳本轉儲的格式是純文本,它包含許多 SQL 命令, 這些 SQL 命令可以用於重建該資料庫並將之恢復到保存成腳本的時候的狀態。 要從這樣的腳本中恢復,使用 psql。 它們甚至可以用於在其它機器甚至是其它硬件體系的機器上重建該資料庫, 透過對腳本進行一些修改,甚至可以在其它 SQL 資料庫產品上重建該資料庫。

另外,還有候選的歸檔文件格式必須和 pg_restore 一起使用重建資料庫。 它們允許 pg_restore 對恢復什麼東西進行選擇, 或者甚至是在恢復之前對需要恢復的條目進行重新排序。 歸檔格式還允許保存和恢復"大對像",這個在腳本轉儲裡是不可能的。 歸檔文件也是設計成可以跨平台移植的。

如果一種候選文件格式和 pg_restore 結合,那麼pg_dump就能提供一種靈活的歸檔和傳輸機制。 pg_dump 可以用於備份整個資料庫, 然後就可以使用 pg_restore 檢查這個歸檔和/或選擇要恢復的資料庫部分。 最靈活等輸出文件格式是"custom(客戶化)"格式(-Fc)。 它允許對歸檔元素進行選取和重新排列, 並且預設時是壓縮的。 tar 格式(-Ft)不是壓縮的並且我們在裝載等時候不可能重排列, 不過它也很靈活;還有,它可以用標準 Unix 工具,比如 tar 處理。

在執行 pg_dump 的時候,我們應該檢查輸出, 看看是否有任何警告存在(在標準錯誤上打印),特別是下面列出的限制。

選項

下面的命令行參數控制輸出的內容和格式。

dbname

聲明將要轉儲的資料庫名。 如果沒有聲明這個參數,那麼使用環境變量 PGDATABASE。 如果那個環境變量也沒聲明,那麼用發起連接的用戶名。

-a
--data-only

只輸出資料,不輸出模式(資料定義)。

這個選項只是對純文本格式有意義。對于歸檔格式,您可以在調用 pg_restore 的時候聲明選項。

-b
--blobs

在轉儲中包含大對象。必須選擇一種非文本輸出格式。

-c
--clean

輸出在建立資料庫建立命令之前先清理(刪除)該資料庫對象的命令。

這個選項只是對純文本格式有意義。對于歸檔格式,您可以在調用 pg_restore 的時候聲明選項。

-C
--create

以一條建立該資料庫本身並且與這個資料庫連線等命令開頭進行輸出。 (如果是這種形式的腳本,那麼您在執行腳本之前和哪個資料庫連線就不重要了。)

這個選項只對純文本格式有意義。對于歸檔格式,您可以在調用 pg_restore 的時候聲明該選項。

-d
--inserts

將資料輸出為的INSERT命令(而不是 COPY)。 這樣會導致恢復非常緩慢。 這個選項主要用於製作那種可以用於其它非 PostgreSQL 資料庫的轉儲。 請注意,如果您重新排列了字串順序,那麼恢復可能會完全失敗。 -D 更安全,但是也更慢。

-D
--column-inserts
--attribute-inserts

把資料轉儲為帶有明確字串名的 INSERT 命令。 (INSERT INTO table(column, ...) VALUES ...)。 這樣會導致恢復非常緩慢,它主要用於製作那種可以用於其它非 PostgreSQL 資料庫的轉儲。

-f file
--file=file

把輸出發往指定的文件。如果忽略這些,則使用標準輸出。

-F format
--format=format

選擇輸出的格式。format可以是下列之一:

p

輸出純文本SQL腳本文件(預設)

t

輸出適合輸入到 pg_restore 裡的tar歸檔文件。 使用這個歸檔允許在恢復資料庫時重新排序和/或把資料庫對像排除在外。 同時也可能可以在恢復的時候限制對哪些資料進行恢復。

c

輸出適於給 pg_restore 用的客戶化歸檔。 這是最靈活的格式,它允許對裝載的資料和對像定義進行重新排列。 這個格式預設的時候是壓縮的。

-i
--ignore-version

忽略在 pg_dump 和資料庫伺服器之間的版本差別。

pg_dump 可以處理來自以前版本的PostgreSQL 的資料庫,但是太老的版本則不被支援了(目前是支援到 7.0)。 如果您需要跨越版本檢查時才使用這個選項( 而且如 pg_dump 失效,別說我沒警告您)。

-n namespace
--schema=schema

只轉儲 schema 的內容。 如果沒有聲明這個選項,所有目標資料庫中的非系統模式都會被轉儲出來。

注意: 在這個模式裡,pg_dump 並不試圖轉儲任何其它選定模式可能依賴的資料庫對象。 因此,系統不保證單一的一個模式的轉儲就可以成功地恢復到一個乾淨的資料庫中去。

-o
--oids

作為資料的一部分,為每個資料表都輸出對像標識(OID)。 如果您的應用在某種程度上引用了OID字串的話,(比如,在外鍵約束中用到)。 那麼使用這個選項。否則,不應該使用這個選項。

-O
--no-owner

不把對象的所有權設置為對應源資料庫。 通常, pg_dump 發出(psql特有的) ALTER OWNER 或者 SET SESSION AUTHORIZATION 語句以設置建立的資料庫對象的所有權。 又見 -R-X use-set-session-authorization 選項。 請注意 -O 並不防止所有對資料庫的重新連線, 只是防止那些為調整權限進行的排它連線。

這個選項只是對純文本格式有意義。對于歸檔格式,在您調用 pg_restore 的時候您可以聲明該選項。

-R
--no-reconnect

這個選項已經過時,但是出於向下兼容的考慮,仍然接受這個選項。

-s
--schema-only

只輸出對像定義(模式),不輸出資料。

-S username
--superuser=username

聲明關閉觸發器時需要用到的超級用戶名。 它只有使用了 --disable-triggers 的時候才有關係。 (通常,我們最好不要輸入這個參數,而是用超級用戶啟動生成的腳本。)

-t table
--table=table

只輸出資料表 table的資料。 很可能是在不同模式裡面有多個同名資料表;如果這樣,那麼所有匹配的資料表都將被轉儲出來。 同時聲明 --schema--table 則只選擇一個資料表。

注意: 在這個模式裡,pg_dump 並不試圖轉儲任何其它選定資料表可能依賴的資料庫對象。 因此,系統不保證單一的一個資料表的轉儲就可以成功地恢復到一個乾淨的資料庫中去。

-v
--verbose

聲明冗余模式。 這樣將令 pg_dump 輸出詳細的對象評注以及轉儲文件的啟停時間和進度訊息到標準輸出上。

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

避免輸出 ACL(賦予/撤消 命令)和資料表的所有者關係訊息。

-X disable-dollar-quoting
--disable-dollar-quoting

這個選項關閉使用美元符包圍函數體。強制它們用 SQL 標準的字串語法的引號包圍。

-X disable-triggers
--disable-triggers

這個選項只是和建立僅有資料的轉儲相關。它告訴 pg_dump 包含在恢復資料時,臨時關閉目標資料表上面的觸發器的命令。 如果您在資料表上有參考完整性檢查或者其它觸發器,而恢復資料的時候您不想重載他們,那麼您就應該使用這個選項。

目前,為 --disable-triggers 發出的命令必須用超級用戶來做。 因此,您應該同時用 -S 聲明一個超級用戶名,或者最好是用一個超級用戶的身份來啟動這個生成的腳本。

這個選項只對純文本格式有意義。對于歸檔格式,您可以在調用 pg_restore 的時候聲明這個選項。

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

輸出 SQL 標準 SET SESSION AUTHORIZATION 命令而不是 OWNER TO 命令。 這樣的轉儲結果更加復合標準,但是依賴轉儲中的對象的歷史,可能不能正確恢復。

-Z 0..9
--compress=0..9

聲明在那些支援壓縮的格式中使用的壓縮級別。 (目前只有客戶化格式支援壓縮)。

下面的命令行參數控制資料庫為連線參數。

-h host
--host=host

聲明執行伺服器的機器的主機名。 如果數值以斜槓開頭,則它被用做到 Unix 域套接字的路徑。 預設是從 PGHOST 環境變量中取得的,如果設置了這個環境變量的話,否則,嘗試一個 Unix 域套接字連接。

-p port
--port=port

聲明伺服器正在偵聽並等待連線的 TCP 連接埠或本地 Unix 主控套接字文件句柄。 預設時使用環境變量 PGPORT 的值(如果存在),或者是編譯時的預設值。

-U username

以給出用戶身份連線。

-W

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

環境

PGDATABASE
PGHOST
PGPORT
PGUSER

預設連接參數

診斷

pg_dump 在內部使用 SELECT 語句。如果您執行 pg_dump 時碰到問題,確認您能夠使用象 psql 這樣的程序從資料庫選取訊息。

注意

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

CREATE DATABASE foo WITH TEMPLATE template0;

pg_dump 有幾個限制:

tar 歸檔的成員的大小限制於 8 GB。(這個限制是 tar 文件格式的固有限制。) 因此這個格式無法用於任何單資料表的大小超過這個尺寸的原文資料表現。 tar 歸檔和任何其它輸出格式的總大小是不受限制的,只是可能會又操作系統的限制。

pg_dump 生成的轉儲文件並不包含優化器用於查詢規劃決策的統計訊息。 因此,恢復完之後,我們建議在每個已恢復的對象上執行 ANALYZE,以保證好性能。

例子

轉儲一個資料庫:

$ pg_dump mydb > db.out

重載這個資料庫:

$ psql -d database -f db.out

輸出一個叫 mydb 的包含BLOB 的資料庫到一個 tar 文件:

$ pg_dump -Ft -b mydb > db.tar

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

$ pg_restore -d newdb db.tar

歷史

pg_dump 工具最早出現在 Postgres95 版本 0.02。 非純文本輸出格式在 PostgreSQL 版本 7.1 時引入。

又見

pg_dumpall, pg_restore, psql