#yasrman使用指导

# 查看帮助

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

$ yasrman -h

# 命令格式

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

user/password/host/port

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

Note：

仅BACKUP、RESTORE、DELETE语句会与DB发生数据交互的语句需DBA角色才可执行。 用户名，密码和IP仅在上述三种语法中才会校验其连接正确性，其他语句不与数据库交互，不会进行校验，只是为了保持命令格式统一。

command

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

catalog_path

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

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

# command-创建catalog

command
CREATE CATALOG

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

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

Note：

catalog文件文件包含记录备份集元数据信息的二进制文件，不可手动删除。若发生删除或者更换catalog路径等异常操作，可能导致无法使用yasrman恢复其包含的备份集、无法查看备份集信息等异常情况。 catalog并不绑定某个具体的数据库，但是建议为不同的数据库创建独立的catalog文件。 yasrman不支持catalog的备份和恢复，用户可以手动拷贝catalog目录进行备份，拷贝catalog时需要保证yasrman没有工作。 catalog备份集元数据信息与DB的系统表元数据信息不会自动同步，若发生过catalog迁移、重建等操作可能出现备份指定tag已存在报错。

示例

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

# command-配置config

command
configure parameter_name parameter_value

执行本命令将所配置的内容持久化到catalog的config.ini文件中，在后续的备份和恢复过程中，如果没有显示指定配置，将按照config.ini里的配置。

Note：

配置参数命令优先级：backup或restore命令指定的参数 > configure命令配置的参数 > 默认参数。

# PARALLELISM

command
configure PARALLELISM integer CLEAR

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

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

示例

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

$ yasrman sys/sys@192.168.1.2: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@192.168.1.2:1688 -c 'configure COMPRESSION ALGORITHM lz4' -D /home/yashan/catalog
$ yasrman sys/sys@192.168.1.2:1688 -c 'configure COMPRESSION LEVEL HIGH' -D /home/yashan/catalog

$ yasrman sys/sys@192.168.1.2:1688 -c 'configure COMPRESSION ALGORITHM clear' -D /home/yashan/catalog
$ yasrman sys/sys@192.168.1.2: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@192.168.1.2:1688 -c 'configure section size 128M' -D /home/yashan/catalog

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

# DEST

command
configure DEST CLIENT SERVER CLEAR

指定备份集的存储位置，client表示存储到工具端（备份集会保存在yasrman所在服务器），server表示备份到数据库主机端（备份集会保存在数据库所在服务器）。不指定时默认为server。

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

示例

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

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

# command-SHOW ALL

command
SHOW ALL

执行本命令将列出在config.ini中已经配置的备份参数。因为这些参数的优先级低于备份恢复语句中指定的参数，所以并不代表一定是执行备份时所使用的参数值。

示例

$ yasrman sys/sys@192.168.1.2: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）的备份集默认存储在catalog/backup文件夹下。

Note：

分布式集群中存在几个节点部署在同一服务器时，FORMAT建议使用相对路径，而不是绝对路径，否则可能出现路径冲突的问题，导致备份失败。

# PARALLELISM

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

# SECTION SIZE

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

# DEST

指定备份集的存储位置，client表示存储到工具端（备份集会保存在yasrman所在服务器），server表示备份到数据库主机端（备份集会保存在数据库所在服务器）。不指定时默认为server。

Note：

对分布式集群备份时，不可指定为client，即只能备份到数据库所在服务器。 增量备份时，同一基线的备份命令的DEST选项都需要与基线保持一致，即同一组增量备份集要么都在工具端，要么都在主机端，否则备份恢复的时候，可能找不到基线备份集而报错。 备份时指定的DEST和恢复时指定的DEST建议保持一致。

示例

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

$ yasrman sys/sys@192.168.1.2:1688 -c "backup database incremental level 0 compression encryption aes128 identified by 123456 format 'incr_base' tag 'incr_base' dest server;" -D /home/yashan/catalog

$ yasrman sys/sys@192.168.1.2:1688 -c "backup database incremental level 1 compression algorithm lz4 encryption aes128 identified by 123456 format 'incr_1' tag 'incr_1' dest server;" -D /home/yashan/catalog

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

$ yasrman sys/sys@192.168.1.2:1688 -c "backup cluster incremental level 0 compression format 'cluster_incr_base' tag 'cluster_incr_base';" -D /home/yashan/catalog

$ yasrman sys/sys@192.168.1.2:1688 -c "backup cluster incremental level 1 compression algorithm zstd format 'cluster_incr_1' tag 'cluster_incr_1';" -D /home/yashan/catalog

# PARAMS

该命令用于对接第三方备份软件，指定XBSA接口的配置参数，进行远程流式备份。格式如下： PARAMS '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@192.168.1.2: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@192.168.1.2: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@192.168.1.2: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 FROM TAG tag_name DECRYPTION password PARALLELISM integer PARAMS xbsa_parameter UNTIL SCN integer TIME time_string

使用本命令与RESTORE DATABASE语句所执行操作类似，但是和基于SQL的restore命令不同的是，在恢复备份集后，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@192.168.1.2:1688 -c "restore database from tag 'full_1'" -D /home/yashan/catalog

##分布式
$ yasrman sys/sys@192.168.1.2: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@192.168.1.2: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@192.168.1.2: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参数。 不支持分布式集群备份。

# UNTIL TIME

该语句用于将数据库恢复到此指定的时间点，time_string必须是时间格式的字符串， 格式需与TIMESTAMP_FORMAT参数定义的格式一致。

指定的时间点必须在备份集生成时间之后。

# UNTIL SCN

该语句用于将数据库恢复到此指定的SCN号。指定的SCN号必须大于备份集中记录的SCN号。

示例（单机部署）

##单机
### 指定时间戳
$ yasrman sys/sys@192.168.1.2:1688 -c "restore database from tag 'full_1' until time '2023-11-13'" -D /home/yashan/catalog

$ yasrman sys/sys@192.168.1.2:1688 -c "restore database from tag 'full_1' until time '2023-11-13 18:55:00'" -D /home/yashan/catalog

$ yasrman sys/sys@192.168.1.2:1688 -c "restore database from tag 'full_1' until time '2023-11-13 18:54:32:657892'" -D /home/yashan/catalog

### 指定SCN
$ yasrman sys/sys@192.168.1.2:1688 -c "restore database from tag 'full_1' until scn 499833430256541696" -D /home/yashan/catalog

Note：

  1. 最小时间点是保证数据库恢复到一致性的时间点，该时间点对应与备份完datafile，开始备份归档时的SCN对应的时间点，略小于备份完成时间。
  2. 如果归档日志不够，或者指定的时间点（或SCN）过大，回放完毕后也达不到指定的时间点，数据库会报错，用户可以查询V$DATABASE的current_scn来查看实际回放进度。如果有可用的归档日志副本，可以注册归档，重新执行restore操作。如果没有多余的归档，当前时间点是唯一的选择，继续执行resetlogs操作。
  3. 分布式不支持指定时间点恢复。

# command-备份集管理

# 查看备份集

command
LIST BACKUP TAG tag_name

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

示例

$ yasrman sys/sys@192.168.1.2: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: 192.168.1.2:1688, nodeCount: 1, distribution: FALSE, isClient: TRUE, offset: 0
    backup path: /home/yashan/catalog/backup/full_bak_1

Note：

list命令仅列出指定的catalog文件中存在的备份集元数据信息，因为catalog不会与数据库自动同步备份元信息，可能与数据库中DBA_BACKUP_SET视图内容不同。

# 删除备份集

command
DELETE BACKUPSET IF EXISTS TAG tag_name

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

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

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

Note：

如果删除过程中断，可能出现部分节点的备份集已删除，但是剩余节点备份集和TAG还存在的情况，此时可以通过重新执行删除命令，继续删除。 如果catalog中存在备份集元信息，但是数据库中没有记录元信息，不加IF EXISTS删除备份集可能报错，请使用IF EXISTS来删除备份集。 仅使用该语句才可同时删除catalog和系统表中的备份集信息。

下载文档
复制链接

段落导航

查看帮助
命令格式
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
UNTIL TIME
UNTIL SCN
command-备份集管理
查看备份集
删除备份集