gs_dumpall
背景信息
gs_dumpall是GaussDB用于导出所有数据库相关信息工具,它可以导出集群数据库的所有数据,包括默认数据库postgres的数据、自定义数据库的数据、以及集群所有数据库公共的全局对象。
gs_dumpall工具在进行数据导出时,其他用户可以访问集群数据库(读或写)。
gs_dumpall工具支持导出完整一致的数据。例如,T1时刻启动gs_dumpall导出整个集群数据库,那么导出数据结果将会是T1时刻该集群数据库的数据状态,T1时刻之后对集群数据库的修改不会被导出。
gs_dumpall在导出整个集群所有数据库时分为两部分:
- gs_dumpall自身对所有数据库公共的全局对象进行导出,包括有关数据库用户和组,表空间以及属性(例如,适用于数据库整体的访问权限)信息。
- gs_dumpall通过调用gs_dump来完成集群中各数据库的SQL脚本文件导出,该脚本文件包含将数据库恢复为其保存时的状态所需要的全部SQL语句。
以上两部分导出的结果为纯文本格式的SQL脚本文件,使用gsql运行该脚本文件可以恢复集群数据库。
gs_dumpall支持SSL加密通信,使用方式同gsql方式。
使用gs_dumpall前请确保gs_dumpall版本与gs_dump版本、数据库版本保持一致,高版本gs_dumpall不保证完全兼容低版本内核数据。
注意事项
- 禁止修改导出的文件和内容,否则可能无法恢复成功。
- 为了保证数据一致性和完整性,gs_dumpall会对需要转储的表设置共享锁。如果某张表在别的事务中设置了共享锁,gs_dumpall会等待此表的锁释放后锁定此表。如果无法在指定时间内锁定某张表,转储会失败。用户可以通过指定--lock-wait-timeout选项,自定义等待锁超时时间。
- 由于gs_dumpall读取所有数据库中的表,因此必须以数据库集群管理员身份进行连接,才能导出完整文件。在使用gsql执行脚本文件导入时,同样需要管理员权限,以便添加用户和组,以及创建数据库。导入备份前,验证其安全性,防止管理员权限被利用。
- 使用gs_dumpall导出所有数据库对象,并希望在新的实例环境上进行导入时,需要保证导出和导入时使用用户的名称和权限相同,否则会出现名称不一致或权限不足的报错。
- 对于定时任务,本工具仅支持导出在MYSQL兼容性数据库中,通过CREATE EVENT创建的定时任务或通过高级包创建的非周期性定时任务。
- gs_dumpall不支持导出自定义Tokenweight分词词典,可以根据报错WARNING: dictionary xx cannot be automatically exported, please create it manually手动创建对应分词词典。
- 由于M-compatibility模式数据库全局只能创建一个,当导出的数据库中包含M-compatibility模式数据库时,须保证导入的目标实例环境上不存在其他的M-compatibility模式数据库。
- 当指定转储编码存在转码场景时,且表中的数据存在非法编码的数据,导出会报错invalid byte sequence,建议使用gs_dump的-s参数只导出定义,并单独使用COPY打开编码容错进行数据的导出与导入。
语法
gs_dumpall [OPTION]...
参数说明
通用参数:
- -f, --filename=FILENAME
- -v, --verbose
指定verbose模式。该选项将导致gs_dumpall向转储文件输出详细的对象注解和启动/停止次数,向标准错误流输出处理信息。
- -V, --version
- --lock-wait-timeout=TIMEOUT
请勿在转储刚开始时一直等待以获取共享表锁。如果无法在指定时间内锁定某个表,就选择失败。可以以任何符合SET statement_timeout的格式指定超时时间。
- -?, --help
转储参数:
- -a, --data-only
- -c, --clean
- -g, --globals-only
- -o, --oids
转储每个表的对象标识符(OIDs),作为表的一部分数据。该选项用于应用以某种方式参照了OID列的情况。如果不是以上这种情况,请勿使用该选项。
- -O, --no-owner
不输出设置对象的归属这样的命令,以匹配原始数据库。默认情况下,gs_dumpall会发出ALTER OWNER或SET SESSION AUTHORIZATION语句设置所创建的模式元素的所属。如果脚本正在运行,该语句不会执行成功,除非是由系统管理员触发(或是拥有脚本中所有对象的同一个用户)。通过指定-O,编写一个任何用户都能存储的脚本,且该脚本会授予该用户拥有所有对象的权限,因为没有使用ALTER OWNER或SET SESSION AUTHORIZATION语句,导入时一直使用执行用户权限,所以在导入前请确认转储文件内是否存在风险。例如,检查转储文件中是否包含提权语句,且该语句管理员是否知晓。
- -r, --roles-only
- -s, --schema-only
- -S, --sysadmin=NAME
- -t, --tablespaces-only
- -x, --no-privileges
- --column-inserts|--attribute-inserts
以INSERT命令带列名(INSERT INTO表(列、…)值…)方式导出数据。这会导致恢复缓慢。但是由于该选项会针对每行生成一个独立分开的命令,所以在重新加载某行时出现的错误只会导致失败语句对应的数据丢失,而非整个表内容。
M-Compatibility模式数据库不支持该选项,导出M-Compatibility模式数据库时会忽略该选项。
- --disable-dollar-quoting
- --disable-triggers
- --inserts
发出INSERT命令(而非COPY命令)时转储数据。这会导致恢复缓慢。注意如果重排列顺序,可能会导致恢复整个失败。--column-inserts选项更加安全,虽然可能更慢些。
M-Compatibility模式数据库不支持该选项,导出M-Compatibility模式数据库时会忽略该选项。
- --no-security-labels
- --no-tablespaces
请勿输出创建表空间的命令,也请勿针对对象选择表空间。使用该选项,无论默认表空间是哪一个,在恢复过程中所有对象都会被创建。
- --no-unlogged-table-data
- --include-alter-table
- --quote-all-identifiers
强制对所有标识符加引号。为了向后续版本迁移,且其中可能涉及引入额外关键词,在转储相应数据库时该选项会有帮助。
M-Compatibility模式数据库不支持该选项,导出M-Compatibility模式数据库时会忽略该选项。
- --dont-overwrite-file
- --use-set-session-authorization
输出符合SQL标准的SET SESSION AUTHORIZATION命令而不是ALTER OWNER命令来确定对象所有权。这样令转储更加符合标准,但是如果转储文件中的对象的历史有些问题,那么可能不能正确恢复。并且,使用SET SESSION AUTHORIZATION的转储需要数据库系统管理员的权限才能转储成功,而ALTER OWNER需要的权限则低得多。但是SET SESSION AUTHORIZATION部分支持使用密文密码随意切换用户及权限,因为使用此参数导出的脚本可能无法正常恢复,不建议使用此参数导出。
SET SESSION AUTHORIZATION使用范围:
- 系统管理员可以通过SET SESSION AUTHORIZATION语句切换到普通用户,无法切换到初始用户、其他sysadmin、opradmin、monadmin、poladmin和auditadmin。
- 其他用户无法通过SET SESSION AUTHORIZATION语句切换用户。
- --with-encryption=AES128
- --with-key=KEY
密钥长度为8~16个字符。
至少包含大写字母(A-Z),小写字母(a-z),数字(0-9),非字母数字字符(限定为~!@#$%^&*()-_=+\|[{}];:,<.>/?)四类字符中的三类字符。
- --include-extensions
如果include-extensions参数被设置,将备份所有的CREATE EXTENSION语句。
扩展功能为内部使用功能,不建议用户使用。
- --include-templatedb
- --dump-nodes
- --include-nodes
- --include-buckets
- --dump-wrm
存储过程中包含负载资源管理器,具体包括资源池、负载组以及负载组映射。
连接M-Compatibility模式数据库进行导出时,不支持该选项。
- --binary-upgrade
M-Compatibility数据库不支持该选项,导出M-Compatibility数据库时会忽略该选项。
- --binary-upgrade-usermap="USER1=USER2"
- --non-lock-table
- --tablespaces-postfix
- --parallel-jobs
- --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必须一起使用。
连接参数:
- -h, --host=HOSTNAME
指定主机的名称。如果取值是以斜线开头,它将用作Unix域套接字的目录。默认值取自PGHOST环境变量;如果没有设置,将启动某个Unix域套接字建立连接。
该参数只针对集群外,对集群内本机IPv4用127.0.0.1,IPv6用::1。
环境变量:PGHOST
- -l, --database=DATABASENAME
指定所连接的转储全局对象的数据库名称,并去寻找还有其他哪些数据库需要被转储。如果没有指定,会使用postgres数据库,如果postgres数据库不存在,会使用template1。
无论指定哪一个数据库作为导出时连接的数据库,在新实例环境上使用gsql工具进行导入时,必须连接默认数据库,否则可能出现语法不兼容的情况,导致导入异常。特别地,如果错误地连接M-Compatibility模式数据库进行导入时,由于M-compatibility模式数据库下CREATE DATABASE与CREATE SCHEMA效果等价,会导致创建失败。
- -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_dumpall连接数据库后,发起一个SET ROLE角色名命令。当所授权用户(由-U指定)没有gs_dumpall要求的权限时,该选项会起到作用,即切换到具备相应权限的角色。某些安装操作规定不允许直接以系统管理员身份登录,而使用该选项能够在不违反该规定的情况下完成转储。
- --rolepassword=ROLEPASSWORD
说明
- 由于gs_dumpall内部调用gs_dump,所以一些诊断信息参见gs_dump。
- 一旦恢复,建议在每个数据库上运行ANALYZE,优化程序提供有用的统计数据。
- gs_dumpall恢复前需要所有必要的表空间目录为空;否则,对于处在非默认位置的数据库,数据库创建会失败。
示例
使用gs_dumpall一次导出集群的所有数据库。
gs_dumpall仅支持纯文本格式导出。所以只能使用gsql恢复gs_dumpall导出的转储内容。
gs_dumpall -U omm -f backup/bkp2.sql -p 37300 gs_dump[user='omm'][localhost][port='37300'][dbname='testdb'][2018-06-27 09:55:09]: The total objects number is 2371. gs_dump[user='omm'][localhost][port='37300'][dbname='testdb'][2018-06-27 09:55:35]: [100.00%] 2371 objects have been dumped. gs_dump[user='omm'][localhost][port='37300'][dbname='testdb'][2018-06-27 09:55:46]: dump database dbname='testdb' successfully gs_dump[user='omm'][localhost][port='37300'][dbname='testdb'][2018-06-27 09:55:46]: total time: 55567 ms gs_dumpall[user='omm'][localhost][port='37300'][2018-06-27 09:55:46]: dumpall operation successful gs_dumpall[user='omm'][localhost][port='37300'][2018-06-27 09:55:46]: total time: 56088 ms 其中:backup/bkp2.sql表示导出的文件,37300表示数据库服务器端口,omm为用户名。