逻辑备份与恢复

gs_dump工具由操作系统用户omm执行。

gs_dump工具在进行数据导出时，其他用户可以访问openGauss数据库（读或写）。

gs_dump工具支持导出完整一致的数据。例如，T1时刻启动gs_dump导出A数据库，那么导出数据结果将会是T1时刻A数据库的数据状态，T1时刻之后对A数据库的修改不会被导出。

gs_dump时生成列不会被转储。

gs_dump支持导出兼容v1版本数据库的文本格式文件。

gs_dump支持将数据库信息导出至纯文本格式的SQL脚本文件或其他归档文件中。

• 纯文本格式的SQL脚本文件：包含将数据库恢复为其保存时的状态所需的SQL语句。通过gsql运行该SQL脚本文件，可以恢复数据库。即使在其他主机和其他数据库产品上，只要对SQL脚本文件稍作修改，也可以用来重建数据库。
• 归档格式文件：包含将数据库恢复为其保存时的状态所需的数据，可以是tar格式、目录归档格式或自定义归档格式，详见。该导出结果必须与gs_restore配合使用来恢复数据库，gs_restore工具在导入时，系统允许用户选择需要导入的内容，甚至可以在导入之前对等待导入的内容进行排序。

主要功能

gs_dump可以创建四种不同的导出文件格式，通过**[-F或者–format=]**选项指定，具体如表1所示。

表 1 导出文件格式

注意事项

• 禁止修改-F c/d/t 格式导出的文件和内容，否则可能无法恢复成功。对于-F p 格式导出的文件，如有需要，可根据需要谨慎编辑导出文件。
• 为了保证数据一致性和完整性，gs_dump会对需要转储的表设置共享锁。如果表在别的事务中设置了共享锁，gs_dump会等待锁释放后锁定表。如果无法在指定时间内锁定某个表，转储会失败。用户可以通过指定–lock-wait-timeout选项，自定义等待锁超时时间。
• 不支持加密导出存储过程和函数。

语法

说明:

“DBNAME”前面不需要加短或长选项。“DBNAME指定要连接的数据库。 例如： 不需要-d，直接指”DBNAME”。

或者

  export PGDATABASE=postgres

  gs_dump -p port_number -f dump1.sql

环境变量： PGDATABASE

参数说明

通用参数：

• -f, –file=FILENAME

  将输出发送至指定文件或目录。如果省略该参数，则使用标准输出。如果输出格式为(-F c/-F d/-F t)时，必须指定-f参数。如果-f的参数值含有目录，要求当前用户对该目录具有读写权限，并且不能指定已有目录。

• -F, –format=c|d|t|p

  选择输出格式。格式如下：

  • p|plain：输出一个文本SQL脚本文件（默认）。

  • c|custom：输出一个自定义格式的归档，并且以目录形式输出，作为gs_restore输入信息。该格式是最灵活的输出格式，因为能手动选择，而且能在恢复过程中将归档项重新排序。该格式默认状态下会被压缩。

  • d|directory：该格式会创建一个目录，该目录包含两类文件，一类是目录文件，另一类是每个表和blob对象对应的数据文件。

  • t|tar：输出一个tar格式的归档形式，作为gs_restore输入信息。tar格式与目录格式兼容；tar格式归档形式在提取过程中会生成一个有效的目录格式归档形式。但是，tar格式不支持压缩且对于单独表有8GB的大小限制。此外，表数据项的相应排序在恢复过程中不能更改。

• -v, –verbose

  指定verbose模式。该选项将导致gs_dump向转储文件输出详细的对象注解和启动/停止次数，向标准错误流输出处理信息。

• -V, –version

  打印gs_dump版本，然后退出。

• -Z, –compress=0-9

  指定使用的压缩比级别。

  取值范围：0~9

  • 0表示无压缩。
  • 1表示压缩比最小，处理速度最快。
  • 9表示压缩比最大，处理速度最慢。

  针对自定义归档格式，该选项指定单个表数据片段的压缩，默认方式是以中等级别进行压缩。tar归档格式和纯文本格式目前不支持压缩。

• –lock-wait-timeout=TIMEOUT

  请勿在转储刚开始时一直等待以获取共享表锁。如果无法在指定时间内锁定某个表，就选择失败。可以以任何符合SET statement_timeout的格式指定超时时间。

• -?, –help

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

转储参数：

• -a, –data-only

  只输出数据，不输出模式(数据定义)。转储表数据、大对象和序列值。

• -b, –blobs

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

• -c, –clean

  在将创建数据库对象的指令输出到备份文件之前，先将清理（删除）数据库对象的指令输出到备份文件中。（如果目标数据库中没有任何对象，gs_restore工具可能会输出一些提示性的错误信息）

  该选项只对文本格式有意义。针对归档格式，可以调用gs_restore时指定选项。

• -C, –create

  备份文件以创建数据库和连接到创建的数据库的命令开始。（如果命令脚本是这种方式执行，可以先指定任意数据库用于执行创建数据库的命令，数据不会恢复到指定的数据库中，而是恢复到创建的数据库中。）

  该选项只对文本格式有意义。针对归档格式，可以在调用gs_restore时指定选项。

• -E, –encoding=ENCODING

  以指定的字符集编码创建转储。默认情况下，以数据库编码创建转储。（得到相同结果的另一个办法是将环境变量“PGCLIENTENCODING”设置为所需的转储编码。）

• -n, –schema=SCHEMA

  只转储与模式名称匹配的模式，此选项包括模式本身和所有它包含的对象。如果该选项没有指定，所有在目标数据库中的非系统模式将会被转储。写入多个-n选项来选择多个模式。此外，根据gsql的\d命令所使用的相同规则，模式参数可被理解成一个pattern，所以多个模式也可以通过在该pattern中写入通配符来选择。使用通配符时，注意给pattern打引号，防止shell扩展通配符。

  说明:

  • 当-n已指定时，gs_dump不会转储已选模式所附着的任何其他数据库对象。因此，无法保证某个指定模式的转储结果能够自行成功地储存到一个空数据库中。
  • 当-n指定时，非模式对象不会被转储。

  转储支持多个模式的转储。多次输入-n schemaname转储多个模式。

  例如：

  gs_dump -h host_name -p port_number postgres -f backup/bkp_shl2.sql -n sch1 -n sch2

  在上面这个例子中，sch1和sch2会被转储。

• -N, –exclude-schema=SCHEMA

  不转储任何与模式pattern匹配的模式。pattern将参照针对-n的相同规则来理解。可以通过输入多次-N，不转储与任何pattern匹配的模式。

  当同时输入-n和-N时，会转储与至少一个-n选项匹配、与-N选项不匹配的模式。如果有-N没有-n，则不转储常规转储中与-N匹配的模式。

  转储过程支持排除多个模式。

  在转储过程中，输入-N exclude schema name排除多个模式。

  例如：

  gs_dump -h host_name -p port_number postgres -f backup/bkp_shl2.sql -N sch1 -N sch2

  在上面这个例子中，sch1和sch2在转储过程中会被排除。

• -o, –oids

  转储每个表的对象标识符（OIDs），作为表的一部分数据。该选项用于应用以某种方式参照了OID列的情况。如果不是以上这种情况，请勿使用该选项。

• -O, –no-owner

  不输出设置对象的归属这样的命令，以匹配原始数据库。默认情况下，gs_dump会发出ALTER OWNER或SET SESSION AUTHORIZATION语句设置所创建的数据库对象的归属。如果脚本正在运行，该语句不会执行成功，除非是由系统管理员触发（或是拥有脚本中所有对象的同一个用户）。通过指定-O，编写一个任何用户都能存储的脚本，且该脚本会授予该用户拥有所有对象的权限。

  该选项只对文本格式有意义。针对归档格式，可以在调用gs_restore时指定选项。

• -s, –schema-only

  只转储对象定义（模式），而非数据。

• -S, –sysadmin=NAME

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

• -t, –table=TABLE

  指定转储的表（或视图、或序列、或外表）对象列表，可以使用多个-t选项来选择多个表，也可以使用通配符指定多个表对象。

  当使用通配符指定多个表对象时，注意给pattern打引号，防止shell扩展通配符。

  当使用-t时，-n和-N没有任何效应，这是因为由-t选择的表的转储不受那些选项的影响。

  说明:

  • -t参数选项个数必须小于等于100。
  • 如果-t参数选项个数大于100，建议使用参数–include-table-file来替换。
  • 当-t已指定时，gs_dump不会转储已选表所附着的任何其他数据库对象。因此，无法保证某个指定表的转储结果能够自行成功地储存到一个空数据库中。
  • -t tablename只转储在默认搜索路径中可见的表。-t *.tablename转储数据库下所有模式下的tablename表。-t schema.table转储特定模式中的表。
  • -t tablename不会导出表上的触发器信息。
  • 对于表名中包含大写字母的表，在使用-t参数指定导出时需对表名添加”来导出。如对于表”abC”，导出需指定-t “abC”；如对于表schema.“abC”，导出需指定-t schema.”abC”。

  例如：

  gs_dump -h host_name -p port_number postgres -f backup/bkp_shl2.sql -t schema1.table1 -t schema2.table2

  在上面这个例子中，schema1.table1和schema2.table2会被转储。

• –include-table-file=FILENAME

  指定需要dump的表文件。

• -T, –exclude-table=TABLE

  不转储的表（或视图、或序列、或外表）对象列表，可以使用多个-T选项来选择多个表，也可以使用通配符指定多个表对象。

  当同时输入-t和-T时，会转储在-t列表中，而不在-T列表中的表对象。

  例如：

  gs_dump -h host_name -p port_number postgres -f backup/bkp_shl2.sql -T table1 -T table2

  在上面这个例子中，table1和table2在转储过程中会被排除。

• –exclude-table-file=FILENAME

  指定不需要dump的表文件。

• -x, –no-privileges|–no-acl

  防止转储访问权限（授权/撤销命令）。

• -q, –target

  指定导出兼容其他版本数据库的文本文件，目前支持v1和v5参数。v1参数用于导出v5数据库的数据为兼容v1的文本文件。v5参数用于导出v5数据库的数据为v5格式的文本文件，减少了导入v5时的可能的报错情况。

  在使用v1参数时，建议和–exclude-guc=“enable_cluster_resize”，–exclude-function，–exclude-with等选项共用，否则导入到v1时可能报错。

• -g, –exclude-guc

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

• –exclude-function

  不导出函数和存储过程。

• –exclude-with

  导出的表定义，末尾不添加WITH(orientation=row，compression=on）这样的描述。

• –binary-upgrade

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

• –binary-upgrade-usermap=“USER1=USER2”

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

• –column-inserts|–attribute-inserts

  以INSERT命令带列名（INSERT INTO表（列、…）值…）方式导出数据。这会导致恢复缓慢。但是由于该选项会针对每行生成一个独立分开的命令，所以在重新加载某行时出现的错误只会导致那行丢失，而非整个表内容。

• –disable-dollar-quoting

  该选项将禁止在函数体前使用美元符号$，并强制使用SQL标准字符串语法对其进行引用。

• –disable-triggers

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

• –exclude-table-data=TABLE

  指定不转储任何匹配表pattern的表这方面的数据。依照针对-t的相同规则理解该pattern。

  可多次输入–exclude-table-data来排除匹配任何pattern的表。当用户需要特定表的定义但不需要其中的数据时，这个选项很有帮助。

  排除数据库中所有表的数据，参见–schema-only。

• –inserts

  发出INSERT命令（而非COPY命令）转储数据。这会导致恢复缓慢。

  但是由于该选项会针对每行生成一个独立分开的命令，所以在重新加载某行时出现的错误只会导致那行丢失，而非整个表内容。注意：如果重排列顺序，可能会导致整个恢复失败。列顺序改变时，–column-inserts选项不受影响，虽然会更慢。

• –no-publications

  不转储发布。

• –no-security-labels

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

• –no-subscriptions

  不转储订阅。

• –no-tablespaces

  不输出选择表空间的命令。使用该选项，无论默认表空间是哪个，在恢复过程中所有对象都会被创建。

  该选项只对文本格式有意义。针对归档格式，可以在调用gs_restore时指定选项。

• –no-unlogged-table-data

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

• –non-lock-table

  该参数仅供软件间接口调用。

• 转储表删除列。该选项会记录列的删除。

• –quote-all-identifiers

  强制对所有标识符加引号。为了向后续版本迁移，且其中可能涉及引入额外关键词，在转储相应数据库时该选项会有帮助。

• –section=SECTION

  指定已转储的名称区段（pre-data、data和post-data）。

• –serializable-deferrable

  转储过程中使用可串行化事务，以确保所使用的快照与之后的数据库状态一致；要实现该操作需要在无异常状况的事务流中等待某个点，因为这样才能保证转储成功，避免引起其他事务出现serialization_failure要重新再做。

  但是该选项对于灾难恢复没有益处。对于在原始数据库进行升级的时候，加载一个数据库的拷贝作为报告或其他只读加载共享的转储是有帮助的。没有这个选项，转储会反映一个与任何事务最终提交的序列化执行不一致的状态。

  如果当gs_dump启动时，读写事务仍处于非活动状态，即便使用该选项也不会对其产生影响。如果读写事务处于活动状态，转储的开始时间可能会延迟一段不确定的时间。

• –use-set-session-authorization

  输出符合SQL标准的SET SESSION AUTHORIZATION命令而不是ALTER OWNER命令来确定对象所有权。这样令转储更加符合标准，但是如果转储文件中的对象的历史有些问题，那么可能不能正确恢复。并且，使用SET SESSION AUTHORIZATION的转储需要数据库系统管理员的权限才能转储成功，而ALTER OWNER需要的权限则低得多。

• –with-encryption=AES128

  指定转储数据需用AES128进行加密。

• –with-key=KEY

  AES128密钥规则如下：

  • 密钥长度为8~16个字符。
  • 至少包含大写字母（A-Z）、小写字母（a-z）、数字（0-9）、非字母数字字符（限定为~!@#$%^&*()-_=+\|[{}];:,<.>/?）四类字符中的三类字符。

  说明:

  • 使用gs_dump工具进行加密导出时，仅支持plain格式导出。通过-F plain导出的数据，需要通过gsql工具进行导入，且如果以加密方式导入，在通过gsql导入时，需要指定–with-key参数。
  • 不支持加密导出存储过程和函数。

• –with-salt=RANDVALUES

  gs_dumpall使用此参数传递随机值。

• –include-Extensions

  在转储中包含扩展。

• –include-depend-objs

  备份结果包含依赖于指定对象的对象信息。该参数需要同-t/–include-table-file参数关联使用才会生效。

• –exclude-self

  备份结果不包含指定对象自身的信息。该参数需要同-t/–include-table-file参数关联使用才会生效。

• –pipeline

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

说明:

• -s/–schema-only和-a/–data-only不能同时使用。
• -c/–clean和-a/–data-only不能同时使用。
• –inserts/–column-inserts和-o/–oids不能同时使用，因为INSERT命令不能设置OIDS。
• –role和–rolepassword必须一起使用。
• –binary-upgrade-usermap和–binary-upgrade必须一起使用。
• –include-depend-objs/–exclude-self需要同-t/–include-table-file参数关联使用才会生效。
• –exclude-self必须同–include-depend-objs一起使用。

连接参数：

• -h, –host=HOSTNAME

  指定主机名称。如果数值以斜杠开头，则被用作到Unix域套接字的路径。缺省从PGHOST环境变量中获取（如果已设置），否则，尝试一个Unix域套接字连接。

  该参数只针对openGauss外，对openGauss内本机只能用127.0.0.1。

  例如：主机名

  环境变量：PGHOST

• -p, –port=PORT

  指定主机端口。在开启线程池情况下，建议使用 pooler port，即主机端口+1。

  环境变量：PGPORT

• -U, –username=NAME

  指定所连接主机的用户名。

  不指定连接主机的用户名时，用户默认系统管理员。

  环境变量：PGUSER

• -w, –no-password

  不出现输入密码提示。如果主机要求密码认证并且密码没有通过其它形式给出，则连接尝试将会失败。 该选项在批量工作和不存在用户输入密码的脚本中很有帮助。

• -W, –password=PASSWORD

  指定用户连接的密码。如果主机的认证策略是trust，则不会对系统管理员进行密码验证，即无需输入-W选项；如果没有-W选项，并且不是系统管理员，“Dump Restore工具”会提示用户输入密码。

• –role=ROLENAME

  指定创建转储使用的角色名。选择该选项，会使gs_dump连接数据库后，发起一个SET ROLE角色名命令。当所授权用户（由-U指定）没有gs_dump要求的权限时，该选项会起到作用，即切换到具备相应权限的角色。某些安装操作规定不允许直接以超系统管理员身份登录，而使用该选项能够在不违反该规定的情况下完成转储。

• –rolepassword=ROLEPASSWORD

  指定角色名的密码。

说明

如果openGauss有任何本地数据要添加到template1数据库，请谨慎将gs_dump的输出恢复到一个真正的空数据库中，否则可能会因为被添加对象的定义被复制，出现错误。要创建一个无本地添加的空数据库，需从template0而非template1复制，例如：

CREATE DATABASE foo WITH TEMPLATE template0;

tar归档形式的文件大小不得超过8GB（tar文件格式的固有限制）。tar文档整体大小和任何其他输出格式没有限制，操作系统可能对此有要求。

由gs_dump生成的转储文件不包含优化程序用来做执行计划决定的统计数据。因此，最好从某转储文件恢复之后运行ANALYZE以确保最佳效果。转储文件不包含任何ALTER DATABASE…SET命令，这些设置由gs_dumpall转储，还有数据库用户和其他完成安装设置。

使用gs_dump转储数据库为SQL文本文件或其它格式的操作，如下所示。

示例中“Bigdata@123”表示数据库用户密码；“backup/MPPDB_backup.sql”表示导出的文件，其中backup表示相对于当前目录的相对目录；“37300”表示数据库服务器端口；“postgres”表示要访问的数据库名。导出操作时，请确保该目录存在并且当前的操作系统用户对其具有读写权限。

示例1：执行gs_dump，导出postgres数据库全量信息，导出的MPPDB_backup.sql文件格式为纯文本格式。

gs_dump -U omm -W Bigdata@123 -f backup/MPPDB_backup.sql -p 37300 postgres -F p
gs_dump[port='37300'][postgres][2018-06-27 09:49:17]: The total objects number is 356.
gs_dump[port='37300'][postgres][2018-06-27 09:49:17]: [100.00%] 356 objects have been dumped.
gs_dump[port='37300'][postgres][2018-06-27 09:49:17]: dump database postgres successfully
gs_dump[port='37300'][postgres][2018-06-27 09:49:17]: total time: 1274  ms

使用gsql程序从纯文本导出文件中导入数据。

示例2：执行gs_dump，导出postgres数据库全量信息，导出的MPPDB_backup.tar文件格式为tar格式。

gs_dump -U omm -W Bigdata@123 -f backup/MPPDB_backup.tar -p 37300 postgres -F t
gs_dump[port='37300'][postgres][2018-06-27 10:02:24]: The total objects number is 1369.
gs_dump[port='37300'][postgres][2018-06-27 10:02:53]: [100.00%] 1369 objects have been dumped.
gs_dump[port='37300'][postgres][2018-06-27 10:02:53]: dump database postgres successfully
gs_dump[port='37300'][postgres][2018-06-27 10:02:53]: total time: 50086  ms

示例3：执行gs_dump，导出postgres数据库全量信息，导出的MPPDB_backup.dmp文件格式为自定义归档格式。

示例4：执行gs_dump，导出postgres数据库全量信息，导出的MPPDB_backup文件格式为目录格式。

gs_dump -U omm -W Bigdata@123 -f backup/MPPDB_backup -p 37300  postgres -F d
gs_dump[port='37300'][postgres][2018-06-27 10:16:04]: The total objects number is 1369.
gs_dump[port='37300'][postgres][2018-06-27 10:16:23]: [100.00%] 1369 objects have been dumped.
gs_dump[port='37300'][postgres][2018-06-27 10:16:23]: dump database postgres successfully
gs_dump[port='37300'][postgres][2018-06-27 10:16:23]: total time: 33977  ms

示例5：执行gs_dump，导出postgres数据库信息，但不导出/home/MPPDB_temp.sql中指定的表信息。导出的MPPDB_backup.sql文件格式为纯文本格式。

gs_dump -U omm -W Bigdata@123 -p 37300 postgres --exclude-table-file=/home/MPPDB_temp.sql -f backup/MPPDB_backup.sql
gs_dump[port='37300'][postgres][2018-06-27 10:37:01]: The total objects number is 1367.
gs_dump[port='37300'][postgres][2018-06-27 10:37:22]: [100.00%] 1367 objects have been dumped.
gs_dump[port='37300'][postgres][2018-06-27 10:37:22]: dump database postgres successfully
gs_dump[port='37300'][postgres][2018-06-27 10:37:22]: total time: 37017  ms

示例6：执行gs_dump，仅导出依赖于指定表testtable的视图信息。然后创建新的testtable表，再恢复依赖其上的视图。

• 备份仅依赖于testtable的视图。

  gs_dump -s -p 37300 postgres -t PUBLIC.testtable --include-depend-objs --exclude-self -f backup/MPPDB_backup.sql -F p
  gs_dump[port='37300'][postgres][2018-06-15 14:12:54]: The total objects number is 331.
  gs_dump[port='37300'][postgres][2018-06-15 14:12:54]: dump database postgres successfully
  gs_dump[port='37300'][postgres][2018-06-15 14:12:54]: total time: 327  ms

• 修改testtable名称。

  gsql -p 37300 postgres -r -c "ALTER TABLE PUBLIC.testtable RENAME TO testtable_bak;"

• 创建新的testtable表。

  CREATE TABLE PUBLIC.testtable(a int, b int, c int);

• 还原依赖于testtable的视图。

  gsql -p 37300 postgres -r -f backup/MPPDB_backup.sql

背景信息

gs_dumpall是openGauss用于导出所有数据库相关信息工具，它可以导出openGauss数据库的所有数据，包括默认数据库postgres的数据、自定义数据库的数据以及openGauss所有数据库公共的全局对象。

gs_dumpall工具由操作系统用户omm执行。

gs_dumpall工具在进行数据导出时，其他用户可以访问openGauss数据库（读或写）。

gs_dumpall工具支持导出完整一致的数据。例如，T1时刻启动gs_dumpall导出openGauss数据库，那么导出数据结果将会是T1时刻该openGauss数据库的数据状态，T1时刻之后对openGauss的修改不会被导出。

gs_dumpall时生成列不会被转储。

gs_dumpall在导出openGauss所有数据库时分为两部分：

• gs_dumpall自身对所有数据库公共的全局对象进行导出，包括有关数据库用户和组、表空间以及属性（例如，适用于数据库整体的访问权限）信息。
• gs_dumpall通过调用gs_dump来完成openGauss中各数据库的SQL脚本文件导出，该脚本文件包含将数据库恢复为其保存时的状态所需要的全部SQL语句。

以上两部分导出的结果为纯文本格式的SQL脚本文件，使用gsql运行该脚本文件可以恢复openGauss数据库。

注意事项

• 禁止修改导出的文件和内容，否则可能无法恢复成功。
• 为了保证数据一致性和完整性，gs_dumpall会对需要转储的表设置共享锁。如果某张表在别的事务中设置了共享锁，gs_dumpall会等待此表的锁释放后锁定此表。如果无法在指定时间内锁定某张表，转储会失败。用户可以通过指定–lock-wait-timeout选项，自定义等待锁超时时间。
• 由于gs_dumpall读取所有数据库中的表，因此必须以openGauss管理员身份进行连接，才能导出完整文件。在使用gsql执行脚本文件导入时，同样需要管理员权限，以便添加用户和组以及创建数据库。

语法

gs_dumpall [OPTION]...

参数说明

通用参数：

• -f, –filename=FILENAME

  将输出发送至指定文件。如果这里省略，则使用标准输出。

• -v, –verbose

  指定verbose模式。该选项将导致gs_dumpall向转储文件输出详细的对象注解和启动/停止次数，向标准错误流输出处理信息。

• -V, –version

  打印gs_dumpall版本，然后退出。

• –lock-wait-timeout=TIMEOUT

  请勿在转储刚开始时一直等待以获取共享表锁。如果无法在指定时间内锁定某个表，就选择失败。可以以任何符合SET statement_timeout的格式指定超时时间。

• -?, –help

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

转储参数：

• -a, –data-only

  只转储数据，不转储模式（数据定义）。

• -c, –clean

  在重新创建数据库之前，执行SQL语句清理（删除）这些数据库。针对角色和表空间的转储命令已添加。

• -g, –globals-only

  只转储全局对象（角色和表空间），无数据库。

• -o, –oids

  转储每个表的对象标识符（OIDs），作为表的一部分数据。该选项用于应用以某种方式参照了OID列的情况。如果不是以上这种情况，请勿使用该选项。

• -O, –no-owner

  不输出设置对象的归属这样的命令，以匹配原始数据库。默认情况下，gs_dumpall会发出ALTER OWNER或SET SESSION AUTHORIZATION语句设置所创建的模式元素的所属。如果脚本正在运行，该语句不会执行成功，除非是由系统管理员触发（或是拥有脚本中所有对象的同一个用户）。通过指定-O，编写一个任何用户都能存储的脚本，且该脚本会授予该用户拥有所有对象的权限。

• -r, –roles-only

  只转储角色，不转储数据库或表空间。

• -s, –schema-only

  只转储对象定义（模式），而非数据。

• -S, –sysadmin=NAME

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

• -t, –tablespaces-only

  只转储表空间，不转储数据库或角色。

• -x, –no-privileges

  防止转储访问权限（授权/撤销命令）。

• –column-inserts|–attribute-inserts

  以INSERT命令带列名（INSERT INTO表（列、…）值…）方式导出数据。这会导致恢复缓慢。但是由于该选项会针对每行生成一个独立分开的命令，所以在重新加载某行时出现的错误只会导致那行丢失，而非整个表内容。

• –disable-dollar-quoting

  该选项将禁止在函数体前使用美元符号$，并强制使用SQL标准字符串语法对其进行引用。

• –disable-triggers

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

• –inserts

  发出INSERT命令（而非COPY命令）转储数据。这会导致恢复缓慢。注意：如果重排列顺序，可能会导致恢复整个失败。–column-inserts选项更加安全，虽然可能更慢些。

• –no-security-labels

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

• –no-tablespaces

  请勿输出创建表空间的命令，也请勿针对对象选择表空间。使用该选项，无论默认表空间是哪个，在恢复过程中所有对象都会被创建。

• –no-publications

  不转储发布。

• –no-security-labels

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

• –no-subscriptions

  不转储订阅。

• –include-alter-table

  导出表中已删除的列信息。

• –quote-all-identifiers

  强制对所有标识符加引号。为了向后续版本迁移，且其中可能涉及引入额外关键词，在转储相应数据库时该选项会有帮助。

• –dont-overwrite-file

  不重写当前文件。

• –use-set-session-authorization

  输出符合SQL标准的SET SESSION AUTHORIZATION命令而不是ALTER OWNER命令来确定对象所有权。这样令转储更加符合标准，但是如果转储文件中的对象的历史有些问题，那么可能不能正确恢复。并且，使用SET SESSION AUTHORIZATION的转储需要数据库系统管理员的权限才能转储成功，而ALTER OWNER需要的权限则低得多。

• –with-encryption=AES128

  指定转储数据需用AES128进行加密。

• –with-key=KEY

  AES128密钥规则如下：

  • 密钥长度为8~16个字符。
  • 至少包含大写字母（A-Z），小写字母（a-z），数字（0-9），非字母数字字符（限定为~!@#$%^&*()-_=+\|[{}];:,<.>/?）四类字符中的三类字符。

• –include-Extensions

  如果include-Extensions参数被设置，将备份所有的CREATE Extension语句。

• –include-templatedb

  转储过程中包含模板库。

• –binary-upgrade

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

• –binary-upgrade-usermap=“USER1=USER2”

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

• –non-lock-table

  该参数仅供软件间接口调用。

• –tablespaces-postfix

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

• –parallel-jobs

  指定备份进程并发数，取值范围为1~1000。

• –pipeline

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

说明:

• -g/–globals-only和-r/–roles-only不能同时使用。
• -g/–globals-only和-t/–tablespaces-only不能同时使用。
• -r/–roles-only和-t/–tablespaces-only不能同时使用。
• -s/–schema-only和-a/–data-only不能同时使用。
• -r/–roles-only和-a/–data-only不能同时使用。
• -t/–tablespaces-only和-a/–data-only不能同时使用。
• -g/–globals-only和-a/–data-only不能同时使用。
• –tablespaces-postfix和–binary-upgrade必须一起使用。
• –binary-upgrade-usermap和–binary-upgrade必须一起使用。
• –parallel-jobs和-f/–file必须一起使用。

连接参数：

• 指定主机的名称。如果取值是以斜线开头，它将用作Unix域套接字的目录。默认值取自PGHOST环境变量；如果没有设置，将启动某个Unix域套接字建立连接。

  该参数只针对openGauss外，对openGauss内本机只能用127.0.0.1。

  环境变量：PGHOST

• -l, –database=DATABASENAME

  指定所连接的转储全局对象的数据库名称，并去寻找还有其他哪些数据库需要被转储。如果没有指定，会使用postgres数据库，如果postgres数据库不存在，会使用template1。

• -p, –port=PORT

  指定服务器所侦听的TCP端口或本地Unix域套接字后缀，以确保连接。默认值设置为PGPORT环境变量。

  在开启线程池情况下，建议使用 pooler port，即侦听端口+1。

  环境变量：PGPORT

• -U, –username=NAME

  所连接的用户名。

  环境变量：PGUSER

• -w, –no-password

  不出现输入密码提示。如果服务器要求密码认证并且密码没有通过其它形式给出，则连接尝试将会失败。 该选项在批量工作和不存在用户输入密码的脚本中很有帮助。

• -W, –password=PASSWORD

  指定用户连接的密码。如果主机的认证策略是trust，则不会对系统管理员进行密码验证，即无需输入-W选项；如果没有-W选项，并且不是系统管理员，“Dump Restore工具”会提示用户输入密码。

• –role=ROLENAME

  指定创建转储使用的角色名。选择该选项，会使gs_dumpall连接数据库后，发起一个SET ROLE角色名命令。当所授权用户（由-U指定）没有gs_dumpall要求的权限时，该选项会起到作用，即切换到具备相应权限的角色。某些安装操作规定不允许直接以系统管理员身份登录，而使用该选项能够在不违反该规定的情况下完成转储。

• –rolepassword=ROLEPASSWORD

  指定具体角色用户的角色密码。

由于gs_dumpall内部调用gs_dump，所以一些诊断信息参见gs_dump。

一旦恢复，最好在每个数据库上运行ANALYZE，优化程序提供有用的统计数据。

gs_dumpall恢复前需要所有必要的表空间目录为空；否则，对于处在非默认位置的数据库，数据库创建会失败。

示例

使用gs_dumpall一次导出openGauss的所有数据库。

gs_dumpall -f backup/bkp2.sql -p 37300
gs_dump[port='37300'][dbname='postgres'][2018-06-27 09:55:35]: [100.00%] 2371 objects have been dumped.
gs_dump[port='37300'][dbname='postgres'][2018-06-27 09:55:46]: dump database dbname='postgres' successfully
gs_dump[port='37300'][dbname='postgres'][2018-06-27 09:55:46]: total time: 55567  ms
gs_dumpall[port='37300'][2018-06-27 09:55:46]: dumpall operation successful
gs_dumpall[port='37300'][2018-06-27 09:55:46]: total time: 56088  ms

背景信息

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

gs_restore工具由操作系统用户omm执行。

主要功能包含：

• 导入到数据库

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

• 导入到脚本文件

  如果未指定导入数据库，则创建包含重建数据库所必须的SQL语句脚本并写入到文件或者标准输出。等效于直接使用gs_dump导出为纯文本格式。

命令格式

gs_restore [OPTION]... FILE

说明:

• FILE没有短选项或长选项。用来指定归档文件所处的位置。
• 作为前提条件，需输入dbname或-l选项。不允许用户同时输入dbname和-l选项。
• gs_restore默认是以追加的方式进行数据导入。为避免多次导入造成数据异常，在进行导入时，建议使用“-c”参数，在重新创建数据库对象前，清理（删除）已存在于将要还原的数据库中的数据库对象。
• 日志打印无开关，若需隐藏日志，请将日志重定向到日志文件。若恢复表数据时，数据量很大，会分批恢复，因此会多次出现“表数据已完成导入”的日志。

参数说明

通用参数：

• -d, –dbname=NAME

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

• -f, –file=FILENAME

  指定生成脚本的输出文件，或使用-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命令，所有数据依然会导入到创建的数据库中。）

• -e, –exit-on-error

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

• -I, –index=NAME

  只导入已列举的index的定义。允许导入多个index。如果多次输入-I index导入多个index。

  例如：

  gs_restore -h host_name -p port_number -d postgres -I Index1 -I Index2 backup/MPPDB_backup.tar

  在上面这个例子中，Index1和Index2会被导入。

• -j, –jobs=NUM

  运行gs_restore最耗时的部分（如加载数据、创建index或创建约束）使用并发任务。该选项能大幅缩短导入时间，即将一个大型数据库导入到某一多处理器的服务器上。

  每个任务可能是一个进程或一个线程，这由操作系统决定。每个任务与服务器进行单独连接。

  该选项的最优值取决于服务器的硬件设置、客户端以及网络。还包括这些因素，如CPU核数量、硬盘设置。建议是从增加服务器上的CPU核数量入手，更大的值（服务器上CPU核数量）在很多情况下也能导致数据文件更快的被导入。当然，过高的值会由于超负荷反而导致性能降低。

  该选项只支持自定义归档格式。输入文件必须是常规文件（不能是像pipe的文件）。如果是通过脚本文件，而非直接连接数据库服务器，该选项可忽略。而且，多任务不能与–single-transaction选项一起使用。

• -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 postgres -n sch1 -n sch2 backup/MPPDB_backup.tar

  在上面这个例子中，sch1和sch2会被导入。

• -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)’同时导入多个指定模式下的函数。

  例如：

  在上面这个例子中，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 postgres -t table1 backup/MPPDB_backup.tar

  导入test1模式下的test1和test2模式下test2

  gs_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

  gs_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。

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

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

连接参数：

• -h, –host=HOSTNAME

  指定的主机名称。如果取值是以斜线开头，他将用作Unix域套接字的目录。默认值取自PGHOST环境变量；如果没有设置，将启动某个Unix域套接字建立连接。

  该参数只针对openGauss外，对openGauss内本机只能用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参数，并且不是系统管理员，“gs_restore”会提示用户输入密码。

• –role=ROLENAME

  指定导入操作使用的角色名。选择该参数，会使gs_restore连接数据库后，发起一个SET ROLE角色名命令。当所授权用户（由-U指定）没有gs_restore要求的权限时，该参数会起到作用，即切换到具备相应权限的角色。某些安装操作规定不允许直接以初始用户身份登录，而使用该参数能够在不违反该规定的情况下完成导入。

• –rolepassword=ROLEPASSWORD

  指定具体角色用户的角色密码。

特例：执行gsql程序，使用如下选项导入由gs_dump/gs_dumpall生成导出文件夹（纯文本格式）的MPPDB_backup.sql文件到postgres数据库。

gsql -d postgres -p 15400 -W Bigdata@123 -f /home/omm/test/MPPDB_backup.sql
SET
SET
SET
SET
SET
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

gs_restore用来导入由gs_dump生成的导出文件。

示例1：执行gs_restore，将导出的MPPDB_backup.dmp文件（自定义归档格式）导入到postgres数据库。

gs_restore -W Bigdata@123 backup/MPPDB_backup.dmp -p 15400 -d postgres
restore operation successful
total time: 13053  ms

示例2：执行gs_restore，将导出的MPPDB_backup.tar文件（tar格式）导入到postgres数据库。

gs_restore backup/MPPDB_backup.tar -p 15400 -d postgres 
restore operation successful
total time: 21203  ms

示例3：执行gs_restore，将导出的MPPDB_backup文件（目录格式）导入到postgres数据库。

gs_restore backup/MPPDB_backup -p 15400 -d postgres
restore operation successful
total time: 21003  ms

示例4：执行gs_restore，使用自定义归档格式的MPPDB_backup.dmp文件来进行如下导入操作。 导入PUBLIC模式下所有对象的定义和数据。在导入时会先删除已经存在的对象，如果原对象存在跨模式的依赖则需手工强制干预。

gs_restore backup/MPPDB_backup.dmp -p 15400 -d postgres -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 15400 -d postgres -e -c -n PUBLIC
restore operation successful
total time: 2203  ms

gs_restore backup/MPPDB_backup.dmp -p 15400 -d postgres -e -c -s -n PUBLIC -t table1
total time: 21000  ms

示例6：执行gs_restore，使用自定义归档格式的MPPDB_backup.dmp文件来进行如下导入操作。只导入PUBLIC模式下表table1的数据。