vb_dumpall

工具介绍

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

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

vb_dumpall在导出Vastbase所有数据库时分为两部分：

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

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

注意事项

vb_dumpall工具由安装Vastbase数据库的操作系统用户执行。
vb_dumpall工具在进行数据导出时，其他用户可以访问Vastbase数据库（读或写）。
由于vb_dumpall内部调用vb_dump，所以一些诊断信息可以参考vb_dump。
vb_dumpall仅支持纯文本格式导出，所以只能使用vsql工具恢复此工具导出的转储内容。
成功恢复后，建议在每个数据库上运行ANALYZE，优化程序提供有用的统计数据。
vb_dumpall恢复前需要所有必要的表空间目录为空；否则，对于处在非默认位置的数据库，数据库创建会失败。（可以通过vsql工具的\db元命令列出所有可用的表空间。）
不支持导出数据库中的定时任务。
vb_dumpall工具在进行数据导出时生成的列不会被转储。
为了保证数据一致性和完整性，vb_dumpall会对需要转储的表设置共享锁。如果某张表在别的事务中设置了共享锁，vb_dumpall会等待此表的锁释放后锁定此表。如果无法在指定时间内锁定某张表，转储会失败。用户可以通过指定--lock-wait-timeout选项，自定义等待锁超时时间。
由于vb_dumpall读取所有数据库中的表，因此必须以Vastbase管理员身份进行连接，才能导出完整文件。在使用vsql执行脚本文件导入时，同样需要管理员权限，以便添加用户和组以及创建数据库。

命令格式

vb_dumpall [OPTION]...

常用参数：

General options:
  -f, --file=FILENAME                         output file name
  -v, --verbose                               verbose mode
  -V, --version                               output version information, then exit
  --lock-wait-timeout=TIMEOUT                 fail after waiting TIMEOUT for a table lock
  -?, --help                                  show this help, then exit

控制转储内容的参数包括：

Options controlling the output content:
  -a, --data-only                             dump only the data, not the schema
  -c, --clean                                 clean (drop) databases before recreating
  -g, --globals-only                          dump only global objects, no databases
  -o, --oids                                  include OIDs in dump
  -O, --no-owner                              skip restoration of object ownership
  -r, --roles-only                            dump only roles, no databases or tablespaces
  -s, --schema-only                           dump only the schema, no data
  -S, --sysadmin=NAME                         system admin user name to use in the dump
  -t, --tablespaces-only                      dump only tablespaces, no databases or roles
  -x, --no-privileges                         do not dump privileges (grant/revoke)
  --column-inserts/--attribute-inserts        dump data as INSERT commands with column names
  --disable-dollar-quoting                    disable dollar quoting, use SQL standard quoting
  --disable-triggers                          disable triggers during data-only restore
  --inserts                                   dump data as INSERT commands, rather than COPY
  --no-publications                           do not dump publications
  --no-security-labels                        do not dump security label assignments
  --no-tablespaces                            do not dump tablespace assignments
  --no-subscriptions                          do not dump subscriptions
  --no-unlogged-table-data                    do not dump unlogged table data
  --include-alter-table                       dump the table delete column
  --quote-all-identifiers                     quote all identifiers, even if not key words
  --dont-overwrite-file                       do not overwrite the existing file
  --use-set-session-authorization             use SET SESSION AUTHORIZATION commands instead of
                                              ALTER OWNER commands to set ownership
  --with-encryption=AES128/SWS-KMS-SM4/TAS-KMS-SM4
                                              dump data is encrypted using AES128 or SWS-KMS-SM4 or TAS-KMS-SM4
  --with-key=KEY                              encryption key, AES128 key must be 16 bytes in length, SWS-KMS-SM4 key must be
                                              greater than 0 in length, if use TAS-KMS-SM4,the key means index of encryption key
  --with-userpin=username:password            used to connect to seckms server
  --include-extensions                        include extensions in dumpall
  --include-templatedb                        include dumping of template database also
  --pipeline                                  use pipeline to pass the password,
                                              forbidden to use in terminal
  --binary-upgrade                            for use by upgrade utilities only
  --binary-upgrade-usermap="USER1=USER2"      to be used only by upgrade utility for mapping usernames
  --non-lock-table                            for use by OM tools utilities only
  --tablespaces-postfix                       to be used only by upgrade utility for adding the postfix name specified for all the tablespaces
  --parallel-jobs                             number of parallel jobs to dump databases

连接参数包括：

Connection options:
  -h, --host=HOSTNAME                         database server host or socket directory
  -l, --database=DBNAME                       alternative default database
  -p, --port=PORT                             database server port number
  -U, --username=NAME                         connect as specified database user
  -w, --no-password                           never prompt for password
  -W, --password=PASSWORD                     the password of specified database user
  --role=ROLENAME                             do SET ROLE before dump
  --rolepassword=ROLEPASSWORD                 the password for role

参数说明

通用参数

-f, --filename=FILENAME：

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

--parallel-jobs和-f/--filename必须同时使用。
-v, --verbose

开启冗长模式。该选项将导致vb_dumpall向转储文件输出详细的对象注解和启动/停止次数，向标准错误流输出处理信息。
-V, --version

打印vb_dumpall版本，然后退出。
--lock-wait-timeout=TIMEOUT

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

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

转储参数

-a, --data-only

只转储数据，不转储模式（数据定义）。
- 该选项不能和-s/--schema-only同时使用。
- 该选项不能和-r/--roles-only同时使用。
- 该选项不能和-t/--tablespaces-only同时使用。
- 该选项不能和-g/--globals-only同时使用。
-c, --clean

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

只转储全局对象（角色和表空间），无数据库。
- 该选项和-a/--data-only不能同时使用。
- 该选项和-r/--roles-only不能同时使用。
- 该选项和-t/--tablespaces-only不能同时使用。
-o, --oids

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

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

只转储角色，不转储数据库或表空间。
- 该选项和-g/--globals-only不能同时使用。
- 该选项和-t/--tablespaces-only不能同时使用。
- 该选项和-a/--data-only不能同时使用。
-s, --schema-only

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

该选项和-a/--data-only不能同时使用。
-S, --sysadmin=NAME

该参数为扩展预留接口，不建议使用。
-t, --tablespaces-only

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

该选项和-a/--data-only不能同时使用。
-x, --no-privileges

防止转储访问权限（授权/撤销命令）。
--column-inserts|--attribute-inserts

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

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

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

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

不转储发布。
--no-security-labels

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

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

不转储订阅。
--no-unlogged-table-data

不转储未记录的表数据。

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

导出表中已删除的列信息。
--quote-all-identifiers

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

不重写当前文件。

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

例如：设想这样一种情景，即当前目录下backup.sql已存在。如果再次备份导出backup.sql文件时，文件就会被重写。

如果备份文件已存在，且输入--dont-overwrite-file选项，则会报告错误信息“转储文件已经存在”。
--use-set-session-authorization

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

指定转储数据使用的加密方式（算法）。支持AES128/SWS-KMS-SM4/TAS-KMS-SM4。
- 该选项必须与--with-key同时使用。
- 当加密方式为SWS-KMS-SM4时，必须与--with-userpin同时使用。
--with-key=KEY

密钥名称或者密钥索引。
- AES128密钥规则如下：
  - 密钥长度为8~16个字符。
  - 至少包含大写字母（A-Z），小写字母（a-z），数字（0-9），非字母数字字符（限定为~!@#$%^&*()-_=+|[{}];:,<.>/?）四类字符中的三类字符。
- 加密算法为TAS-KMS-SM4时，--with-key指定的是江南天安KMS上创建的密钥索引，Vastbase限制其索引范围必须是1 ~ 2048。
- 加密算法为SWS-KMS-SM4时，--with-key指定的是三未信安KMS上创建的密钥名称。
--with-userpin=username:password

连接seckms加密服务器的username:password信息。
--include-extensions

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

转储过程中包含模板库。
--pipeline

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

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

--binary-upgrade-usermap和--binary-upgrade必须一起使用。
--binary-upgrade-usermap=“USER1=USER2”

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

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

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

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

--parallel-jobs和-f/--file必须同时使用。

连接参数

-h, --host=HOSTNAME

指定主机的名称。如果取值是以斜线开头，它将用作Unix域套接字的目录。默认值取自PGHOST环境变量；如果没有设置，将启动某个Unix域套接字建立连接。该参数只针对Vastbase外，对Vastbase内本机只能用127.0.0.1。

环境变量：$PGHOST
-l, --database=DATABASE

指定所连接的转储全局对象的数据库名称，并去寻找还有其他哪些数据库需要被转储。如果没有指定，会使用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选项，并且不是系统管理员，会提示用户输入密码。
--role=ROLENAME

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

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

示例

示例1： 使用vb_dumpall一次导出Vastbase的所有数据库。

备份命令如下：

vb_dumpall -f backup_all.sql -p 5432

备份成功，打印信息如下：

vb_dump[port='5432'][dbname='postgres'][2023-03-22 12:17:10]: The total objects number is 447.
vb_dump[port='5432'][dbname='postgres'][2023-03-22 12:17:10]: [100.00%] 447 objects have been dumped.
vb_dump[port='5432'][dbname='postgres'][2023-03-22 12:17:10]: dump database dbname='postgres' successfully
vb_dump[port='5432'][dbname='postgres'][2023-03-22 12:17:10]: total time: 1386  ms
vb_dump[port='5432'][dbname='vastbase'][2023-03-22 12:17:11]: The total objects number is 447.
vb_dump[port='5432'][dbname='vastbase'][2023-03-22 12:17:11]: [100.00%] 447 objects have been dumped.
vb_dump[port='5432'][dbname='vastbase'][2023-03-22 12:17:11]: dump database dbname='vastbase' successfully
vb_dump[port='5432'][dbname='vastbase'][2023-03-22 12:17:11]: total time: 1317  ms
vb_dumpall[port='5432'][2023-03-22 12:17:11]: dumpall operation successful
vb_dumpall[port='5432'][2023-03-22 12:17:11]: total time: 2769  ms

示例2： 使用vb_dumpall备份时指定-c，将清理这些数据库（对象）的语句输出到备份文件的开头。表示在恢复该文件时，先执行SQL语句清理这些数据库（对象），再重新创建数据库。

1、使用vsql工具连接至vastbase数据库。

vsql -d vastbase -p 5432 -r

2、创建测试表并插入一条数据。

create table student(stdno int,student_age char(20),grade float8);
insert into student values(001,'15.00',81.00);

3、退出vsql程序。

\q

4、执行备份命令。

vb_dumpall -f bak_all.sql -p 5432 -c