PostgreSQL自带的命令行工具08- pg_restore

PostgreSQL自带的命令行工具08- pg_restore

基础信息
OS版本：Red Hat Enterprise Linux Server release 7.9 (Maipo)
DB版本：16.2
pg软件目录：/home/pg16/soft
pg数据目录：/home/pg16/data
端口：5777

pg_restore 是 PostgreSQL 中用来恢复由 pg_dump 创建的备份文件的命令行工具。它特别适用于处理 pg_dump 以自定义格式（使用 -Fc 选项）、目录格式或 tar 格式备份的数据库文件。

通过help查看帮助文档。

[pg16@test backup]$ pg_restore --help
pg_restore restores a PostgreSQL database from an archive created by pg_dump.

Usage:
  pg_restore [OPTION]... [FILE]

General options:
  -d, --dbname=NAME        connect to database name
  -f, --file=FILENAME      output file name (- for stdout)
  -F, --format=c|d|t       backup file format (should be automatic)
  -l, --list               print summarized TOC of the archive
  -v, --verbose            verbose mode
  -V, --version            output version information, then exit
  -?, --help               show this help, then exit

Options controlling the restore:
  -a, --data-only              restore only the data, no schema
  -c, --clean                  clean (drop) database objects before recreating
  -C, --create                 create the target database
  -e, --exit-on-error          exit on error, default is to continue
  -I, --index=NAME             restore named index
  -j, --jobs=NUM               use this many parallel jobs to restore
  -L, --use-list=FILENAME      use table of contents from this file for
                               selecting/ordering output
  -n, --schema=NAME            restore only objects in this schema
  -N, --exclude-schema=NAME    do not restore objects in this schema
  -O, --no-owner               skip restoration of object ownership
  -P, --function=NAME(args)    restore named function
  -s, --schema-only            restore only the schema, no data
  -S, --superuser=NAME         superuser user name to use for disabling triggers
  -t, --table=NAME             restore named relation (table, view, etc.)
  -T, --trigger=NAME           restore named trigger
  -x, --no-privileges          skip restoration of access privileges (grant/revoke)
  -1, --single-transaction     restore as a single transaction
  --disable-triggers           disable triggers during data-only restore
  --enable-row-security        enable row security
  --if-exists                  use IF EXISTS when dropping objects
  --no-comments                do not restore comments
  --no-data-for-failed-tables  do not restore data of tables that could not be
                               created
  --no-publications            do not restore publications
  --no-security-labels         do not restore security labels
  --no-subscriptions           do not restore subscriptions
  --no-table-access-method     do not restore table access methods
  --no-tablespaces             do not restore tablespace assignments
  --section=SECTION            restore named section (pre-data, data, or post-data)
  --strict-names               require table and/or schema include patterns to
                               match at least one entity each
  --use-set-session-authorization
                               use SET SESSION AUTHORIZATION commands instead of
                               ALTER OWNER commands to set ownership

Connection options:
  -h, --host=HOSTNAME      database server host or socket directory
  -p, --port=PORT          database server port number
  -U, --username=NAME      connect as specified database user
  -w, --no-password        never prompt for password
  -W, --password           force password prompt (should happen automatically)
  --role=ROLENAME          do SET ROLE before restore

The options -I, -n, -N, -P, -t, -T, and --section can be combined and specified
multiple times to select multiple objects.

If no input file name is supplied, then standard input is used.

Report bugs to <pgsql-bugs@lists.postgresql.org>.
PostgreSQL home page: <https://www.postgresql.org/>

基本用法

pg_restore [选项]... [文件名]

如果备份文件是以纯文本 SQL 格式创建的，那么恢复这样的备份应直接使用 psql 命令，** pg_restore 主要用于处理非纯文本格式的备份**。

主要选项

• -d DBNAME 或 --dbname=DBNAME：直接恢复到指定的数据库。这里 DBNAME 是目标数据库的名称。
• -f FILE 或 --file=FILE：将恢复的 SQL 语句输出到指定的文件，而不是直接恢复到数据库中。
• -l 或 --list：列出备份文件中的内容，而不执行实际恢复。这对于检查备份文件中包含哪些对象非常有用。
• -t TABLE 或 --table=TABLE：只恢复指定的表。这里 TABLE 是要恢复的表的名称。
• -s 或 --schema-only：只恢复对象的架构（结构），不恢复数据。
• -a 或 --data-only：只恢复数据，不恢复对象的架构（结构）。
• -C 或 --create：在恢复数据之前先尝试创建数据库。
• -j NUM 或 --jobs=NUM：使用指定数量的并行作业来恢复。这可以显著提高大型数据库备份的恢复速度。仅适用于目录格式或自定义格式的备份。
• -v 或 --verbose：详细模式，显示更多信息。

示例1

直接恢复到数据库

[pg16@test backup]$ pg_restore --dbname white   /home/pg16/backup/white_20240504.dmp 

这会将 white_20240504.dmp 备份文件恢复到 white 数据库中。

示例2

列出备份文件white_20240504.dmp的内容。

[pg16@test backup]$ pg_restore -l white_20240504.dmp 
;
; Archive created at 2024-05-04 01:59:50 PDT
;     dbname: white
;     TOC Entries: 14
;     Compression: gzip
;     Dump Version: 1.15-0
;     Format: CUSTOM
;     Integer: 4 bytes
;     Offset: 8 bytes
;     Dumped from database version: 16.2
;     Dumped by pg_dump version: 16.2
;
;
; Selected TOC Entries:
;
6; 2615 16405 SCHEMA - yewu1 postgres
7; 2615 16498 SCHEMA - yewu2 postgres
217; 1259 16406 TABLE yewu1 t1 postgres
218; 1259 16409 TABLE yewu1 t2 postgres
219; 1259 16499 TABLE yewu1 t4 postgres
220; 1259 16502 TABLE yewu2 t4 postgres
4065; 0 16406 TABLE DATA yewu1 t1 postgres
4066; 0 16409 TABLE DATA yewu1 t2 postgres
4067; 0 16499 TABLE DATA yewu1 t4 postgres
4068; 0 16502 TABLE DATA yewu2 t4 postgres

这会列出 `white_20240504.dmp` 文件中所有备份对象的明细，而不执行实际恢复动作。

示例3

只恢复备份中的架构

[pg16@test backup]$  pg_restore -d white2 --schema-only /home/pg16/backup/white_20240504.dmp  

--yewu1.t4 中没有数据。
[pg16@test backup]$ psql -p 5777
psql (16.2)
Type "help" for help.

postgres=# \l
                                                       List of databases
   Name    |  Owner   | Encoding | Locale Provider |   Collate   |    Ctype    | ICU Locale | ICU Rules |   Access privileges   
-----------+----------+----------+-----------------+-------------+-------------+------------+-----------+-----------------------
 postgres  | postgres | UTF8     | libc            | en_US.UTF-8 | en_US.UTF-8 |            |           | 
 template0 | postgres | UTF8     | libc            | en_US.UTF-8 | en_US.UTF-8 |            |           | =c/postgres          +
           |          |          |                 |             |             |            |           | postgres=CTc/postgres
 template1 | postgres | UTF8     | libc            | en_US.UTF-8 | en_US.UTF-8 |            |           | =c/postgres          +
           |          |          |                 |             |             |            |           | postgres=CTc/postgres
 white     | postgres | UTF8     | libc            | en_US.UTF-8 | en_US.UTF-8 |            |           | 
 white2    | postgres | UTF8     | libc            | en_US.UTF-8 | en_US.UTF-8 |            |           | 
(5 rows)

postgres=# \c white2 postgres
You are now connected to database "white2" as user "postgres".
white2=# \dn
      List of schemas
  Name  |       Owner       
--------+-------------------
 public | pg_database_owner
 yewu1  | postgres
 yewu2  | postgres
(3 rows)

white2=# select * from yewu1.t4;
 id 
----
(0 rows)

white2=# 

这命令恢复 white_20240504.dmp 中的表结构等架构信息，但不包含数据。

示例4

使用多个并行作业来加速恢复过程

[pg16@test backup]$ pg_restore -d white3 -j 4 /home/pg16/backup/white_20240504.dmp 

这会启用 4 个并行作业来恢复 `white_20240504.dmp` 到 `white3` 数据库，加快恢复速度。（需要注意的是，这可能增加数据库的负载）

注意事项

• 在执行 pg_restore 命令之前，请确保有足够的权限，如超级用户权限，尤其是在执行创建数据库或安装扩展等操作时。
• 使用 -C 选项时，pg_restore 只尝试创建数据库，但不会设置连接参数（如主机名和端口），你需要确保已经正确配置。
• 恢复过程中可能会因为依赖关系等原因遇到错误。在某些情况下，可能需要多次运行 pg_restore 或手动解决这些问题。

pg_restore 是一个强大的工具，可以帮助你从各种格式的 PostgreSQL 备份中恢复数据，特别是当备份文件大或者需要精确控制恢复过程时。

谨记：心存敬畏，行有所止。