# gs_dump导出数据库信息
#### 工具介绍
gs_dump是GaussDB用于导出数据库相关信息的工具，用户可以自定义导出一个数据库或其中的对象（模式、表、视图等）。支持导出的数据库可以是默认数据库postgres，也可以是自定义数据库。
- gs_dump支持SSL加密通信。
- gs_dump工具在进行数据导出时，其他用户可以访问集群数据库（读或写）。

- gs_dump工具导出完整一致的数据。例如，T1时刻启动gs_dump导出A数据库，那么导出数据结果将会是T1时刻A数据库的数据状态，T1时刻之后对A数据库的修改不会被导出。
- gs_dump支持将数据库信息导出至纯文本格式的SQL脚本文件或其他归档文件中。
  - 纯文本格式的SQL脚本文件：包含将数据库恢复为其保存时的状态所需的SQL语句。通过[gsql连接数据库](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0617.html)运行该SQL脚本文件，可以恢复数据库。即使在其他主机和其他数据库产品上，只要对SQL脚本文件稍作修改，也可以用来重建数据库。
  
  - 归档格式文件：包含将数据库恢复为其保存时的状态所需的数据，可以是tar格式、目录归档格式或自定义归档格式，详见[表1]。该导出结果必须与[gs_restore导入数据](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0702.html)配合使用来恢复数据库，使用gs_restore工具导入时，系统允许用户选择需要导入的内容，甚至可以在导入之前对等待导入的内容进行排序。
   

- gs_dump支持四种不同的导出文件格式，通过\[-F或者--format=\]选项指定，具体如[表1]所示。
   表1导出文件格式 
  | 格式名称     | -F的参数值 | 说明                                                          | 建议                                   | 对应导入工具                                                                                                                                                 |
  |:---|:---|:---|:---|:---|
  | 纯文本格式    | p        | 纯文本脚本文件包含SQL语句和命令。命令可以由gsql命令行终端程序执行，用于重新创建数据库对象并加载表数据。      | 小型数据库，或者需要对导出的sql文件进行修改，推荐纯文本格式。 | 使用[gsql连接数据库](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0617.html)工具恢复数据库对象前，可根据需要使用文本编辑器编辑纯文本导出文件。                      |
  | 自定义归档格式  | c      | 一种二进制文件。支持从导出文件中恢复所有或所选的数据库对象。                               | 中型或大型数据库，推荐自定义归档格式。                 | 这三种归档格式，必须使用[4.7.5-gs_restore](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0702.html)进行对象和数据的导入。gs_restore也可以选择要导入的数据库对象。 |
  | 目录归档格式   | d      | 该格式会创建一个目录，该目录包含两类文件，一类是包含数据库对象的目录文件，另一类是每个表和blob对象对应的数据文件。 | 需要将数据库对象与数据分目录存储导出，推荐使用目录归档格式。    | 这三种归档格式，必须使用[4.7.5-gs_restore](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0702.html)进行对象和数据的导入。gs_restore也可以选择要导入的数据库对象。 |
  | tar归档格式 | t       | tar归档文件支持从导出文件中恢复所有或所选的数据库对象。tar归档格式不支持压缩且对于单个文件大小应小于8GB。   | 需要将归档结果导出并打包，可以使用tar归档格式。          | 这三种归档格式，必须使用[4.7.5-gs_restore](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0702.html)进行对象和数据的导入。gs_restore也可以选择要导入的数据库对象。 |
     
  ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
  可以使用gs_dump工具将文件压缩为目录归档或自定义归档导出文件，减少导出文件的大小。生成目录归档或自定义归档导出文件时，默认进行中等级别的压缩。gs_dump程序无法压缩已归档导出文件。
  
 
#### 注意事项
- 使用gs_dump前请确保gs_dump版本与数据库版本保持一致，高版本gs_dump不保证完全兼容低版本内核数据。
- gs_dump不适用于库中对象数量（表、视图、索引等）过多的场景。当库中对象数量超过十万级，或者对象间依赖关系过于复杂时，gs_dump导出时间会很长。

- 禁止修改-F c/d/t格式导出的文件和内容，否则可能无法恢复成功。对于-F p格式导出的文件，如有需要，可谨慎编辑导出的文件。
- 为了保证数据一致性和完整性，gs_dump默认会对需要转储的表设置ACCESS SHARE级别锁。如果表在别的事务中设置了冲突的锁，gs_dump会等待锁释放后锁定表。如果无法在指定时间内锁定某个表，转储会失败。用户可以通过指定--lock-wait-timeout选项，自定义等待锁超时时间。锁与锁之间的冲突请参见[LOCK](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0353.html)。
- 不支持加密导出存储过程和函数。
- 对于物化视图，本工具仅支持物化视图定义的导出，在导入后需手动执行REFRESH命令来进行数据恢复。
- gs_dump不会导出物化视图相关的matviewmap_和mlog_前缀开头的表，不会导出带有internal_mask选项的表，不会导出在回收站中的表。
- 对于临时对象，本工具仅支持导出全局临时表。
- 本工具不支持在备机上使用。
- 由于DN上系统表中分布信息不完整，所以在DN使用gs_dump时，不会转储表的分布信息。
- gs_dump导出分区索引时，部分索引分区的属性无法导出，比如索引分区的unusable状态。可以通过查询系统表PG_PARTITION或者查询视图ADM_IND_PARTITIONS获取索引分区的具体属性，通过ALTER INDEX命令可以手动设置索引分区属性。
- 对于定时任务，本工具仅支持导出在MYSQL兼容性数据库中，通过高级包创建的非周期性定时任务。
- gs_dump不支持导出自定义Tokenweight分词词典，可以根据报错WARNING: dictionary xx cannot be automatically exported, please create it manually手动创建对应分词词典。
- 普通用户不支持导出DIRECTORY、SYNONYM，若普通用户进行相关导出，会提示"WARNING: xx not dumped because current user is not a superuser"。需使用初始用户或SYSADMIN权限的用户进行导出。导出后执行导入需遵循语法本身的用户权限、操作约束，详情请参见[CREATE DIRECTORY](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0245.html)、 [CREATE SYNONYM](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0270.html)。
- 如果源数据库实例的template1中存在本地数据，请将gs_dump的输出恢复到一个真正的空数据库（从template0而非template1复制），否则可能会因为被添加对象的定义被复制，出现错误。创建一个无本地添加的空数据库，需从template0而非template1复制，例如：
  ```
  CREATE DATABASE foo WITH TEMPLATE template0;
  ```
  
- tar归档形式的单个文件大小不得超过8GB（tar文件格式的固有限制）。tar文档整体大小和任何其他输出格式没有限制，操作系统可能对此有要求。
- 由gs_dump生成的转储文件不包含优化程序用来做执行计划决定的统计数据。因此，建议从某转储文件恢复之后运行ANALYZE以确保最佳效果。转储文件不包含ALTER DATABASE...SET命令、数据库用户和其他完成安装设置，这些设置由gs_dumpall转储。
- gs_dump不导出失效函数，需要导出函数前请确保函数有效，失效的函数会打印告警，提示对应OID的函数失效。
- PACKAGE外的函数参数类型是表的列类型（table.column%type）或视图的列类型（view.column%type），且列类型是基础类型时，导出的函数定义中，参数类型会被转化为对应的基础类型。通过ALTER TABLE MODIFY COLUMN修改表的列类型并执行ALTER FUNCTION COMPILE，或者修改视图查询表的列类型后重建视图并执行ALTER FUNCTION COMPILE，PG_PROC系统表中该函数PROARGSRC字段中参数类型不会随之变化，导出的函数定义中，参数类型依然是对象列类型变更前的基础类型。
- gs_dump当前设计不兼容三权分立，三权分立下仅可通过初始用户使用gs_dump工具。导入的文件也需要通过初始用户执行。
- 当导出对象中包含触发器时，需要加上参数--use-set-session-authorization --all，并通过文本模式导出。否则恢复时无法准确还原触发器的owner信息。
- 使用gs_dump不会转储model对象。
- 使用系统管理员用户执行gs_dump导出时，不会导出初始用户创建的对象，初始用户创建的对象需要使用初始用户进行导出。使用普通用户执行gs_dump导出时，仅会导出owner归属于该普通用户的所有对象。
- 当导出对象中包含依赖PACKAGE内部函数的视图时，在首次导入目标端时会报视图依赖对象找不到的错误，此时需要使用gs_dump --schema-only备份元数据，并再次导入到目标端即可。
- 在使用gs_dump导出高级压缩库级策略定义时，需满足以下条件：必须执行全库导出操作且用户具备系统管理员权限。若上述条件未同时满足，则相关策略将以表、分区或子分区级别的独立策略形式导出，而非作为库级策略处理。
- gs_dump会把sequence的实际状态导出，其在恢复到目标端后，该sequence会继续上一次的状态。
- 对一些还未支持ustore老版本上导出的备份文件，在支持ustore的版本上恢复时，表会被创建为ustore格式且受ustore规格的限制，若想恢复为astore格式，需要设置enable_default_ustore_table为off。
- 使用gs_dump导出间隔分区表时，只能导出该分区表的range分区部分，不能导出该分区表的interval分区部分。对于该分区表上的分类索引，遵循同样的原则，即只能导出建立在range分区上的分类索引，不能导出interval分区上的分类索引。
- 当ddl_invalid_mode参数设置为invalid后，对函数和包做drop操作时，不会级联删除依赖其的对象，只是失效其依赖关系，即pg_depend系统表中仍然保有一条依赖关系记录；此时使用gs_dump进行备份时，会因为存在依赖关系但是找不到依赖的对象而报错cache lookup failed。需要修复依赖关系（重建依赖对象/删除被依赖对象）后进行导出。
- gs_dump默认会导出失效视图，如果导出的视图中有失效视图会打印提示，在507.0之前版本导入时可能会报错。可指定--ignore-invalid-views选项，不导出失效视图。
- gs_dump不导出rowid系统列上的数据，仅导出rowid作为数据类型时用户列的数据。
- 导出全文检索相关数据对象之后，如果导入的目标库没有对应的全文检索文件，或者导入导出时带上-c选项，则导入会失败。对于这类对象需要在目标库上创建后重试导入，或者导入导出时不指定-c选项。
- gs_dump导出视图时，若视图定义包含SELECT \* 且基表在视图创建后发生过列变更，则导出文件中的 \* 在目标库导入后会按目标表当前列结构重新展开。
- gs_redis重分布期间，gs_redis会以CANCELABLE模式加锁并主动向持有冲突锁的gs_dump线程发送SIGTERM，可能导致gs_dump导出被强制终止而失败。
- gs_dump导出的对象中包含用户视图时，请确保导出环境与恢复环境中的behavior_compat_options参数关于proc_outparam_override的配置保持一致，否则可能导入失败。
- gs_dump导出结果不包含所有会话参数设置等状态信息（如：behavior_compat_options等)，执行语句结果若依赖状态信息，在目标库导入时，需要原库和目标库的会话参数一致，否则可能报错或者数据不一致。
 
#### 命令格式
```
gs_dump [OPTION]... [DBNAME]
```
#### 参数说明
- DBNAME 指定要连接的数据库，前面不需要加短或长选项。例如：
  ```
  gs_dump -p port_number  testdb -f dump1.sql
  ```
  或者
  ```
  export PGDATABASE=testdb 
  gs_dump -p port_number -f dump1.sql
  ```
  DBNAME详细使用方式参见"gsql使用指导"中[表6](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0618.html#ZH-CN_TOPIC_0000002793706941__zh-cn_topic_0059779319_t5f35328143ec419983a1c23d13c46e49)。
  
- OPTION 分为三类，通用参数、转储参数和连接参数。
  通用参数：
  - -f, --file=FILENAME 将输出发送至指定文件或目录。如果省略该参数，则使用标准输出。如果输出格式为-F c、-F d或-F t时，必须指定-f参数。如果-f的参数值含有目录，要求当前用户对该目录具有读写权限。
    
  
  - -F, --format=c\|d\|t\|p 选择输出格式。格式如下：
    - c\|custom：输出一个自定义格式的归档，并且以目录形式输出，以此作为gs_restore的输入信息。该格式是最灵活的输出格式，因为可以手动选择，而且在恢复过程中可以将归档项重新排序。该格式默认状态下会被压缩。
    
    - d\|directory：该格式会创建一个目录，该目录包含两类文件，一类是目录文件，另一类是每个表和blob对象对应的数据文件。
    
    - t\|tar：输出一个tar格式的归档，作为gs_restore输入信息。tar格式与目录格式兼容，tar格式归档形式在提取过程中会生成一个有效的目录格式归档形式。tar格式不支持压缩且对于单独表有8GB的大小限制。此外，表数据项的相应排序在恢复过程中不能更改。
    
    - p\|plain：输出一个文本SQL脚本文件（默认）。
     
  
  - -v, --verbose 指定verbose模式。该选项将导致gs_dump向转储文件输出详细的对象注解和启动/停止次数，向标准错误流输出处理信息。
    
  
  - -V, --version 打印gs_dump版本，然后退出。
    
  
  - -Z, --compress=0-9 指定使用的压缩比级别。
    取值范围：0\~9
    - 0表示无压缩。
    
    - 1表示压缩比最小，处理速度最快。
    
    - 9表示压缩比最大，处理速度最慢。
    
    
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    - 针对自定义归档格式，该选项指定单个表数据片段的压缩，默认方式是以中等级别进行压缩。tar归档格式和纯文本格式目前不支持压缩。
    
    - 对于参数的取值，系统将取遇到的第一个非数字字符之前的部分。如果字符串以非数字字符开头，则取值为0。
      
  
  - --lock-wait-timeout=TIMEOUT 请勿在转储刚开始时一直等待以获取共享表锁（一级锁），如果不能在指定时间内锁定表，则选择失败。参数单位为ms（毫秒）。可以以任何符合SET statement_timeout的格式指定超时时间。
    整个导出过程中会一直持有这些锁，不会阻塞DML语句。
    
  
  - -?, --help 显示gs_dump命令行参数帮助，然后退出。
    
  
  - --ignore-invalid-views 指定该参数时，不会导出失效视图，导出时发现有失效视图会打印提示。
    
  
  
  转储参数：
  - -a, --data-only 只输出数据，不输出模式（数据定义）。转储表数据和序列值。
    
  
  - -b, --blobs 该参数为扩展预留接口，不建议使用。
    
  
  - -c, --clean 在将创建数据库对象的指令输出到备份文件之前，先将清理（删除）数据库对象的指令输出到备份文件中。如果目标数据库中没有任何对象，gsql或gs_restore工具可能会输出一些提示性的错误信息。
    该选项只对文本格式有意义。针对归档格式，可以在调用gs_restore时指定选项。
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    - 输出到备份文件中的删除数据库对象指令，均为非级联式删除的DROP命令。
    
    - 连接database1在t1时刻使用-c参数导出表table1到backup01.dmp文件，t2时刻在database1中创建视图view1并依赖table1，t3使用gs_restore的-c参数将backup01.dmp恢复到database1中时，因为会使用非级联删除，在删除table1时会报错"ERROR: table table cannot be dropped because other objects depend on it. "，并在创建table1时报错"ERROR: Relation "table1" already exists. "。此时需要用户在评估影响后，手动对相关依赖对象进行删除，或手动执行级联删除命令。
      
  
  - -C, --create 备份文件的内容以创建数据库和连接到该数据库的命令开始。如果命令脚本以这种方式执行，在运行脚本之前连接的是哪一个数据库都没有影响。
    该选项只对文本格式有意义。针对归档格式，可以在调用gs_restore时指定选项。
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    - 在M-Compatibility模式数据库下，不支持使用该选项。必须先在目标实例上创建出M-Compatibility模式数据库，然后在源实例上导出，最后在目标实例连接新创建的M-Compatibility模式数据库导入。
    
    - 在指定-n、-t或者--include-table-file之后，-C选项会失效。
      
  
  - -E, --encoding=ENCODING 以指定的字符集编码创建转储。默认情况下，以数据库编码创建转储。将环境变量"PGCLIENTENCODING"设置为所需的转储编码，也可以得到相同的结果。
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    当指定转储编码存在转码场景，且表中的数据存在非法编码的数据时，导出会报错invalid byte sequence，建议使用gs_dump的-s参数只导出定义，并单独使用COPY打开编码容错进行数据的导出与导入。
    
  
  - -g, --exclude-guc=GUC_PARAM 导出的文本文件中，不包括相关guc参数的set命令，目前只支持enable_cluster_resize，指定其他参数不会报错，但不会生效。
    
  
  - -j, --jobs=NUM 以指定的并行数进行导出。
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    - 不指定-j时，默认使用串行导出。
    
    - 指定的并行数不允许超过客户端CPU核数的两倍。当客户端运行在容器中时，由于获取到的是主机的CPU数量，可能比容器实际能使用的多，并发度建议由用户自行控制在实际能使用的客户端CPU数量的两倍范围内。表内并行导出通过多进程并发多个事务实现，实际并发度会受限于服务端的线程池模型，也同时会给服务端增加压力，请按照实际情况合理设置并发度，例如并发度不超过客户端空闲CPU数量，同时不超过服务端最大连接数限制等。建议并行数不低于4。
    
    - 并行导出仅支持目录归档格式。
    
    - 并行导出默认使用表内并行导出，即只导出一个表时，也可以对该表的数据拆分成多个导出任务，并行导出到多个文件中。可以通过同时指定--disable-inter-table-parallel参数关闭表内并行，当关闭表内并行导出时，并行导出是表级别的，即仅在导出多个表的表数据时，并行才会生效。
    
    - 表内并行导出后执行并行导入时，同表数据会放到一个事务中，即并行导入效率没有提升。
    
    - 并行导出与--inserts、--column-inserts、--attribute-inserts选项冲突。
    
    - 并行导出与--query选项冲突。
    
    - bucket表不支持表内并行导出。
    
    - 并行导出性能会受到压缩参数-Z的影响，建议合理设置压缩级别（默认中等压缩、或者设置为0即不压缩）。压缩级别越高，客户端CPU占用会越高，并存在客户端CPU抢占导致导出速度降低的情况。
    
    - 并行导出不支持在升级观察期使用。
    
    - 表内并行导出不支持在DN上使用；即仅允许在DN上同时指定-j和--disable-inter-table-parallel。
    
    - 分布式上并行导出存在一定的损耗。并行数较低时，并行优化效果不明显。
      
  
  - -n, --schema=SCHEMA 只转储与模式名称匹配的模式，此选项包括模式本身和所有它包含的对象。如果该选项没有指定，所有在目标数据库中的非系统模式将会被转储。支持写入多个-n选项来选择多个模式。此外，根据gsql的\\d命令所使用的相同规则，模式参数可以被理解为一个pattern，所以多个模式也可以通过在该pattern中写入通配符来选择。使用通配符时，注意给pattern打引号，防止shell扩展通配符。
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    - 当指定-n时，gs_dump不会转储已选模式所附着的任何其他数据库对象。因此，无法保证某个指定模式的转储结果能够自行成功地储存到一个空数据库中。
    
    - 当指定-n时，非模式对象不会被转储。
    
    - M-Compatibility模式数据库下， 通过CREATE DATABASE带templatem创建的数据库直接通过指定db_name导出数据； 而通过CREATE DATABASE db_name创建的DATABASE与SCHEMA等效，只能通过-n导出数据。
    
    - GaussDB会自动将对象名称中的大写字母转为小写，当模式名称中包含大写字母时，需要添加额外的引号，如：-n '"Sch1"' 或 -n "\\"Sch1\\""。
    
    - 当指定-n时，不支持通过pattern "\*"去匹配导出数据库中的系统SCHEMA。
     
    转储支持多个模式的转储。例如，以下示例中，sch1和sch2都会被转储。
    ```
    gs_dump -h host_name -p port_number testdb -f backup/bkp_shl2.sql -n sch1 -n sch2
    ```
    
  
  - -N, --exclude-schema=SCHEMA 不转储任何与模式pattern匹配的模式。Pattern将参照针对-n的相同规则来理解。可以通过输入多个-N，不转储与任何pattern匹配的模式。
    当同时输入-n和-N时，会转储与至少一个-n选项匹配、与-N选项不匹配的模式。如果有-N没有-n，则不转储常规转储中与-N匹配的模式。
    转储过程支持排除多个模式。例如，以下示例中，sch1和sch2在转储过程中都会被排除。
    ```
    gs_dump -h host_name -p port_number testdb -f backup/bkp_shl2.sql -N sch1 -N sch2
    ```
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    GaussDB会自动将对象名称中的大写字母转为小写，当模式名称中包含大写字母时，需要添加额外的引号，如：-N '"Sch1"' 或 -N "\\"Sch1\\""。
    
  
  - -o, --oids 转储每个表的对象标识符（OIDs），作为表的一部分数据。该选项用于以某种方式（例如：外键约束方式）参照了OID列的情况。如果不是以上这种情况，请勿使用该选项。不能与--inserts/--column-inserts选项一起使用。
    
  
  - -O, --no-owner 不输出设置对象的归属这样的命令，以匹配原始数据库。默认情况下，gs_dump会发出ALTER OWNER或SET SESSION AUTHORIZATION语句设置所创建的数据库对象的归属。脚本运行时这些语句会失败，除非是由系统管理员（或是拥有脚本中所有对象的同一个用户）触发。通过指定-O，可以生成一个任何用户都能用于恢复的脚本，且该脚本会授予该用户所有对象的权限。
    该选项只对文本格式有意义。针对归档格式，可以在调用gs_restore时指定选项。
    
  
  - -s, --schema-only
    只转储对象定义（模式），不转储数据。
    
  
  - -q, --target=VERSION 指定导出兼容其他版本数据库的文本文件，目前支持v1和v5参数，指定其他参数不会报错，但不会生效。v1参数用于导出GaussDB v5版本数据库的数据为兼容GaussDB v1版本数据库的文本文件。v5参数用于导出GaussDB v5版本数据库的数据为GaussDB v5版本数据库格式的文本文件，减少了导入GaussDB v5版本数据库时可能的报错情况。
    在使用v1参数时，建议同时设置--exclude-guc="enable_cluster_resize"，--exclude-function，--exclude-with等选项，否则导入到GaussDB v1版本数据库时可能报错。
    
  
  - -S, --sysadmin=NAME 该参数为扩展预留接口，不建议使用。
    
  
  - -t, --table=TABLE 指定转储的表（或视图、或序列、或外表）对象列表，可以使用多个-t选项来选择多个表，也可以使用通配符指定多个表对象。例如，以下示例中，schema1.table1和schema2.table2都会被转储。
    ```
    gs_dump -h host_name -p port_number testdb -f backup/bkp_shl2.sql -t schema1.table1 -t schema2.table2
    ```
    当使用通配符指定多个表对象时，注意给pattern打引号，防止shell扩展通配符。
    当使用-t时，-n和-N没有任何效果，因为由-t选择的表的转储不受-n、-N选项的影响。
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    - -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\\"。
    
    - -t "" 不匹配任何表。
    
    - 当-t参数中有多个"."分隔符时，实际上仅最后两个分隔符生效，倒数第二个和倒数第一个分隔符之间的名称即模式名，倒数第一个分隔符之后的名称即表名。例如-t schema_a.schema_b.schema_c.table1，实际上会导出模式schema_c的表table1；-t schema_a.schema_b.schema_c.\*.table1，实际上会导出所有模式下的表table1。
      
  
  - --include-table-file=FILENAME 指定需要dump的表文件。
    
  
  - -T, --exclude-table=TABLE 不转储的表（视图、序列、外表）对象列表，可以使用多个-T选项来选择多个表，也可以使用通配符指定多个表对象。
    当同时输入-t和-T时，会转储在-t列表中，而不在-T列表中的表对象。
    例如，以下示例中，table1和table2在转储过程中都会被排除。
    ```
    gs_dump -h host_name -p port_number testdb -f backup/bkp_shl2.sql -T table1 -T table2
    ```
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    对于自增列的序列，-T参数不会生效。
    
  
  - --exclude-table-file=FILENAME 指定不需要dump的表文件。
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    同--include-table-file，其内容格式如下：
    schema1.table1
    schema2.table2
    ......
    
  
  - -x, --no-acl 防止转储访问权限命令（授权/撤销命令），只影响acl对象，不影响privilege对象。
    
  
  - --exclude-function 不导出函数和存储过程。
    
  
  - --exclude-with 导出的表定义，末尾不添加WITH(orientation=row,compression=on)等描述。
    
  
  - --binary-upgrade 该参数为扩展预留接口，不建议使用。
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    M-Compatibility模式数据库不支持该选项。
    
  
  - --binary-upgrade-usermap="USER1=USER2" 该参数为扩展预留接口，不建议使用。
    
  
  - --column-inserts\|--attribute-inserts 以INSERT命令带列名（INSERT INTO表（列、...）值...）方式导出数据。这会导致恢复缓慢。但是由于该选项会针对每行生成一个独立分开的命令，所以在重新加载某行时出现的错误只会导致失败语句对应的数据丢失，而非整个表内容。
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    M-Compatibility模式数据库不支持该选项。
    
  
  - --disable-dollar-quoting 该选项将禁止在函数体前使用美元符号$，并强制使用SQL标准字符串语法对其进行引用。
    
  
  - --disable-inter-table-parallel 该选项仅在并行导出时生效，当指定该参数时，并行导出使用表级别的并行。
    
  
  - --include-alter-table 导出表删除列的相关步骤。
    
  
  - --disable-triggers 该参数为扩展预留接口，不建议使用。
    
  
  - --exclude-table-data=TABLE 指定不转储任何匹配pattern的表的数据。依照针对-t的相同规则理解该pattern。
    可多次输入--exclude-table-data来排除匹配任何pattern的表。当用户需要特定表的定义但不需要其中的数据时，该选项很有帮助。
    排除数据库中所有表的数据，参见[-s, --schema-only]。
    
  
  - --include-query-file=FILENAME 导出表内数据时通过该参数在文件内批量配置谓词过滤条件，通过增加过滤条件，只导出满足过滤条件的表数据。
    FILENAME中的内容支持如下格式，每个谓词条件之间以'\\n'换行分隔：
    1. \[schema_name.\]\[table_name:\] query_clause
    
    2. query=\[schema_name.\]\[table_name:\] query_clause
     
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    - 文件中以'#'开头的行会被当做注释行。
      
    
    - --include-query-file和--query可以同时使用，但是对于同一张表只能指定一个谓词条件。
    
    - 谓词条件其他规则请参见--query参数说明。
      
  
  - --inserts 发出INSERT命令（而非COPY命令）时转储数据，会导致恢复缓慢。
    但是，由于该选项会针对每行生成一个独立分开的命令，所以，重新加载某行时出现的错误只会导致对应的一行数据丢失，而非整个表内容。需要注意的是，如果重排列顺序，可能会导致恢复失败。列顺序改变时，--column-inserts选项不受影响。
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    M-Compatibility模式数据库不支持该选项。
    
  
  - --log-level=LOG\|DEBUG\|DEBUG1\|DEBUG2\|DEBUG3 该选项将指定gs_dump的日志级别。LOG记录正常执行信息，DEBUG记录一些调试信息。DEBUG数字越大，日志级别越高，记录的信息越详细。
    
  
  - --no-security-labels 该参数为扩展预留接口，不建议使用。
    
  
  - --no-tablespaces 不输出选择表空间的命令。若使用该选项，无论默认表空间是什么，在恢复过程中所有对象都会被创建。
    该选项只对文本格式有意义。针对归档格式，可以在调用gs_restore时指定选项。
    
  
  - --no-unlogged-table-data 该参数为扩展预留接口，不建议使用。
    
  
  - --non-lock-table 屏蔽gs_dump导出过程中对表加锁的行为。该参数仅供软件间接口调用，不推荐用户主动调用。
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    gs_dump导出table过程中，默认在整个事务内对要导出的table添加access share lock，此级别的锁会阻塞表上并发DDL语句的执行，保证导出表的过程中不会因对表并发DDL的影响而报错。
    
  
  - --query=\[schema_name.\]\[table_name:\]query_clause 导出表内数据时通过该参数支持谓词过滤，通过增加过滤条件，只导出满足过滤条件的表数据。
    其中query_clause是一个标准的以'where'开头的查询子句。
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    - 当多个表需要添加谓词过滤时，需要同时使用多个--query参数。
    
    - 可以同时指定多个query参数，但是对于同一张表只能指定一个query参数。
    
    - -t参数的优先级高于--query参数，同时使用-t与--query参数时，先按照-t参数过滤需要被导出的表的范围，再根据范围内的表进行谓词筛选。
    
    - --query参数仅对谓词进行拼接，不对谓词进行转义，需要转义时需要用户手动进行转义处理。
    
    - 使用的谓词应符合SQL标准且能被正确执行，否则数据导出时会报错。
    
    - 不支持对视图、物化视图指定谓词条件，否则数据导出时会报错。
    
    - 导出性能受谓词的查询性能影响。
    
    - --query参数中的where子句部分需要使用单引号或双引号进行包围，如果where子句中出现字符类型的过滤条件，则必须使用双引号进行包围。
      例如where子句中的过滤条件不是字符类型，可以使用单引号或双引号进行包围。
      ```
      --query=test_schema.test_table:'where test_attr > 3'
      --query=test_schema.test_table:"where test_attr > 3"
      ```
      例如where子句中的过滤条件是字符类型，必须使用双引号进行包围。
      ```
      --query=test_schema.test_table:"where test_attr = 'a'"
      ```
      
    
    - GaussDB会自动将对象名称中的大写字母转为小写，当schema_name、table_name或者query_clause中包含大写字母或特殊字符时，需要添加额外的引号。 例如Schema名称包含大写字符或特殊字符：
      ```
      --query="\"TEST_SCHEMA\"".test_table:"where test_attr > 3"
      ```
      例如谓词条件包含大写字符（列名有大写）：
      ```
      --query=test_schema.test_table:"where \"TEST_attr\" > 3"
      ```
      
      
  
  - --quote-all-identifiers 强制对所有标识符加引号。向后续版本迁移场景下，可能涉及引入额外关键词，使用该选项会有帮助。
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    M-Compatibility模式数据库不支持该选项。
    
  
  - --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命令的转储，如果转储文件中对象的历史有问题，可能不能正确恢复。并且，使用SET SESSION AUTHORIZATION的转储需要数据库系统管理员权限才能成功，而ALTER OWNER需要的权限比较低。此外，SET SESSION AUTHORIZATION部分支持直接使用密文密码，因此使用此参数导出的脚本可能无法正常恢复，不建议使用此参数导出。
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    SET SESSION AUTHORIZATION使用范围：
    - 系统管理员可以通过SET SESSION AUTHORIZATION语句切换到普通用户，无法切换到初始用户、其他sysadmin、opradmin、monadmin、poladmin和auditadmin。
    
    - 其他用户无法通过SET SESSION AUTHORIZATION语句切换用户。
      
  
  - --all 示本次gs_dump工具被gs_dumpall工具所调用。除了需要导出触发器场景之外，不建议使用此参数。
    
  
  - --with-copy-format=FILE_FORMAT 指定gs_dump导出的数据文件格式。
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    - FILE_FORMAT值为字符串类型，只允许输入TEXT和CSV格式，默认取值为TEXT格式。
    
    - 仅在目录归档模式下，支持FILE_FORMAT值为CSV格式。
    
    - 指定FILE_FORMAT值为CSV时，不支持与--inserts、--column-inserts、--attribute-inserts参数同时使用。
    
    - 使用目录归档模式进行导出后，必须使用gs_restore工具进行导入恢复，用户不需要关心导出的数据文件格式。若用户明确需要导出的数据文件格式为CSV，则可以指定--with-copy-format=CSV进行导出。
      
  
  - --with-encryption=AES128 指定转储数据用AES128进行加密。
    
  
  - --with-key=KEY AES128密钥规则如下：
    密钥长度为8\~16个字符。
    至少包含大写字母（A-Z），小写字母（a-z），数字（0-9），非字母数字字符（限定为\~!@#$%\^\&\*()-_=+\\\|\[{}\];:,\<.\>/?）四类字符中的三类字符。
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    不支持加密导出存储过程和函数。
    
  
  - --with-salt=RANDVALUES gs_dumpall使用此参数传递随机值。
    
  
  - --include-nodes 将TO NODE/TO GROUP语句包含在已转储的CREATE TABLE/CREATE FOREIGN TABLE语句中。
    
  
  - --include-extensions 在转储中包含扩展。
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/notice_3.0-zh-cn.png)
    扩展功能为内部使用功能，只允许操作数据库内部的高级包或扩展。
    
  
  - --include-depend-objs 备份结果包含依赖于指定对象的对象信息。该参数需要同-t/--include-table-file参数关联使用才会生效。
    
  
  - --exclude-self 备份结果不包含指定对象自身的信息。该参数需要同-t/--include-table-file参数关联使用才会生效。
    
  
  - --pipeline 使用管道传输密码，禁止在终端使用。
    
  
  - --no-transaction 默认情况（不开启该选项），导出的文件（纯文本格式）会为CREATE和ALTER ... OWNER TO、SET SESSION AUTHORIZATION和RESET SESSION AUTHORIZATION这类语句单独添加事务块。如果开启该选项，这些语句将直接输出，而不会被额外包裹在BEGIN/COMMIT中。
    
  
  - --dont-overwrite-file 文本、tar以及自定义格式情况下会重写现有文件。对目录格式不适用。
    例如：
    设想这样一种情景，即当前目录下backup.sql已存在。如果在输入命令中输入-f backup.sql选项时，当前目录恰好也生成backup.sql，文件就会被重写。
    如果备份文件已存在，且输入--dont-overwrite-file选项，则会报告附带'转储文件已经存在'信息的错误。
    ```
    gs_dump -p port_number testdb -f backup.sql -F plain --dont-overwrite-file
    ```
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    - -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一起使用。
    
    - --with-encryption=AES128仅支持-F p/plain。
    
    - --with-key=KEY仅支持-F p/plain。
    
    - --with-salt=RANDVALUES由gs_dumpall调用，不需要用户手动输入。
      
   
  连接参数：
  - -h, --host=HOSTNAME 指定主机名称。如果数值以斜杠开头，则被用作Unix域套接字的路径。缺省从PGHOST环境变量中获取（如果已设置）。
    该参数只针对集群外部连接，对集群内本机IPv4用127.0.0.1，IPv6用::1。
    
  
  - -p, --port=PORT 指定主机端口。在开启线程池情况下，建议使用pooler port，即主机端口+1。缺省从PGPORT环境变量中获取（如果已设置）。
    
  
  - -U, --username=NAME 指定所连接主机的用户名，跨节点执行不支持使用初始用户。缺省从PGUSER环境变量中获取（如果已设置）。
    ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    使用普通用户权限导出、普通用户权限导入时，在导入前需要给普通用户赋予对应数据库创建schema权限，如：GRANT CREATE ON DATABASE db_xxx TO user_xxx。
    
  
  - -w, --no-password 不出现输入密码提示。如果主机要求密码认证并且密码没有通过其他形式给出，则连接尝试将会失败。 该选项在批量工作和不存在用户输入密码的脚本中很有帮助。
    
  
  - -W, --password=PASSWORD 指定用户连接的密码。当主机的认证策略是trust时，不会对系统管理员进行密码验证，即无需输入-W选项；如果不加此参数且不是系统管理员，则会提示交互式输入。为了系统安全，推荐使用交互式输入密码方式。
    
  
  - --role=ROLENAME 指定创建转储使用的角色名。选择该选项，会使gs_dump连接数据库后，发起一个SET ROLE角色名命令。当所授权用户（由-U指定）没有gs_dump要求的权限时，该选项会起到作用，即切换到具备相应权限的角色。某些安装操作规定不允许直接以超系统管理员身份登录，而使用该选项能够在不违反该规定的情况下完成转储。
    
  
  - --rolepassword=ROLEPASSWORD 指定角色名的密码。
    
   
 
#### 示例
以下示例中，"backup/MPPDB_backup.sql"表示导出的文件，其中backup表示相对于当前目录的相对目录；"37300"表示数据库服务器端口；"testdb"表示要访问的数据库名。
![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
导出操作时，请确保该目录存在并且当前的操作系统用户对其具有读写权限。
**示例一**
执行gs_dump，导出testdb数据库全量信息，导出的MPPDB_backup.sql文件格式为纯文本格式。
```
gs_dump -U omm -f backup/MPPDB_backup.sql -p 37300 testdb -F p
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 09:49:17]: The total objects number is 356.
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 09:49:17]: [100.00%] 356 objects have been dumped.
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 09:49:17]: dump database testdb successfully
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 09:49:17]: total time: 1274  ms
```
**示例二**
执行gs_dump，导出testdb数据库全量信息，导出的MPPDB_backup.tar文件格式为tar格式。
```
gs_dump -U omm -f backup/MPPDB_backup.tar -p 37300 testdb -F t
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 10:02:24]: The total objects number is 1369.
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 10:02:53]: [100.00%] 1369 objects have been dumped.
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 10:02:53]: dump database testdb successfully
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 10:02:53]: total time: 50086  ms
```
**示例三**
执行gs_dump，导出testdb数据库全量信息，导出的MPPDB_backup.dmp文件格式为自定义归档格式。
```
gs_dump -U omm -f backup/MPPDB_backup.dmp -p 37300 testdb -F c
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 10:05:40]: The total objects number is 1369.
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 10:06:03]: [100.00%] 1369 objects have been dumped.
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 10:06:03]: dump database testdb successfully
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 10:06:03]: total time: 36620  ms
```
**示例四**
执行gs_dump，导出testdb数据库全量信息，导出的MPPDB_backup文件格式为目录格式。
```
gs_dump -U omm -f backup/MPPDB_backup -p 37300  testdb -F d
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 10:16:04]: The total objects number is 1369.
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 10:16:23]: [100.00%] 1369 objects have been dumped.
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 10:16:23]: dump database testdb successfully
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 10:16:23]: total time: 33977  ms
```
**示例五**
执行gs_dump，导出testdb数据库信息，但不导出/home/MPPDB_temp.sql中指定的表信息。导出的MPPDB_backup.sql文件格式为纯文本格式。
```
gs_dump -U omm -p 37300 testdb --exclude-table-file=/home/MPPDB_temp.sql -f backup/MPPDB_backup.sql
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 10:37:01]: The total objects number is 1367.
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 10:37:22]: [100.00%] 1367 objects have been dumped.
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 10:37:22]: dump database testdb successfully
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-27 10:37:22]: total time: 37017  ms
```
**示例六**
执行gs_dump，仅导出依赖于指定表testtable的视图信息。
```
gs_dump -U omm -s -p 37300 testdb -t PUBLIC.testtable --include-depend-objs --exclude-self -f backup/MPPDB_backup.sql -F p
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-15 14:12:54]: The total objects number is 331.
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-15 14:12:54]: [100.00%] 331 objects have been dumped.
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-15 14:12:54]: dump database testdb successfully
gs_dump[user='omm'][localhost][port='37300'][testdb][2018-06-15 14:12:54]: total time: 327  ms
```
#### 相关工具
[gs_dumpall导出所有数据库信息](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0701.html)，[gs_restore导入数据](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0702.html)，[gsql连接数据库](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0617.html)