gs_restore
背景信息
gs_restore是GaussDB提供的针对gs_dump导出数据的导入工具。通过此工具可将gs_dump导出生成的文件进行导入。
主要功能包含：
gs_restore支持SSL加密通信，使用方式同gsql方式。
使用gs_restore前请确保gs_restore版本与gs_dump版本、数据库版本保持一致。
命令格式
gs_restore [OPTION]... FILE
- FILE没有短选项或长选项。用来指定归档文件所处的位置。
- 作为前提条件，需输入dbname或-l选项。不允许用户同时输入dbname和-l选项。
- gs_restore默认是以追加的方式进行数据导入。为避免多次导入造成数据异常，在进行导入时，建议选择使用“-c”和“-e”参数。“-c”表示在重新创建数据库对象前，清理（删除）已存在于将要还原的数据库中的数据库对象；“-e”表示当发送SQL语句到数据库时如果出现错误请退出，默认状态下会继续，且在导入后会显示一系列错误信息。
- 在进行导入时，如果schema对象的owner拥有OPRADMIN的系统权限，那么在导入时需要使用初始用户。
- 在进行导入时，如果数据中存在非法编码的数据并且不需要进行转码，可以配置数据库兼容性参数copy_special_character_version为'no_error'将非法编码的数据进行导入，否则会报错，但不会中断导入。
参数说明
通用参数：
- -d, --dbname=NAME
- -f, --file=FILENAME
默认是标准输出。
-f不能同-d一起使用。
- -F, --format=c|d|t
指定归档格式。由于gs_restore会自动决定格式，因此不需要指定格式。
取值范围：
- c/custom：该归档形式为gs_dump的自定义格式。
- d/directory：该归档形式是一个目录归档形式。
- t/tar：该归档形式是一个tar归档形式。
- -l, --list
列出归档形式内容。这一操作的输出可用作-L选项的输入。注意如果像-n或-t的过滤选项与-l使用，过滤选项将会限制列举的项目（即归档形式内容）。
- -v, --verbose
- -V, --version
- -?, --help
导入参数：
- -a, -data-only
- -c, --clean
在重新创建数据库对象前，清理（删除）已存在于将要还原的数据库中的数据库对象。如果目标数据库中没有删除操作涉及的对象，可能会输出一些提示性的错误信息。
- -C, --create
导入数据库之前会先使用CREATE DATABASE创建数据库（指定该选项后，-d指定的数据库仅用于执行CREATE DATABASE命令，所有数据依然会导入到创建的数据库中）。
在M-Compatibility模式数据库下，不支持使用该选项。必须先在目标实例上创建M-Compatibility模式数据库，然后在源实例上导出，最后在目标实例连接新创建的M-Compatibility模式数据库导入。
- -e, --exit-on-error
- -I, --index=NAME
只导入已列举的index的定义。允许导入多个index。如果多次输入-I index导入多个index。
例如：
gs_restore -h host_name -p port_number -d testdb -I Index1 -I Index2 backup/MPPDB_backup.tar
在上面这个例子中，Index1和Index2会被导入。
- -j, --jobs=NUM
运行gs_restore最耗时的部分（如加载数据、创建index、或创建约束）使用并发任务。该选项能大幅缩短导入时间，即将一个大型数据库导入到某一多处理器的服务器上。
每个任务可能是一个进程或一个线程，这由操作系统决定。每个任务与服务器进行单独连接。
该选项的最优值取决于服务器的硬件设置、客户端、以及网络。还包括这些因素，如CPU核数量、硬盘设置。建议是从增加服务器上的CPU核数量入手，更大的值（服务器上CPU核数量）在很多情况下也能导致数据文件更快地被导入。相应地，过高的值会由于超负荷反而导致性能降低。
该选项只支持自定义归档格式。输入文件必须是常规文件（不能是像pipe的文件）。如果是通过脚本文件，而非直接连接数据库服务器，该选项可忽略。而且，多任务不能与--single-transaction选项一起使用。
此参数适用于多表/多索引/多约束的情况。实际使用过程中，创建的进程数（或线程数）与表、索引、约束等的数量有关，最高并发不会超过给定的jobs数。
- -L, --use-list=FILENAME
只导入列举在list-file中的那些归档形式元素，导入顺序以它们在文件中的顺序为准。注意如果像-n或-t的过滤选项与-L使用，它们将会进一步限制导入的项目。
一般情况下，list-file是通过编辑前面提到的某个-l参数的输出创建的。文件行的位置可更改或直接删除行，也可使用分号（;）在行的开始注出。见下文的举例。
- -n, --schema=NAME
该选项可与-t选项一起用以导入某个指定的表。
多次输入-n schemaname可以导入多个模式。
例如：
gs_restore -h host_name -p port_number -d testdb -n sch1 -n sch2 backup/MPPDB_backup.tar
在上面这个例子中，sch1和sch2会被导入。
- 与gs_dump不同，在gs_restore中该参数为全匹配，当模式名称中包含大写字母时，不需要添加额外的引号，如：-n "Sch1"
- M-Compatibility兼容模式下，该参数值受GUC参数lower_case_table_names影响。比如在大小写敏感模式下（lower_case_table_names=0），该参数值也需要大小写敏感，如果包含大写字母，不需要添加额外的引号。在大小写不敏感模式下（lower_case_table_names=1），该参数值需要传小写名称。
- -O, --no-owner
不输出设置对象的归属这样的命令，以匹配原始数据库。默认情况下，gs_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)'同时导入多个指定模式下的函数。
例如：
./gs_restore -h host_name -p port_number -d testdb -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, --sysadmin=NAME
- -t, --table=NAME
只导入已列举的表定义、数据或定义和数据。该选项与-n选项同时使用时，用来指定某个模式下的表对象。-n参数不输入时，默认为PUBLIC模式。多次输入-n <schemaname> -t <tablename>可以导入指定模式下的多个表。
例如：
导入PUBLIC模式下的table1
gs_restore -h host_name -p port_number -d testdb -t table1 backup/MPPDB_backup.tar
导入test1模式下的test1和test2模式下test2
gs_restore -h host_name -p port_number -d testdb -n test1 -t test1 -n test2 -t test2 backup/MPPDB_backup.tar
导入PUBLIC模式下的table1和test1 模式下test1
gs_restore -h host_name -p port_number -d testdb -n PUBLIC -t table1 -n test1 -t table1 backup/MPPDB_backup.tar
- -t不支持schema_name.table_name的输入格式，指定此格式不会报错，但不会生效。
- 当-t已指定时，gs_restore不会导入已选表所附着的任何其他数据库对象。因此，无法保证某个指定表的转储结果能够自行成功地导入到一个空数据库中。
- -t tablename不会导入表上的触发器信息。
- 与gs_dump不同，在gs_restore中该参数为全匹配，当表名称中包含大写字母时，不需要添加额外的引号，如：-t "Tbl1"
- M-Compatibility兼容模式下，该参数值受GUC参数lower_case_table_names影响。比如在大小写敏感模式下（lower_case_table_names=0），该参数值也需要大小写敏感，如果包含大写字母，不需要添加额外的引号。在大小写不敏感模式下（lower_case_table_names=1），该参数值需要传小写名称。
- -T, --trigger=NAME
- -x, --no-privileges/--no-acl
- -1, --single-transaction
执行导入作为一个单独事务（即把命令包围在BEGIN/COMMIT中）。
该选项确保要么所有命令成功完成，要么没有改变应用。该选项意为--exit-on-error。
- --disable-triggers
- --no-data-for-failed-tables
默认状态下，即使创建表的命令失败（如表已经存在），表数据仍会被导入。使用该选项，像这种表的数据会被跳过。如果目标数据库已包含想要的表内容，这种行为会有帮助。
该选项只有在直接导入到某数据库中时有效，不针对生成SQL脚本文件输出。
- --no-security-labels
- --no-tablespaces
- --section=SECTION
- --use-set-session-authorization
输出SET SESSION AUTHORIZATION命令，而非ALTER OWNER命令，用以决定对象归属。该选项使转储更加兼容标准，但通过参考转储中对象的记录，导入过程可能会有问题。使用SET SESSION AUTHORIZATION的转储要求必须是系统管理员，同时在导入前还需参考"SET SESSION AUTHORIZATION"，手工对导出文件的密码进行修改验证，只有这样才能进行正确的导入操作，相比之下，ALTER OWNER对权限要求较低。
- --pipeline
- 如果安装过程中有任何本地数据要添加到template1数据库，请谨慎将gs_restore的输出载入到一个真正的空数据库中；否则可能会因为被添加对象的定义被复制，而出现错误。要创建一个无本地添加的空数据库，需从template0而非template1复制，例如：
CREATE DATABASE foo WITH TEMPLATE template0;
- gs_restore不能选择性地导入大对象；例如只能导入那些指定表的对象。如果某个归档形式包含大对象，那所有大对象都会被导入。如果此归档对象通过-L、-t或其他选项被排除，那么所有大对象一个都不会被导入。
1.-d/--dbname 和 -f/--file 不能同时使用。
2. -s/--schema-only 和 -a/--data-only不能同时使用。
3. -c/--clean 和 -a/--data-only不能同时使用。
4. 使用--single-transaction时，-j/--jobs必须为单任务。
5. --role 和 --rolepassword必须一起使用。
连接参数：
- -h, --host=HOSTNAME
指定的主机名称。如果取值是以斜线开头，他将用作Unix域套接字的目录。默认值取自PGHOST环境变量；如果没有设置，将启动某个Unix域套接字建立连接。
该参数只针对集群外，对集群内本机IPv4用127.0.0.1，IPv6用::1。
环境变量：PGHOST
- -p, --port=PORT
指定服务器所侦听的TCP端口或本地Unix域套接字后缀，以确保连接。默认值设置为PGPORT环境变量。
在开启线程池情况下，建议使用 pooler port，即侦听端口+1。
环境变量：PGPORT
- -U, --username=NAME
环境变量：PGUSER
- -w, --no-password
不出现输入密码提示。如果服务器要求密码认证并且密码没有通过其它形式给出，则连接尝试将会失败。 该选项在批量工作和不存在用户输入密码的脚本中很有帮助。
- -W, --password=PASSWORD
指定用户连接的密码。如果主机的认证策略是trust，则不会对系统管理员进行密码验证，即无需输入-W参数；如果不加此参数，并且不是系统管理员，则会提示交互式输入，为了系统安全，推荐使用交互式输入密码方式。
- --role=ROLENAME
指定导入操作使用的角色名。选择该参数，会使gs_restore连接数据库后，发起一个SET ROLE角色名命令。当所授权用户（由-U指定）没有gs_restore要求的权限时，该参数会起到作用，即切换到具备相应权限的角色。某些安装操作规定不允许直接以初始用户身份登录，而使用该参数能够在不违反该规定的情况下完成导入。
- --rolepassword=ROLEPASSWORD
示例
特例：执行gsql程序，使用如下选项导入由gs_dump/gs_dumpall生成导出文件夹（纯文本格式）的MPPDB_backup.sql文件到testdb数据库。
gsql -d testdb -p 8000 -f /home/omm/test/MPPDB_backup.sql SET SET SET SET SET ALTER TABLE ALTER TABLE ALTER TABLE ALTER TABLE ALTER TABLE CREATE INDEX CREATE INDEX CREATE INDEX SET CREATE INDEX REVOKE REVOKE GRANT GRANT total time: 30476 ms 示例中“-f”后的是导出的文件，“8000”表示数据库服务器端口；“testdb”表示要访问的数据库名。
gs_restore用来导入由gs_dump生成的导出文件。
示例1：执行gs_restore，将导出的MPPDB_backup.dmp文件（自定义归档格式）导入到testdb数据库。
gs_restore backup/MPPDB_backup.dmp -p 8000 -d testdb
restore operation successful
total time: 13053 ms
示例2：执行gs_restore，将导出的MPPDB_backup.tar文件（tar格式）导入到testdb数据库。
gs_restore backup/MPPDB_backup.tar -p 8000 -d testdb
restore operation successful
total time: 21203 ms
示例3：执行gs_restore，将导出的MPPDB_backup文件（目录格式）导入到testdb数据库。
gs_restore backup/MPPDB_backup -p 8000 -d testdb
restore operation successful
total time: 21003 ms
示例4：执行gs_restore，使用自定义归档格式的MPPDB_backup.dmp文件来进行如下导入操作。 导入PUBLIC模式下所有对象的定义和数据。在导入时会先删除已经存在的对象，如果原对象存在跨模式的依赖则需手工强制干预。
gs_restore backup/MPPDB_backup.dmp -p 8000 -d testdb -e -c -n PUBLIC
Error while PROCESSING TOC:
Error from TOC entry 313; 1259 337399 TABLE table1 gaussdba
could not execute query: ERROR: cannot drop table table1 because other objects depend on it
DETAIL: view t1.v1 depends on table table1
HINT: Use DROP ... CASCADE to drop the dependent objects too.
Command was: DROP TABLE IF EXISTS public.table1;
手工删除依赖，导入完成后再重新创建。
gs_restore backup/MPPDB_backup.dmp -p 8000 -d testdb -e -c -n PUBLIC
restore operation successful
total time: 2203 ms
示例5：执行gs_restore，使用自定义归档格式的MPPDB_backup.dmp文件来进行如下导入操作。只导入PUBLIC模式下表table1的定义。
gs_restore backup/MPPDB_backup.dmp -p 8000 -d testdb -e -c -s -n PUBLIC -t table1
restore operation successful
total time: 21000 ms
示例6：执行gs_restore，使用自定义归档格式的MPPDB_backup.dmp文件来进行如下导入操作。只导入PUBLIC模式下表table1的数据。
gs_restore backup/MPPDB_backup.dmp -p 8000 -d testdb -e -a -n PUBLIC -t table1
restore operation successful
total time: 20203 ms
