PostgreSQL pg_restore

2021-09-13 16:30 更新

pg_restore — 從一個由pg_dump創(chuàng)建的歸檔文件恢復一個PostgreSQL數(shù)據(jù)庫

大綱

pg_restore [connection-option...] [option...] [filename]

描述

pg_restore是一個用來從pg_dump創(chuàng)建的非文本格式歸檔恢復PostgreSQL數(shù)據(jù)庫的工具。它將發(fā)出必要的命令把該數(shù)據(jù)庫重建成它被保存時的狀態(tài)。這些歸檔文件還允許 pg_restore選擇恢復哪些內(nèi)容或者在恢復前對恢復項重排序。這些歸檔文件被設(shè)計為可以在不同的架構(gòu)之間遷移。

pg_restore可以在兩種模式下操作。如果指定了一個數(shù)據(jù)庫名稱，pg_restore會連接那個數(shù)據(jù)庫并且把歸檔內(nèi)容直接恢復到該數(shù)據(jù)庫中。否則，會創(chuàng)建一個腳本，其中包含著重建該數(shù)據(jù)庫所必要的 SQL 命令，它會被寫入到一個文件或者標準輸出。這個腳本輸出等效于pg_dump的純文本輸出格式。因此，一些控制輸出的選項與 pg_dump的選項類似。

顯然，pg_restore無法恢復不在歸檔文件中的信息。例如，如果歸檔使用“以INSERT命令轉(zhuǎn)儲數(shù)據(jù)”選項創(chuàng)建， pg_restore將無法使用COPY語句裝載數(shù)據(jù)。

選項

pg_restore接受下列命令行參數(shù)。

filename

指定要被恢復的歸檔文件（對于一個目錄格式的歸檔則是目錄）的位置。如果沒有指定，則使用標準輸入。

-a
--data-only

只恢復數(shù)據(jù)，不恢復模式（數(shù)據(jù)定義）。如果在歸檔中存在，表數(shù)據(jù)、大對象和序列值會被恢復。

這個選項類似于指定--section=data，但是由于歷史原因兩者不完全相同。

-c
--clean

在重新創(chuàng)建數(shù)據(jù)庫對象之前清除（丟棄）它們（除非使用了--if-exists，如果有對象在目標數(shù)據(jù)庫中不存在，這可能會生成一些無害的錯誤消息）。

-C
--create

在恢復一個數(shù)據(jù)庫之前縣創(chuàng)建它。如果還指定了--clean，在連接到目標數(shù)據(jù)庫之前丟棄并且重建它。

如果使用--create，pg_restore還會恢復數(shù)據(jù)庫的注釋（如果有）以及與其相關(guān)的配置變量設(shè)置，也就是任何提到過這個數(shù)據(jù)庫的ALTER DATABASE ... SET ...和ALTER ROLE ... IN DATABASE ... SET ...命令。不管是否指定 --no-acl，數(shù)據(jù)庫本身的訪問特權(quán)都會被恢復。

在使用這個選項時，-d提到的數(shù)據(jù)庫只被用于發(fā)出初始的DROP DATABASE和CREATE DATABASE命令。所有要恢復到該數(shù)據(jù)庫名中的數(shù)據(jù)都出現(xiàn)在歸檔中。

-d dbname
--dbname=dbname

連接到數(shù)據(jù)庫dbname并且直接恢復到該數(shù)據(jù)庫中。dbname 可以是 連接字符串。 如果是這樣，連接字符串參數(shù)將覆蓋任何沖突的命令行選項。

-e
--exit-on-error

在發(fā)送 SQL 命令到該數(shù)據(jù)庫期間如果碰到一個錯誤就退出。默認行為是繼續(xù)并且在恢復結(jié)束時顯示一個錯誤計數(shù)。

-f filename
--file=filename

為生成的腳本指定輸出文件，或在與-l選項一起使用時為列表指定輸出文件。為 stdout用 -。

-F format
--format=format

指定歸檔的格式。并不一定要指定該格式，因為pg_restore將會自動決定格式。如果指定，可以是下列之一：

c
custom

歸檔是pg_dump的自定義格式。

d
directory

歸檔是一個目錄歸檔。

t
tar

歸檔是一個tar歸檔。

-I index
--index=index

只恢復提及的索引的定義。可以通過寫多個-I開關(guān)指定多個索引。

-j number-of-jobs
--jobs=number-of-jobs

使用并發(fā)任務(wù)運行pg_restore中最耗時的步驟 — 載入數(shù)據(jù)、創(chuàng)建索引或者創(chuàng)建約束； 同時，最多使用number-of-jobs個并發(fā)會話。對于一個運行在多處理器機器上的服務(wù)器， 這個選項能夠大幅度減少恢復一個大型數(shù)據(jù)庫的時間。當發(fā)出腳本而不是直接連接到數(shù)據(jù)庫服務(wù)器時，將忽略此選項。

每一個任務(wù)是一個進程或者一個線程，這取決于操作系統(tǒng)，它們都使用一個獨立的服務(wù)器連接。

這個選項的最佳值取決于服務(wù)器、客戶端以及網(wǎng)絡(luò)的硬件設(shè)置。因素包括 CPU 的核心數(shù)和磁盤設(shè)置。一個好的建議是服務(wù)器上 CPU 的核心數(shù)，但是更大的值在很多情況下也能導致更快的恢復時間。當然，過高的值會由于超負荷反而導致性能降低。

這個選項只支持自定義和目錄歸檔格式。輸入必須是一個常規(guī)文件或目錄（例如，不能是一個管道或者標準輸出）。還有，多任務(wù)不能和選項--single-transaction一起用。

-l
--list

列出歸檔的內(nèi)容的表格。這個操作的輸出能被用作-L選項的輸入。注意如果把-n或-t這樣的過濾開關(guān)與-l一起使用，它們將會限制列出的項。

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

只恢復在list-file中列出的歸檔元素，并且按照它們出現(xiàn)在該文件中的順序進行恢復。注意如果把-n或-t這樣的過濾開關(guān)與-L一起使用，它們將會進一步限制要恢復的項。

list-file通常是編輯一個-l操作的輸出來創(chuàng)建。行可以被移動或者移除，并且也可以通過在行首放一個（;）將其注釋掉。例子見下文。

-n shcema
--schema=schema

只恢復在被提及的模式中的對象?？梢杂枚鄠€-n開關(guān)來指定多個模式。這可以與-t選項組合在一起只恢復一個指定的表。

-N schema
--exclude-schema=schema

不恢復所提及方案中的對象?？梢杂枚鄠€-N開關(guān)指定多個要被排除的方案。

如果對同一個方案名稱同時給出了-n和-N，則-N會勝出并且該方案會被排除。

-O
--no-owner

不要輸出將對象的所有權(quán)設(shè)置為與原始數(shù)據(jù)庫匹配的命令。默認情況下，pg_restore會發(fā)出ALTER OWNER或者SET SESSION AUTHORIZATION語句來設(shè)置已創(chuàng)建的模式對象的所有權(quán)。除非到該數(shù)據(jù)庫的初始連接是一個超級用戶（或者擁有腳本中所有對象的同一個用戶）建立的，這些語句將會失敗。通過 -O，任何用戶名都可以被用于初始連接，并且這個用戶將會擁有所有被創(chuàng)建的對象。

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

只恢復被提及的函數(shù)。要小心地拼寫函數(shù)的名稱和參數(shù)使它們正好就是出現(xiàn)在轉(zhuǎn)儲文件的內(nèi)容表中的名稱和參數(shù)?？梢允褂枚鄠€-P開關(guān)指定多個函數(shù)。

-R
--no-reconnect

這個選項已被廢棄，但是出于向后兼容性的目的，系統(tǒng)仍然還接受它。

-s
--schema-only

只恢復歸檔中的模式（數(shù)據(jù)定義）不恢復數(shù)據(jù)。

這個選項是--data-only的逆選項。它與指定--section=pre-data --section=post-data相似，但是由于歷史原因并不完全相同。

（不要把這個選項和--schema選項弄混，后者把詞“schema”用于一種不同的含義）。

-S username
--superuser=username

指定在禁用觸發(fā)器時要用的超級用戶名。只有使用--disable-triggers時這個選項才相關(guān)。

-t table
--table=table

只恢復所提及的表的定義和數(shù)據(jù)。出于這個目的，“table”包括視圖、物化視圖、序列和外部表。可以寫上多個-t開關(guān)可以選擇多個表。這個選項可以和-n選項結(jié)合在一起指定一個特定模式中的表。

注意

在指定-t時，pg_restore不會嘗試恢復所選表可能依賴的任何其他數(shù)據(jù)庫對象。因此，無法確保能成功地把一個特定表恢復到一個干凈的數(shù)據(jù)庫中。

注意

這個標志的行為和pg_dump的-t標志不一樣。在pg_restore中當前沒有任何通配符匹配的規(guī)定，也不能在其-t選項中包括模式的名稱。而且，雖然pg_dump的-t標志也會轉(zhuǎn)儲選中表的附屬對象（例如索引），但是 pg_restore的-t標志不包括這些附屬對象。

注意

在 9.6 版本之前的PostgreSQL 9.6 中，這個標志只匹配表，而并不匹配其他類型的關(guān)系。

-T trigger
--trigger=trigger

只恢復所提及的觸發(fā)器?？梢杂枚鄠€-T開關(guān)指定多個觸發(fā)器。

-v
--verbose

指定冗長模式。

-V
--version

打印該pg_restore的版本并退出。

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

阻止恢復訪問特權(quán)（授予/收回命令）。

-1
--single-transaction

將恢復作為單一事務(wù)執(zhí)行（即把發(fā)出的命令包裹在BEGIN/COMMIT中）。這可以確保要么所有命令完全成功，要么任何改變都不被應(yīng)用。這個選項隱含了--exit-on-error。

--disable-triggers

只有在執(zhí)行一個只恢復數(shù)據(jù)的恢復時，這個選項才相關(guān)。它指示pg_restore在裝載數(shù)據(jù)時執(zhí)行命令臨時禁用目標表上的觸發(fā)器。如果你在表上有參照完整性檢查或者其他觸發(fā)器并且你不希望在數(shù)據(jù)載入期間調(diào)用它們時，請使用這個選項。

目前，為--disable-triggers發(fā)出的命令必須以超級用戶身份完成。因此你還應(yīng)該用-S指定一個超級用戶名，或者更好的方法是以一個PostgreSQL超級用戶運行pg_restore。

--enable-row-security

只有在恢復具有行安全性的表的內(nèi)容時，這個選項才相關(guān)。默認情況下，pg_restore將把row_security設(shè)置為 off 來確保所有數(shù)據(jù)都被恢復到表中。如果用戶不擁有足夠繞過行安全性的特權(quán)，那么會拋出一個錯誤。這個參數(shù)指示pg_restore把 row_security設(shè)置為on允許用戶嘗試恢復啟用了行安全性的表的內(nèi)容。如果用戶沒有從轉(zhuǎn)儲向表中插入行的權(quán)限，這仍將失敗。

注意當前這個選項還要求轉(zhuǎn)儲處于INSERT格式，因為COPY FROM不支持行安全性。

--if-exists

使用條件命令（即增加一個IF EXISTS子句）刪除數(shù)據(jù)庫對象。只有指定了--clean時，這個選項才有效。

--no-comments

即便歸檔中包含注釋也不輸出恢復注釋的命令。

--no-data-for-failed-tables

默認情況下，即便表的創(chuàng)建命令失?。ɡ缫驗楸硪呀?jīng)存在），表數(shù)據(jù)也會被恢復。通過這個選項，對這類表的數(shù)據(jù)會被跳過。如果目標數(shù)據(jù)庫已經(jīng)包含了想要的表內(nèi)容，這種行為又很有有用。例如，PostgreSQL擴展（如PostGIS）的輔助表可能已經(jīng)被載入到目標數(shù)據(jù)庫中，指定這個選項就能阻止把重復的或者廢棄的數(shù)據(jù)載入到這些表中。

只有當直接恢復到一個數(shù)據(jù)庫中時這個選項才有效，在產(chǎn)生 SQL腳本輸出時這個選項不會產(chǎn)生效果。

--no-publications

即便歸檔中包含publication也不輸出恢復publication的命令。

--no-security-labels

不要輸出恢復安全標簽的命令，即使歸檔中包含安全標簽。

--no-subscriptions

即便歸檔中包含subscription也不輸出恢復subscription的命令。

--no-tablespaces

不輸出命令選擇表空間。通過這個選項，所有的對象都會被創(chuàng)建在恢復時的默認表空間中。

--section=sectionname

只恢復提及的小節(jié)。小節(jié)的名稱可以是pre-data、data或者post-data?？梢园堰@個選項指定多次來選擇多個小節(jié)。默認值是恢復所有小節(jié)。

數(shù)據(jù)小節(jié)包含實際的表數(shù)據(jù)以及大對象定義。Post-data 項由索引定義、觸發(fā)器、規(guī)則和除已驗證的檢查約束之外的約束構(gòu)成。Pre-data 項由所有其他數(shù)據(jù)定義項構(gòu)成。

--strict-names

要求每一個模式（-n/--schema）以及表（-t/--table）限定詞匹配備份文件中至少一個模式/表。

--use-set-session-authorization

輸出 SQL 標準的SET SESSION AUTHORIZATION命令取代ALTER OWNER命令來決定對象擁有權(quán)。這會讓轉(zhuǎn)儲更加兼容標準，但是依賴于轉(zhuǎn)儲中對象的歷史，可能無法正確恢復。

-?
--help

顯示有關(guān)pg_restore命令行參數(shù)的幫助，并且退出。

pg_restore也接受下列用于連接參數(shù)的命令行參數(shù)：

-h host
--host=host

指定服務(wù)器正在運行的機器的主機名。如果該值開始于一個斜線，它被用作一個 Unix 域套接字的目錄。默認是從PGHOST環(huán)境變量中取得（如果被設(shè)置），否則將嘗試一次 Unix 域套接字連接。

-p port
--port=port

指定服務(wù)器正在監(jiān)聽連接的 TCP 端口或本地 Unix 域套接字文件擴展名。默認是放在PGPORT環(huán)境變量中（如果被設(shè)置），否則使用編譯在程序中的默認值。

-U username
--username=username

要作為哪個用戶連接。

-w
--no-password

不發(fā)出一個口令提示。如果服務(wù)器要求口令認證并且沒有其他方式提供口令（例如一個.pgpass文件），那么連接嘗試將失敗。這個選項對于批處理任務(wù)和腳本有用，因為在其中沒有一個用戶來輸入口令。

-W
--password

強制pg_restore在連接到一個數(shù)據(jù)庫之前提示要求一個口令。

這個選項不是必須的，因為如果服務(wù)器要求口令認證，pg_restore將自動提示要求一個口令。但是，pg_restore將浪費一次連接嘗試來發(fā)現(xiàn)服務(wù)器想要一個口令。在某些情況下，值得鍵入-W來避免額外的連接嘗試。

--role=rolename

指定一個用來創(chuàng)建該轉(zhuǎn)儲的角色名。這個選項導致pg_restore在連接到數(shù)據(jù)庫后發(fā)出一個SET ROLE rolename命令。當已認證用戶（由-U指定）缺少pg_restore所需的特權(quán)但是能夠切換到一個具有所需權(quán)利的角色時，這個選項很有用。一些安裝有針對直接作為超級用戶登錄的策略，使用這個選項可以讓轉(zhuǎn)儲在不違反該策略的前提下完成。

環(huán)境

PGHOST
PGOPTIONS
PGPORT
PGUSER

默認連接參數(shù)

PG_COLOR

規(guī)定在診斷消息中是否使用顏色?？赡艿闹禐?code class="literal">always、 auto、never。 never.

和大部分其他PostgreSQL工具相似，這個工具也使用libpq（見第 33.14 節(jié)）支持的環(huán)境變量。

診斷

當使用-d選項指定一個直接數(shù)據(jù)庫連接時，pg_restore在內(nèi)部執(zhí)行SELECT語句。如果你運行pg_restore時出現(xiàn)問題，確定你能夠從正在使用的數(shù)據(jù)庫中選擇信息，例如 psql 。此外，libpq前端-后端庫所使用的任何默認連接設(shè)置和環(huán)境變量都將適用。

注解

如果你的數(shù)據(jù)庫集簇對于template1數(shù)據(jù)庫有任何本地添加，要注意將pg_restore的輸出載入到一個真正的空數(shù)據(jù)庫。否則你很可能由于以增加對象的重復定義而得到錯誤。要創(chuàng)建一個不帶任何本地添加的空數(shù)據(jù)庫，從template0而不是template1復制它，例如：

CREATE DATABASE foo WITH TEMPLATE template0;

下面將詳細介紹pg_restore的局限性。

  • 在恢復數(shù)據(jù)到一個已經(jīng)存在的表中并且使用了選項--disable-triggers時，pg_restore會在插入數(shù)據(jù)之前發(fā)出命令禁用用戶表上的觸發(fā)器，然后在完成數(shù)據(jù)插入后重新啟用它們。如果恢復在中途停止，可能會讓系統(tǒng)目錄處于錯誤的狀態(tài)。

  • pg_restore不能有選擇地恢復大對象，例如只恢復特定表的大對象。如果一個歸檔包含大對象，那么所有的大對象都會被恢復，如果通過-L、-t或者其他選項進行了排除，它們一個也不會被恢復。

pg_dump的局限性詳見pg_dump文檔。

一旦完成恢復，應(yīng)該在每一個被恢復的表上運行ANALYZE，這樣優(yōu)化器能得到有用的統(tǒng)計信息。更多信息請見第 24.1.3 節(jié)和第 24.1.6 節(jié)。

示例

假設(shè)我們已經(jīng)以自定義格式轉(zhuǎn)儲了一個叫做mydb的數(shù)據(jù)庫：

$ pg_dump -Fc mydb > db.dump

要刪除該數(shù)據(jù)庫并且從轉(zhuǎn)儲中重新創(chuàng)建它：

$ dropdb mydb
$ pg_restore -C -d postgres db.dump

-d開關(guān)中提到的數(shù)據(jù)庫可以是任何已經(jīng)存在于集簇中的數(shù)據(jù)庫，pg_restore只會用它來為mydb發(fā)出CREATE DATABASE命令。通過-C，數(shù)據(jù)總是會被恢復到出現(xiàn)在歸檔文件的數(shù)據(jù)庫名中。

要把轉(zhuǎn)儲重新載入到一個名為newdb的新數(shù)據(jù)庫中：

$ createdb -T template0 newdb
$ pg_restore -d newdb db.dump

注意我們不使用-C，而是直接連接到要恢復到其中的數(shù)據(jù)庫。還要注意我們是從template0而不是template1創(chuàng)建了該數(shù)據(jù)庫，以保證它最初是空的。

要對數(shù)據(jù)庫項重排序，首先需要轉(zhuǎn)儲歸檔的表內(nèi)容：

$ 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

分號表示開始一段注釋，行首的數(shù)字表明了分配給每個項的內(nèi)部歸檔 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


以上內(nèi)容是否對您有幫助：
在線筆記
App下載
App下載

掃描二維碼

下載編程獅App

公眾號
微信公眾號

編程獅公眾號