search-icon search-icon

#yasrman使用指导

# 查看帮助

使用yasrman -h命令可查看帮助信息。

$ yasrman -h

# 命令格式

yasrman <user>/<password>@<host>:<port> -c <command> [-D <catalog_path>]

user/password/host/port

指向CN节点（分布式部署）或者主机节点（单机部署）的连接信息，支持远程TCP连接及本地UDS连接，user需为拥有DBA角色的有效数据库用户。

Note：

仅BACKUP、RESTORE、DELETE语句会与DB发生数据交互的语句需DBA角色才可执行。 用户名密码参数仅在上述三种语法中才会校验其连接正确性。

command

具体的命令语句，见下文描述。

catalog_path

指定catalog路径，必须指定为绝对路径。-D命令省略时，catalog_path默认为当前路径。

当command为创建catalog时，catalog_path必须为一个新路径用于创建；当command为其他时，catalog_path必须为一个已存在的catalog路径。

# command-创建catalog

command
CREATE CATALOG

本命令将根据-D选项指定的路径和名称创建一个catalog文件夹，未指定时在当前路径下创建一个名称为catalog的文件夹。若文件夹已存在，本命令报错。

首次使用yasrman进行备份恢复前，必须使用本命令创建catalog。

Note：

catalog文件为记录备份集元数据信息的二进制文件，不可手动删除。若发生删除或者更换catalog路径等异常操作，可能导致无法使用yasrman恢复其包含的备份集、无法查看备份集信息等异常情况。

示例

$ yasrman sys/sys@127.0.0.1:1688 -c 'create catalog' -D /home/yashan/catalog

# command-配置config

command
configure parameter_name parameter_value

执行本命令将所配置的内容持久化到catalog的config.ini文件中。

Note：

配置参数命令优先级：默认值 < configure命令 < backup命令。

# PARALLELISM

command
configure PARALLELISM integer CLEAR

指定每个节点执行多线程备份恢复的并行度，其中integer见开发手册BACKUP DATABASE中PARALLELISM语句描述。

指定CLEAR时，config.ini文件的PARALLELISM参数值被置为默认值。

示例

$ yasrman sys/sys@127.0.0.1:1688 -c 'configure PARALLELISM 3' -D /home/yashan/catalog

$ yasrman sys/sys@127.0.0.1:1688 -c 'configure PARALLELISM clear' -D /home/yashan/catalog

# COMPRESSION

command
configure COMPRESSION ALGORITHM LZ4 ZSTD CLEAR LEVEL LOW MEDIUM HIGH CLEAR

指定生成备份集的压缩算法，ALGORITHM及LEVEL同开发手册BACKUP DATABASE中COMPRESSION语句描述。

为ALGORITHM指定CLEAR时，config.ini文件的COMPRESSION_ALGORITHM参数值被置为NULL，表示关闭压缩选项。

为LEVEL指定CLEAR时，config.ini文件的COMPRESSION_LEVEL参数值被置为默认值。

示例

$ yasrman sys/sys@127.0.0.1:1688 -c 'configure COMPRESSION ALGORITHM lz4' -D /home/yashan/catalog
$ yasrman sys/sys@127.0.0.1:1688 -c 'configure COMPRESSION LEVEL HIGH' -D /home/yashan/catalog

$ yasrman sys/sys@127.0.0.1:1688 -c 'configure  COMPRESSION ALGORITHM clear' -D /home/yashan/catalog
$ yasrman sys/sys@127.0.0.1:1688 -c 'configure  COMPRESSION LEVEL clear' -D /home/yashan/catalog

# SIZE

command
configure SECTION SIZE size_clause CLEAR

指定生成备份集的压缩算法，size_clause同开发手册BACKUP DATABASE中SECTION SIZE语句描述。

指定CLEAR时，config.ini文件的SECTION_SIZE参数值被置为默认值。

示例

$ yasrman sys/sys@127.0.0.1:1688 -c 'configure section size 128M' -D /home/yashan/catalog

$ yasrman sys/sys@127.0.0.1:1688 -c 'configure section size clear' -D /home/yashan/catalog

# DEST

指定为增量备份时，如果yasrman工具和目标DB安装部署不在同一机器，同一基线的备份命令的DEST选项都需要与基线保持一致，否则会导致备份失败。

command
configure DEST CLIENT SERVER CLEAR

指定备份集的存储位置，client表示存储到工具端，server表示备份到数据库主机端。不指定时默认为server。

指定CLEAR时，config.ini文件的DEST参数值被置为默认值。

示例

$ yasrman sys/sys@127.0.0.1:1688 -c 'configure DEST SERVER' -D /home/yashan/catalog

$ yasrman sys/sys@127.0.0.1:1688 -c 'configure DEST clear' -D /home/yashan/catalog

# command-SHOW ALL

command
SHOW ALL

执行本命令将列出在config.ini中已经配置的备份参数，这些参数可以在备份语句中实时指定，所以并不代表一定是执行备份时所使用的参数值。

示例

$ yasrman sys/sys@127.0.0.1:1688 -c 'show all' -D /home/yashan/catalog
+---------------------------+-----------+----------------+
|           NAME            |  DEFAULT  |      VALUE     |
+---------------------------+-----------+----------------+
| PARALLELISM               | 2         | 2              |
| SECTION SIZE              | 134217728 | 134217728      |
| COMPRESSION ALGORITHM     | NONE      | NONE           |
| COMPRESSION LEVEL         | LOW       | LOW            |
| DEST                      | SERVER    | SERVER         |
+---------------------------+-----------+----------------+

# command-备份

command
BACKUP CLUSTER DATABASE TAG tag_name FULL INCREMENTAL LEVEL integer CUMULATIVE COMPRESSION ALGORITHM ZSTD LZ4 LOW MEDIUM HIGH ENCRYPTION AES128 AES192 AES256 SM4 IDENTIFIED BY password FORMAT backup_path PARALLELISM integer SECTION SIZE size_clause DEST server client PARAMS xbsa_parameter

成功执行本命令完成备份的前提是，所有节点上的数据库为OPEN状态，且已开启归档。

对于启用了HA的分布式数据库，在部署时已打开归档开关，但对于非HA的分布式数据库，默认安装时归档开关为可选项，用户需注意此时应该增加该开关设置，否则后续无法执行备份。

如在初始安装时未增加归档开关设置，在执行备份前，用户需登录至每一节点，将该节点数据库切换至MOUNT状态，打开归档，然后再打开数据库。

# CLUSTER

使用本关键字表示对分布式集群中的所有CN节点、DN主节点和MN主节点发起备份。

分布式集群包含多个节点，执行过程中任何一个节点备份出现异常时，所有节点备份都将失败，本命令抛出错误。

# DATABASE

使用本关键字表示对单机数据库的主机节点发起备份。

# TAG

同开发手册BACKUP DATABASE中TAG语句定义及描述。

# FULL

同开发手册BACKUP DATABASE中FULL语句定义及描述。

# INCREMENTAL LEVEL

同开发手册BACKUP DATABASE中INCREMENTAL LEVEL语句定义及描述。

# COMPRESSION

同开发手册BACKUP DATABASE中COMPRESSION语句定义及描述。

# ENCRYPTION

同开发手册BACKUP DATABASE中ENCRYPTION语句定义及描述。

# FORMAT

同开发手册BACKUP DATABASE中FORMAT语句定义及描述。

当format未指定路径时，采用如下默认路径：

  • 备份在主机端（dest server）的备份集默认存储在$YASDB_DATA/backup文件夹下。
  • 备份在工具端（dest client）的备份集默认存储在/home/yashan/catalog/backup文件夹下。

Note：

分布式集群中存在几个节点部署在同一服务器时，建议使用相对路径，否则可能出现路径冲突的问题。 catalog备份集元数据信息与DB的系统表元数据信息并非完全同步，若发生过catalog迁移、重建等操作可能出现备份指定tag已存在报错。

# PARALLELISM

同开发手册BACKUP DATABASE中PARALLELISM语句定义及描述。

# SECTION SIZE

同开发手册BACKUP DATABASE中SECTION SIZE语句定义及描述。

Note：

请按照实际数据文件大小选择合适的分片大小，假设当前DB中单个数据文件最大大小为MAXSIZE，建议分片大小应该小于(MAXSIZE/(PARALLELISM*2))，且建议最大不超过4G，其中PARALLELISM为备份指定的并行度，可有效提高备份效率。

# DEST

指定备份集的存储位置，client表示存储到工具端，server表示备份到数据库主机端。不指定时默认为server。

Note：

对分布式集群备份时，不可指定为client。 指定为增量备份时，如果yasrman工具和目标DB安装部署不在同一机器，同一基线的备份命令的DEST选项都需要与基线保持一致，否则会导致备份失败。

示例

##单机
$ yasrman sys/sys@127.0.0.1:1688 -c "backup database tag 'full_1' format 'full_bak_1'" -D /home/yashan/catalog

##分布式
$ yasrman sys/sys@127.0.0.1:1688 -c "backup cluster tag 'full_1' format 'full_bak_1'" -D /home/yashan/catalog

# PARAMS

该语句用于进行远程流式备份，指定XBSA接口的配置参数，格式如下： 'XBSA_LIBRARY=xbsa_library_path, TOKEN=token_value, ENV=(key1=val1,key2=val2,...)'

  1. xbsa_library_path：XBSA动态链接库的绝对路径，目前仅支持linux的动态链接库。
  2. token_value：BSAInit接口的token入参。
  3. keyX, valX: BSAInit接口env入参，所有key-value对的最大总长度要小于4096。

示例

$ yasrman sys/sys@127.0.0.1:1688 -c "backup database tag 'xbsa_full_1' dest client params 'XBSA_LIBRARY=/home/yashan/lib/libxbsa.so, TOKEN=157257815837, ENV=(BSA_SERVICE_HOST=192.168.1.1:1601,BSA_BACKUP_UUID=yashan1234561)'" -D /home/yashan/catalog
$ yasrman sys/sys@127.0.0.1:1688 -c "backup database tag 'xbsa_incr_0' incremental level 0 compression algorithm lz4 dest client params 'XBSA_LIBRARY=/home/yashan/lib/libxbsa.so, TOKEN=157257815837, ENV=(BSA_SERVICE_HOST=192.168.1.1:1601,BSA_BACKUP_UUID=yashan1234562)'" -D /home/yashan/catalog
$ yasrman sys/sys@127.0.0.1:1688 -c "backup database tag 'xbsa_incr_1' incremental level 1 dest client params 'XBSA_LIBRARY=/home/yashan/lib/libxbsa.so, TOKEN=157257815837, ENV=(BSA_SERVICE_HOST=192.168.1.1:1601,BSA_BACKUP_UUID=yashan1234563)'" -D /home/yashan/catalog

Note：

必须指定DEST CLIENT参数。 FORMAT参数将被忽略。 不支持分布式集群备份。

# command-恢复

command
RESTORE CLUSTER DATABASE DECRYPTION password FROM TAG tag_name PARALLELISM integer PARAMS xbsa_parameter

使用本命令与RESTORE DATABASE语句所执行操作类似，不同的是，在恢复备份集后，yasrman会继续open主机，如存在备机会build备机，所以本命令完成后整个数据库包括HA集群即可正常使用。

成功执行本命令完成恢复的前提是，所有节点上实例的数据文件目录、归档文件目录、bucket目录已清空，并启动至NOMOUNT状态。

对于分布式集群，可使用yasboot clean的--restore选项完成上述前提要求，具体请参考yasboot中cluster clean命令描述。

Warn：

请务必使用cluster clean --restore，而非cluster clean，未带--restore选项的clean命令将会完全清除节点上的DATA目录且无法被恢复，如在BACKUP CLUSTER命令中使用了备份集的缺省路径，则位于DATA目录中的备份集也将被清除。

# CLUSTER

使用本关键字表示对分布式集群执行恢复。

# DATABASE

使用本关键字表示对单机数据库执行恢复。

# TAG

指定执行恢复的备份集别名。

# DECRYPTION

该语句用于指定备份集恢复时解密，此时需要同时指定解密密码。

# PARALLELISM

该语句用于指定多线程恢复的并行度，该值范围[1, 8]，省略时默认为2。

示例

##单机
$ yasrman sys/sys@127.0.0.1:1688 -c "restore database from tag 'full_1'" -D /home/yashan/catalog

##分布式
$ yasrman sys/sys@127.0.0.1:1688 -c "restore cluster from tag 'full_1'" -D /home/yashan/catalog

# PARAMS

该语句用于进行流式备份集的恢复，指定XBSA接口的配置参数，格式如下： 'XBSA_LIBRARY=xbsa_library_path, TOKEN=token_value, ENV=(key1=val1,key2=val2,...)'

  1. xbsa_library_path：XBSA动态链接库的绝对路径，目前仅支持linux的动态链接库。
  2. token_value：BSAInit接口的token入参。
  3. keyX, valX: BSAInit接口env入参，所有key-value对的最大总长度要小于4096。

示例

$ yasrman sys/sys@127.0.0.1:1688 -c "restore database from tag 'xbsa_full_1' dest client params 'XBSA_LIBRARY=/home/yashan/lib/libxbsa.so, TOKEN=157257815837, ENV=(BSA_SERVICE_HOST=192.168.1.1:1601,BSA_BACKUP_UUID=yashan1234561)'" -D /home/yashan/catalog
$ yasrman sys/sys@127.0.0.1:1688 -c "restore database from tag 'xbsa_incr_0' dest client params 'XBSA_LIBRARY=/home/yashan/lib/libxbsa.so, TOKEN=157257815837, ENV=(BSA_SERVICE_HOST=192.168.1.1:1601,BSA_BACKUP_UUID=yashan1234562)'" -D /home/yashan/catalog

Note：

必须指定DEST CLIENT参数。 不支持分布式集群备份。

# command-备份集管理

# 查看备份集

command
LIST BACKUP TAG tag_name

通过指定备份集别名查看所有节点上的该备份集信息，不指定TAG时将展示所有节点上的所有备份集。

示例

$ yasrman sys/sys@127.0.0.1:1688 -c "list backup tag 'full_1'" -D /home/yashan/catalog
Group: tag: full_1, format: /home/yashan/catalog/backup/full_bak_1, connect url: 127.0.0.1:1688, nodeCount: 1, distribution: FALSE, isClient: TRUE, offset: 0
    backup path: /home/yashan/catalog/backup/full_bak_1

Note：

list命令仅列出指定的catalog文件中存在的备份集元数据信息，与DB中DBA_BACKUP_SET视图内容并非完全同步。

# 删除备份集

command
DELETE BACKUPSET IF EXISTS TAG tag_name

删除指定TAG对应的备份集，本操作的前提是分布式集群或单机主机处于正常运行状态。

指定的tag_name不存在时，本命令报错。 指定IF EXISTS表示不论tag_name是否存在都返回删除成功。示例

$ yasrman sys/sys@127.0.0.1:1688 -c "DELETE BACKUPSET tag 'full_1'" -D /home/yashan/catalog

Note：

如果删除过程中断，可能出现部分节点的备份集已删除，但是剩余节点备份集和TAG还存在的情况，此时可以通过重新执行该命令，继续删除。 仅使用该语句才可一致性删除catalog和系统表中的备份集信息。

pdf-btn 下载文档
copy-btn 复制链接
段落导航
查看帮助
命令格式
command-创建catalog
command-配置config
PARALLELISM
COMPRESSION
SIZE
DEST
command-SHOW ALL
command-备份
CLUSTER
DATABASE
TAG
FULL
INCREMENTAL LEVEL
COMPRESSION
ENCRYPTION
FORMAT
PARALLELISM
SECTION SIZE
DEST
PARAMS
command-恢复
CLUSTER
DATABASE
TAG
DECRYPTION
PARALLELISM
PARAMS
command-备份集管理
查看备份集
删除备份集