文档首页/ 云数据库 GaussDB/ 工具参考（集中式_V2.0-8.x）/ gs_restore
更新时间：2024-12-13 GMT+08:00
查看PDF
分享

gs_restore

背景信息

gs_restore是GaussDB提供的针对gs_dump导出数据的导入工具。通过此工具可将gs_dump导出生成的文件进行导入。

主要功能包含：

  • 导入到数据库

    如果连接参数中指定了数据库，则数据将被导入到指定的数据库中。其中，并行导入必须指定连接的密码。导入时生成列会自动更新，并像普通列一样保存。

    如果连接参数中指定了PDB，则数据将被导入到指定的PDB中。

    • 如果导入至指定的PDB，则不支持使用-C, --create选项。
    • 如果导入指定的PDB处于close状态时，导入操作会执行失败。
    • 如果导入指定的PDB设置事务为只读事务时，导入操作会执行失败。
    • M-Compatibility模式数据库下，禁止在lower_case_table_names参数不同的实例之间进行导入导出，否则可能引起数据丢失。
  • 导入到归档文件

    如果参数指定"-l"，则生成归档文件，其中包含简略的数据总结。

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

    连接数据库dbname并直接导入到该数据库中。

  • -f, --file=<FILE_NAME>

    指定生成归档的输出文件，使用-l时列表的输出文件。

    默认是标准输出。

    -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

    指定verbose模式。

  • -V, --version

    打印gs_restore版本，然后退出。

  • -?, --help

    显示gs_restore命令行参数帮助，然后退出。

导入参数：

  • -a, -data-only

    只导入数据，不导入模式（数据定义）。gs_restore的导入是以追加方式进行的。

  • -c, --clean

    在重新创建数据库对象前，清理（删除）已存在于将要还原的数据库中的数据库对象。如果目标数据库中没有删除操作涉及的对象，可能会输出一些提示性的错误信息。

  • -C, --create

    导入数据库之前会先使用CREATE DATABASE创建数据库（指定该选项后，-d指定的数据库仅用于执行CREATE DATABASE命令，所有数据依然会导入到创建的数据库中）。

    • 在多租场景下，使用gs_restore导入数据至PDB时，不支持使用该选项。
    • 在M-Compatibility模式数据库下，不支持使用该选项。必须先在目标实例上创出M-Compatibility模式数据库，然后在源实例上导出，最后在目标实例连接新创出的M-Compatibility模式数据库导入。
  • -e, --exit-on-error

    当发送SQL语句到数据库时如果出现错误，请退出。默认状态下会继续，且在导入后会显示一系列错误信息。

  • -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数。
    • 当gs_restore导入目标数据库是PDB时，该选项的最优值取决于分配给该PDB的资源规格。
  • -L, --use-list=<FILE_NAME>

    只导入列举在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会被导入。

    • M-Compatibility兼容模式下，通过CREATE DATABASE带templatem创建的数据库通过-d指定db_name导入数据，而通过CREATE DATABASE db_name创建出来的database等价于Schema，只能通过-n导入数据。
    • 指定的模式名必须存在于作为输入的归档文件中，如果指定了归档文件中不存在的模式名，该模式的导入不生效。
    • 与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

    防止导入访问权限（grant/revoke命令）。

  • -1, --single-transaction

    执行导入作为一个单独事务（即把命令包围在BEGIN/COMMIT中）。

    该选项确保要么所有命令成功完成，要么没有改变应用。该选项意为--exit-on-error。

  • --disable-triggers

    该参数为扩展预留接口，不建议使用。

  • --no-data-for-failed-tables

    默认状态下，即使创建表的命令失败（如表已经存在），表数据仍会被导入。使用该选项，像这种表的数据会被跳过。如果目标数据库已包含想要的表内容，这种行为会有帮助。

    该选项只有在直接导入到某数据库中时有效，不针对生成SQL脚本文件输出。

  • --no-security-labels

    该参数为扩展预留接口，不建议使用。

  • --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

    使用管道传输密码，禁止在终端使用。

  • 如果安装过程中有任何本地数据要添加到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

示例7：在多租场景下，执行gs_restore，导入指定PDB_backup.dmp文件（自定义归档格式）到名称为testpdb的PDB。

gs_restore backup/PDB_backup.dmp -p 20000 -d testpdb
restore operation successful
total time: 371  ms

示例8：在多租场景下，执行gs_restore，导入指定PDB_backup.tar文件（tar归档格式）到名称为testpdb的PDB。

gs_restore backup/PDB_backup.tar -p 20000 -d testpdb
restore operation successful
total time: 367  ms

示例9：在多租场景下，执行gs_restore，导入指定PDB_backup目录文件（目录归档格式）到名称为testpdb的PDB。

gs_restore backup/PDB_backup -p 20000 -d testpdb
restore operation successful
total time: 370  ms

示例10：在多租场景下，执行gs_retsore，使用-C, --create选项来进行导入操作，gs_restore报错退出。

gs_restore backup/PDB_backup -C -p 20000 -d testpdb
gs_restore unsupport the '-C, --create' option for pdb.

相关命令

gs_dump，gs_dumpall

相关文档