vb_restore
背景信息
vb_restore是Vastbase提供的针对vb_dump导出数据的导入工具。通过此工具可导入由vb_dump生成的自定义归档格式（c）、目录格式（d）、tar格式（t）的备份文件。
vb_restore的主要功能包含：
导入到数据库
如果连接参数中指定了数据库，则数据将被导入到指定的数据库中。其中，并行导入必须指定连接的密码。导入时生成列会自动更新，并像普通列一样保存。
导入到脚本文件
如果未指定导入数据库，则必须指定list选项。将会创建包含重建数据库所必须的SQL语句脚本并写入到文件或者标准输出。等效于直接使用vb_dump导出为纯文本格式。多用于TOC文件选择性恢复。
注意事项
- vb_restore工具由安装Vastbase数据库的操作系统用户执行。
- 一旦恢复，最好在每个数据库上运行ANALYZE，优化程序提供有用的统计数据。
如果安装过程中有任何本地数据要添加到template1数据库，请谨慎将vb_restore的输出载入到一个真正的空数据库中；否则可能会因为被添加对象的定义被复制，而出现错误。要创建一个无本地添加的空数据库，需从template0而非template1复制，例如：
CREATE DATABASE foo WITH TEMPLATE template0;vb_restore不能选择性地导入大对象；例如只能导入那些指定表的对象。如果某个归档形式包含大对象，那所有大对象都会被导入或一个都不会被导入。如果此归档对象通过-L、-t或其他选项被排除，那么所有大对象一个都不会被导入。
vb_restore默认是以追加的方式进行数据导入。为避免多次导入造成数据异常，在进行导入时，建议使用“-c”参数，在重新创建数据库对象前，清理（删除）已存在于将要还原的数据库中的数据库对象。
日志打印无开关，若需隐藏日志，请将日志重定向到日志文件。若恢复表数据时，数据量很大，会分批恢复，因此会多次出现“表数据已完成导入”的日志。
命令格式
vb_restore [OPTION]... FILE
- FILE没有短选项或长选项。用来指定归档文件所处的位置。
- 作为前提条件，需输入dbname或-l选项。不允许用户同时输入dbname和-l选项。
通用参数：
General options:
-d, --dbname=NAME connect to database name
-f, --file=FILENAME output file name
-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(s)
-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(s)
-O, --no-owner skip restoration of object ownership
-P, --function=NAME(args) restore named function(s)
-s, --schema-only restore only the schema, no data
-S, --sysadmin=NAME system admin user name to use for disabling triggers
-t, --table=NAME restore named table(s)
-T, --trigger=NAME restore named trigger(s)
-x, --no-privileges/--no-acl skip restoration of access privileges (grant/revoke)
-1, --single-transaction restore as a single transaction
--disable-triggers disable triggers during data-only restore
--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-tablespaces do not restore tablespace assignments
--section=SECTION restore named section (pre-data, data, or post-data)
--use-set-session-authorization use SET SESSION AUTHORIZATION commands instead of
ALTER OWNER commands to set ownership
--pipeline use pipeline to pass the password,
forbidden to use in terminal
--with-decryption=AES128/SM4 restore data is decrypted using AES128 or SM4 in hardware encryption mode
--with-key=KEY hardware encryption device internal key index
--with-salt=RANDVALUES random values for decrypt
连接参数：
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=PASSWORD the password of specified database user
--role=ROLENAME do SET ROLE before restore
--rolepassword=ROLEPASSWORD the password for role
参数说明
通用参数
-d, --dbname=NAME
连接数据库dbname并直接导入到该数据库中。
-f, --file=FILENAME
指定生成脚本的输出文件，或使用-l时列表的输出文件。
默认是标准输出。
-d/--dbname和-f/--file 不能同时使用。
-F, --format=c|d|t
指定归档格式。由于vb_restore会自动决定格式，因此不需要指定格式。
取值范围：
c/custom：该归档形式为vb_dump的自定义格式。
d/directory：该归档形式是一个目录归档形式。
t/tar：该归档形式是一个tar归档形式。
-l, --list
列出归档形式内容。这一操作的输出可用作-L选项的输入。注意如果像-n或-t的过滤选项与-l使用，过滤选项将会限制列举的项目（即归档形式内容）。
-v, --verbose
开启冗长模式，打印详细信息。
-V, --version
打印vb_restore版本，然后退出。
-?, --help
显示vb_restore命令行参数帮助，然后退出。
恢复控制参数
-a, --data-only
只导入数据，不导入模式（数据定义）。vb_restore的导入是以追加方式进行的。
-s/--schema-only 和 -a/--data-only不能同时使用。
-c, --clean
在重新创建数据库对象前，清理（删除）已存在于将要还原的数据库中的数据库对象。
-c/--clean 和 -a/--data-only不能同时使用。
-C, --create
导入数据库之前会先使用CREATE DATABASE创建数据库。（指定该选项后，-d指定的数据库仅用以执行CREATE DATABASE命令，所有数据依然会导入到创建的数据库中。）
-e, --exit-on-error
当发送SQL语句到数据库时如果出现错误，请退出。默认状态下会继续，且在导入后会显示一系列错误信息。
-I, --index=NAME
只导入已列举的index的定义。允许导入多个index。如果多次输入-I index导入多个index。
例如：
vb_restore -h host_name -p port_number -d postgres -I Index1 -I Index2 backup/MPPDB_backup.tar在上面这个例子中，Index1和Index2会被导入。
-j, --jobs=NUM
运行vb_restore最耗时的部分（如加载数据、创建index或创建约束）使用并发任务。该选项能大幅缩短导入时间，即将一个大型数据库导入到某一多处理器的服务器上。
- 使用--single-transaction时，-j/--jobs必须为单任务。
- 每个任务可能是一个进程或一个线程，这由操作系统决定。每个任务与服务器进行单独连接。
- 该选项的最优值取决于服务器的硬件设置、客户端以及网络。还包括这些因素，如CPU核数量、硬盘设置。建议是从增加服务器上的CPU核数量入手，更大的值（服务器上CPU核数量）在很多情况下也能导致数据文件更快的被导入。当然，过高的值会由于超负荷反而导致性能降低。
- 该选项只支持自定义归档格式（c）和目录格式（d）。输入文件必须是常规文件（不能是像pipe的文件）。如果是通过脚本文件，而非直接连接数据库服务器，该选项可忽略。而且，多任务不能与--single-transaction选项一起使用。
-L, --use-list=FILENAME
只导入列举在list-file中的那些归档形式元素，导入顺序以它们在文件中的顺序为准。注意如果像-n或-t的过滤选项与-L使用，它们将会进一步限制导入的项目。一般情况下，list-file是通过编辑前面提到的某个-l参数的输出创建的。文件行的位置可更改或直接删除，也可使用分号（;）在行的开始注出。
-n, --schema=NAME
只导入已列举的模式中的对象。该选项可与-t选项一起用以导入某个指定的表。多次输入
-n _schemaname_可以导入多个模式。例如：
vb_restore -h host_name -p port_number -d postgres -n sch1 -n sch2 backup/MPPDB_backup.tar在上面这个例子中，sch1和sch2会被导入。
-O, --no-owner
不输出设置对象的归属这样的命令，以匹配原始数据库。默认情况下，vb_restore会发出ALTER OWNER或SET SESSION AUTHORIZATION语句设置所创建的模式元素的所属。除非是由系统管理员（或是拥有脚本中所有对象的同一个用户）进行数据库首次连接的操作，否则语句会失败。使用-O选项，任何用户名都可用于首次连接，且该用户拥有所有已创建的对象。
-P, --function=NAME(args)
只导入已列举的函数。请按照函数所在转储文件中的目录，准确拼写函数名称和参数。当-P单独使用时，表示导入文件中所有'function-name(args)'函数；当-P同-n一起使用时，表示导入指定模式下的'function-name(args)'函数；多次输入-P，而仅指定一次-n，表示所有导入的函数默认都是位于-n模式下的。可以多次输入
-n schema-name -P 'function-name(args)'同时导入多个指定模式下的函数。例如：
vb_restore -h host_name -p port_number -d postgres -n test1 -P 'Func1(integer)' -n test2 -P 'Func2(integer)' backup/MPPDB_backup.tar在上面这个例子中，test1模式下的函数Func1(i integer)和test2模式下的函数Func2(j integer)会被一起导入。
-s, --schema-only
只导入模式（数据定义），不导入数据（表内容）。当前的序列值也不会导入。
-s/--schema-only 和 -a/--data-only不能同时使用。
若在使用vb_dump导出时指定了只导出模式（即指定了-s参数），则导入时必须指定本参数。
-S, --sysadmin=NAME
该参数为扩展预留接口，不建议使用。
-t, --table=NAME
只导入已列举的表定义、数据或定义和数据。该选项与-n选项同时使用时，用来指定某个模式下的表对象。-n参数不输入时，默认为PUBLIC模式。多次输入
-n <schemaname> -t <tablename>可以导入指定模式下的多个表。例如：
导入PUBLIC模式下的table1：
vb_restore -h host_name -p port_number -d postgres -t table1 backup/MPPDB_backup.tar导入test1模式下的test1和test2模式下test2：
vb_restore -h host_name -p port_number -d postgres -n test1 -t test1 -n test2 -t test2 backup/MPPDB_backup.tar导入PUBLIC模式下的table1和test1 模式下test1：
vb_restore -h host_name -p port_number -d postgres -n PUBLIC -t table1 -n test1 -t table1 backup/MPPDB_backup.tar-t不支持schema_name.table_name，指定此格式不会报错，但不会生效。
-T, --trigger=NAME
该参数为扩展预留接口。
-x, --no-privileges/--no-acl
防止导入访问权限（GRANT/REVOKE命令）。
-1, --single-transaction
执行导入作为一个单独事务（即把命令包围在BEGIN/COMMIT中）。该选项确保要么所有命令成功完成，要么没有改变应用。该选项意为--exit-on-error。
使用--single-transaction时，-j/--jobs必须为单任务。
--disable-triggers
该参数为扩展预留接口，不建议使用。
--no-data-for-failed-tables
默认状态下，即使创建表的命令失败（如表已经存在），表数据仍会被导入。使用该选项，像这种表的数据会被跳过。如果目标数据库已包含想要的表内容，这种行为会有帮助。该选项只有在直接导入到某数据库中时有效，不针对生成SQL脚本文件输出。
--no-publications
不导入发布。
--no-security-labels
该参数为扩展预留接口，不建议使用。
--no-subscriptions
不导入订阅。
--no-tablespaces
不输出选择表空间的命令。使用该选项，无论默认表空间是哪个，在导入过程中所有对象都会被创建。
--section=SECTION
导入已列举的区段（如pre-data、data或post-data）。
--use-set-session-authorization
该选项用来进行文本格式的备份。
输出SET SESSION AUTHORIZATION命令，而非ALTER OWNER命令，用以决定对象归属。该选项使转储更加兼容标准，但通过参考转储中对象的记录，导入过程可能会有问题。使用SET SESSION AUTHORIZATION的转储要求必须是系统管理员，同时在导入前还需参考“SET SESSION AUTHORIZATION”，手工对导出文件的密码进行修改验证，只有这样才能进行正确的导入操作，相比之下，ALTER OWNER对权限要求较低。
--pipeline
使用管道传输密码，禁止在终端使用。
--with-decryption=AES128/SM4
还原数据时采用AES128或SM4硬件加密方式解密。
若导出时使用
--with-encryption指定了加密方式，则恢复时需要指定此参数并采用同样的方式进行解密。- 该选项必须与
--with-key和--with-salt同时使用。 - 该选项仅在V2.2 Build 10(Patch NO.12)及以后补丁版本支持。
- 该选项必须与
--with-key=KEY
硬件加密设备内部的密钥索引。
该选项仅在V2.2 Build 10(Patch NO.12)及以后补丁版本支持。
--with-salt=RANDVALUES
用于解密的随机盐值。
- 必须为16个字符的字符串。
- 恢复时指定的盐值必须与加密导出时指定的盐值相同。
该选项仅在V2.2 Build 10(Patch NO.12)及以后补丁版本支持。
连接参数
-h, --host=HOSTNAME
指定的主机名称。如果取值是以斜线开头，将用作Unix域套接字的目录。默认值取自PGHOST环境变量；如果没有设置，将启动某个Unix域套接字建立连接。该参数只针对Vastbase外，对Vastbase内本机只能用127.0.0.1。
环境变量：PGHOST
-p, --port=PORT
指定服务器所侦听的TCP端口或本地Unix域套接字后缀，以确保连接。默认值设置为PGPORT环境变量。在开启线程池情况下，建议使用 pooler port，即侦听端口+1。
环境变量：PGPORT
-U, --username=NAME
所连接的用户名。
环境变量：PGUESR
-w, --no-password
不出现输入密码提示。如果服务器要求密码认证并且密码没有通过其它形式给出，则连接尝试将会失败。 该选项在批量工作和不存在用户输入密码的脚本中很有帮助。
-W, --password=PASSWORD
指定用户连接的密码。如果主机的认证策略是trust，则不会对系统管理员进行密码验证，即无需输入-W参数；如果没有-W参数，并且不是系统管理员，vb_restore会提示用户输入密码。
--role=ROLENAME
指定导入操作使用的角色名。选择该参数，会使vb_restore连接数据库后，发起一个SET ROLE角色名命令。当所授权用户（由-U指定）没有vb_restore要求的权限时，该参数会起到作用，即切换到具备相应权限的角色。某些安装操作规定不允许直接以初始用户身份登录，而使用该参数能够在不违反该规定的情况下完成导入。
--rolepassword=ROLEPASSWORD
指定具体角色用户的角色密码。
--role 和--rolepassword必须一起使用。
TOC文件选择性恢复
功能描述
使用vb_restore还原除了纯文本格式以外的备份时，可以通过生成并编辑TOC控制文件，将文件内的行注释、删除或重新排列，达到定制还原效果的目的。
注意事项
用户可以在生成控制文件后，以行前加分号“;”的方式注释掉不用还原的内容。
控制文件内，每行开头的数字代表赋给每个项目的内部归档 ID。
语法格式
生成控制文件的语句如下：
vb_restore -l -f test.toc backup.dmp
或者：
vb_restore -l backup.dmp > test.sql
上述语句中：
test.toc、test.sql是生成的控制文件的名称（包括路径）。
backup.dmp是通过vb_dump导出得到的备份文件名称（包括路径），备份文件也可以是tar格式或者目录格式。
TOC控制文件的使用请参考本文示例5。
示例
示例中“Bigdata@123”表示数据库用户密码。
“5432”表示数据库服务器端口。
示例中待恢复的备份文件均来自vb_dump的示例。
示例1： 恢复vb_dump示例4中的备份文件backup4_1.dmp。恢复时指定-C，代表自动创建数据库test4。
1、使用vsql工具连接至数据库vastbase。
vsql -d vastbase -p 5432 -r
2、删除名为test4的数据库（如果存在）。
请注意当前操作对业务的影响，谨慎操作。
若预先已存在名为test4的数据库，再次导入时会导致数据重复。
drop database if exists test4;
3、退出vsql程序。
\q
4、执行导入操作。
vb_restore -d vastbase -C backup4_1.dmp
5、完成导入操作后，使用vsql工具连接至test4数据库。
vsql -d test4 -p 5432 -r
6、使用如下语句查看导入结果。
select * from table1;
select * from table2;
select * from table3;
返回结果如下，表示已成功导入test4库，数据库中的每张表都有且仅有一条数据。
name | id
-------+----
alice | 1
(1 row)
name | id
------+----
jack | 2
(1 row)
name | id
------+----
bob | 3
(1 row)
示例2： 在本文示例1的基础上，再次执行恢复语句导入backup4_1.dmp。在执行时指定-c，表示恢复数据前先删除对象，恢复操作不会导致数据重复。
1、执行导入语句。
vb_restore -d testdb1 backup4_1.dmp -c
2、完成导入操作后，使用vsql工具连接至test4数据库。
vsql -d test4 -p 5432 -r
3、使用如下语句查看导入结果。
select * from table1;
select * from table2;
select * from table3;
返回结果如下，表示已成功导入test4库，数据库中的每张表都有且仅有一条数据。
name | id
-------+----
alice | 1
(1 row)
name | id
------+----
jack | 2
(1 row)
name | id
------+----
bob | 3
(1 row)
示例3： 创建一个新数据库并恢复vb_dump示例4的备份文件backup4_4.tar。
1、使用vsql工具连接至数据库vastbase。
vsql -d vastbase -p 5432 -r
2、创建用于恢复的数据库testdb3。
create database testdb3;
3、退出vsql程序。
\q
4、执行恢复语句。
vb_restore -d testdb3 backup4_4.tar
5、完成恢复后，使用vsql工具连接至数据库testdb3。
vsql -d testdb3 -p 5432 -r
6、查看当前数据库中的表信息。
\d
返回结果如下，testdb3数据库下仅包含table1、table2，与备份时的内容一致。
List of relations
Schema | Name | Type | Owner | Storage
--------+---------------+-------+----------+------------------------------------------------
public | table1 | table | vastbase | {orientation=row,compression=no,fillfactor=80}
public | table2 | table | vastbase | {orientation=row,compression=no,fillfactor=80}
public | vb_login_info | view | vastbase |
(3 rows)
7、查看table1和table2的表数据。
select * from table1;
select * from table2;
返回结果如下，两张表都有且仅有一条数据。
name | id
-------+----
alice | 1
(1 row)
name | id
------+----
jack | 2
(1 row)
示例4： 在一个新数据库内恢复vb_dump示例4的备份文件backup4_1.dmp。在恢复时指定-s，代表仅恢复定义。
1、使用vsql工具连接至数据库vastbase。
vsql -d vastbase -p 5432 -r
2、创建用于恢复的数据库testdb4。
create database testdb4;
3、退出vsql程序。
\q
4、执行恢复语句。
vb_restore -d testdb4 backup4_1.dmp -s
5、恢复成功后，使用vsql工具连接至数据库testdb4。
vsql -d testdb4 -p 5432 -r
6、使用如下语句查看恢复情况。
select * from table1;
select * from table2;
select * from table3;
返回结果如下，表示已成功将table1、table2、table3导入到数据库testdb4中，只包括定义，不包括数据。
name | id
------+----
(0 rows)
name | id
------+----
(0 rows)
name | id
------+----
(0 rows)
示例5： 在一个新数据库内恢复vb_dump示例4的备份文件backup4_1.dmp，并通过TOC控制文件排除表table2。
1、使用vsql工具连接至数据库vastbase。
vsql -d vastbase -p 5432 -r
2、创建用于恢复的数据库testdb5。
create database testdb5;
3、退出vsql程序。
\q
4、为备份文件backup4_1生成相应的TOC控制文件。
vb_restore -l -f test.toc backup4_1.dmp
5、查看TOC文件的内容。
vi test.toc
在包含table2信息的第17和22行首加上分号“;”注释掉内容，修改后的示例如下。修改后保存退出。
;
; Archive created at Thu Apr 20 16:45:52 2023
; dbname: test4
; TOC Entries: 10
; Compression: -1
; Dump Version: 1.12-0
; Format: CUSTOM
; Integer: 4 bytes
; Offset: 8 bytes
; Dumped from database version: 9.2.4
; Dumped by gs_dump version: 9.2.4
;
;
; Selected TOC Entries:
;
720; 1259 16619 TABLE public table1 vastbase
;721; 1259 16625 TABLE public table2 vastbase
722; 1259 16631 TABLE public table3 vastbase
447; 1259 13336 VIEW public vb_login_info vastbase
5527; 0 0 ACL public vb_login_info vastbase
5519; 0 16619 TABLE DATA public table1 vastbase
;5520; 0 16625 TABLE DATA public table2 vastbase
5521; 0 16631 TABLE DATA public table3 vastbase
6、使用TOC控制文件完成恢复。
vb_restore -Fc -C -L test.toc -d testdb5 backup4_1.dmp
7、完成恢复后，使用vsql工具连接至数据库testdb5。
vsql -d vastbase -p 5432 -r
8、查看当前数据库的表信息。
\d
返回结果如下，表示成功导入了table1和table3。
List of relations
Schema | Name | Type | Owner | Storage
--------+---------------+-------+----------+------------------------------------------------
public | table1 | table | vastbase | {orientation=row,compression=no,fillfactor=80}
public | table3 | table | vastbase | {orientation=row,compression=no,fillfactor=80}
public | vb_login_info | view | vastbase |
(3 rows)
9、查看table1和table3的数据。
select * from table1;
select * from table3;
返回结果如下：
name | id
------+----
alice | 1
(1 row)
name | id
------+----
bob | 3
(1 row)
