openGauss 逻辑备份恢复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不会导出表上的触发器信息。

  例如：

  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的表文件。

  说明:
  同–include-table-file，其内容格式如下：
  schema1.table1
  schema2.table2
  …

• -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时可能报错。

• –exclude-guc

  导出的文本文件中，不包括相关guc参数的set命令，目前只支持enable_cluster_resize。

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

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

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

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

• –dont-overwrite-file

  文本、tar以及自定义格式情况下会重写现有文件。这对目录格式不适用。

  例如：

  设想这样一种情景，即当前目录下backup.sql已存在。如果在输入命令中输入-f backup.sql选项时，当前目录恰好也生成backup.sql，文件就会被重写。

  如果备份文件已存在，且输入–dont-overwrite-file选项，则会报告附带‘转储文件已经存在’信息的错误。

  gs_dump -p port_number postgres -f backup.sql -F plain --dont-overwrite-file
  

说明:

• -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一起使用。