PG_DUMP(1)

NAME
pg_dump - 將一個PostgreSQL資料庫抽出到一個指令碼檔案或者其它歸檔檔案中

SYNOPSIS

pg_dump [ option... ] [ dbname ]

DESCRIPTION 描述

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

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

 另外，還有候選的歸檔檔案格式可以和 pg_restore(1) 一起使用重建資料庫， 並且它們也允許 pg_restore(1) 對恢復什麼東西進行選擇， 或者甚至是在恢復之前對需要恢復的條目進行重新排序。 歸檔檔案也是設計成可以跨平臺移植的。

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

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

OPTIONS 選項

 下面的命令列引數用於控制輸出格式。

dbname
     宣告將要轉儲的資料庫名。 如果沒有宣告這個引數，那麼使用環境變數 PGDATABASE。 如果那個環境變數也沒宣告，那麼用發起連線的使用者名稱。

-a

--data-only
     只輸出資料，不輸出結構（表定義）。
     這個選項只是對純文字格式有意義。對於其它格式，你可以在呼叫 pg_restore 的時候宣告選項。

-b

--blobs
     在轉儲中包含大物件。

-c

--clean
     輸出在建立資料庫建立命令之前先清理（刪除）該資料庫物件的命令。
     這個選項只是對純文字格式有意義。對於其它格式，你可以在呼叫 pg_restore 的時候宣告選項。

-C

--create
     以一條建立該資料庫本身並且與這個資料庫聯接等命令開頭進行輸出。 （如果是這種形式的指令碼，那麼你在執行指令碼之前和哪個資料庫聯接就不重要了。）
     這個選項只對純文字格式有意義。對於其它格式，你可以在呼叫 pg_restore 的時候宣告該選項。

-d

--inserts
     將資料輸出為的 INSERT 命令（而不是 COPY）。 這樣會導致恢復非常緩慢。但卻令歸檔更容易移植到其它 SQL 資料庫。

-D

--column-inserts

--attribute-inserts
     把資料轉儲為帶有明確欄位名的 INSERT 命令。 （INSERT INTO table(column, ...) VALUES ...）。 這樣會導致恢復非常緩慢，但是如果你想重新排列欄位的順序，那麼它是必須的。

-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 的內容。 如果沒有宣告這個選項，所有目標資料庫中的非系統模式都會被轉儲出來。

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

-o

--oids
     為每個表都輸出物件標識（OID）。 如果你的應用在某種程度上引用了OID欄位的話，（比如，在外部索引鍵約束中用到）。 那麼使用這個選項。否則，不應該使用這個選項。

-O

--no-owner
     不把物件的所有權設定為對應源資料庫。 By default, pg_dump issues SET SESSION AUTHORIZATION statements to set ownership of created schema elements. These statements will fail when the script is run unless it is started by a superuser (or the same user that owns all of the objects in the script). To make a script that can be restored by any user, but will give that user ownership of all the objects, specify -O.
     這個選項只是對純文字格式有意義。對於其它格式，在你呼叫 pg_restore 的時候你可以宣告該選項。

-R

--no-reconnect
     這個選項已經過時，但是出於向下相容的考慮，仍然接受這個選項。

-s

--schema-only
     只輸出表綱要（定義），不輸出資料。

-S username

--superuser=username
     宣告關閉觸發器時需要用到的超級使用者名稱。 它只有使用了 --disable-triggers 的時候才有關係。 （通常，我們最好不要輸入這個引數，而是用超級使用者啟動生成的指令碼。）

-t table

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

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

-v

--verbose
     宣告冗餘模式。 這樣將令 pg_dump 在標準錯誤上列印進度資訊。

-x

--no-privileges

--no-acl
     避免輸出 ACL（賦予/撤消 命令）和表的所有者關係資訊。

-X use-set-session-authorization

--use-set-session-authorization
     這個選項廢棄了，保留它是為了向下相容。 pg_dump 現在表現得總是想正式選取了這個選項一樣。

-X disable-triggers

--disable-triggers
     這個選項只是和建立僅有資料的轉儲相關。它告訴 pg_dump 包含在恢復資料時，臨時關閉目標表上面的觸發器的命令。 如果你在表上有參考完整性檢查或者其它觸發器，而恢復資料的時候你不想過載他們，那麼你就應該使用這個選項。
     目前，為 --disable-triggers 發出的命令必須用超級使用者來做。 因此，你應該同時用 -S 宣告一個超級使用者名稱，或者最好是用一個超級使用者的身份來啟動這個生成的指令碼。
     這個選項只對純文字格式有意義。對於其它格式，你可以在呼叫 pg_restore 的時候宣告這個選項。

-Z 0..9

--compress=0..9
     宣告在那些支援壓縮的格式中使用的壓縮級別。 （目前只有客戶化格式支援壓縮）。

 下面的命令列引數控制資料庫為聯接引數。

-h host

--host=host
     宣告執行伺服器的機器的主機名。 如果數值以斜扛開頭，則它被用做到 Unix 域套接字的路徑。 預設是從 PGHOST 環境變數中取得的，如果設定了這個環境變數的話，否則，嘗試一個 Unix 域套接字連線。

-p port

--port=port
     宣告伺服器正在偵聽並等待聯接的 TCP 埠或本地 Unix 主控套接字檔案控制代碼。 預設時使用環境變數 PGPORT 的值（如果存在），或者是編譯時的預設值。

-U username
     以給出使用者身分聯接。

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

ENVIRONMENT 環境

PGDATABASE

PGHOST

PGPORT

PGUSER
     預設連線引數

DIAGNOSTICS 診斷

pg_dump 在內部使用 SELECT 語句。如果你執行 pg_dump 時碰到問題，確認你能夠使用象 psql(1) 這樣的程式從資料庫選取資訊。

NOTES 注意

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

CREATE DATABASE foo WITH TEMPLATE template0;

pg_dump 有幾個限制：

•
     在轉儲一個表或者作為純文字轉儲時，pg_dump 無法操作大物件。 大物件必須整資料庫地使用非文字歸檔格式之一進行轉儲。

•
     在進行純資料轉儲時，並且使用了選項 --disable-triggers 的時候，pg_dump 發出一些查詢先關閉在使用者表上面的觸發器， 然後插入資料，資料插入完成後再發出查詢開啟觸發器。 如果恢復動作在中間停止，那麼系統表可能就會處於一種錯誤狀態。

 tar 歸檔的成員的大小限制於 8 GB。（這個限制是 tar 檔案格式的固有限制。） 因此這個格式無法用於那些一個表的大小超過這個尺寸的原文表現。 tar 歸檔和任何其它輸出格式的總大小是不受限制的，只是可能會又作業系統的限制。

 恢復完之後，我們建議在每個已恢復的物件上執行 ANALYZE。 這樣最佳化器就可以得到有用的統計。

EXAMPLES 例子

 轉儲一個數據庫：

$ 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

HISTORY 歷史

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

SEE ALSO 參見
pg_dumpall(1), pg_restore(1), psql(1)

譯者
Postgresql 中文網站 何偉平 <laser@pgsqldb.org>

跋
本頁面中文版由中文 man 手冊頁計劃提供。
中文 man 手冊頁計劃：https://github.com/man-pages-zh/manpages-zh