#BUILD DATABASE

# 通用描述

BUILD DATABASE用于在主备高可用部署环境中，在备库上创建standby数据库，有关主备高可用架构的详细操作描述请参考高可用。

在存在级联备的环境中，级联备库的上级备库对应为下文中的主库，级联备库对应为下文中的备库，具有与主备库相同的语法、功能及约束。

主库端BUILD命令仅SYS超级用户或拥有SYSDBA、SYSBACKUP权限的用户才可执行。

该语句仅适用于单机和共享集群部署。

对备库成功执行本语句的前提是：

主库数据库已OPEN，并处于归档模式。
备库已安装数据库软件，且启动实例到NOMOUNT状态（增量BUILD中的备库须为OPEN状态）。
主备库上网络及权限畅通，相关配置参数值已正确设置。
满足CREATE DATABASE语句的所有约束条件。

本语句涵盖了YashanDB需要进行BUILD操作的各种场景：

全量BUILD：用于新建或重建备库的初始化
- 由备库分别对自身发起BUILD（BUILD DATABASE）：适用于单机、共享集群部署
- 由主库向备库发起BUILD（BUILD DATABASE TO STANDBY指定单个standby_name或BUILD DATABASE TO REMOTE指定单个IP）：适用于单机、共享集群部署
- 由主库向多备库同时发起BUILD（BUILD DATABASE TO STANDBY或BUILD DATABASE TO REMOTE）：适用于单机部署
- 由备库向多备库同时发起BUILD（BUILD DATABASE TO REMOTE）：适用于单机部署
增量BUILD：用于异常备库的快速修复
- 由主库向存在gap的备库发起BUILD（BUILD DATABASE INCREMENTAL TO STANDBY或BUILD DATABASE INCREMENTAL TO REMOTE）：适用于单机部署
- 由备库向存在gap的备库发起BUILD（BUILD DATABASE INCREMENTAL TO REMOTE）：适用于单机部署
- 由主库向need repair的备库发起BUILD（BUILD DATABSE REPAIR STANDBY）：适用于单机部署

本语句执行过程中，可以通过V$BACKUP_PROGRESS视图查询某个BUILD操作的进度。若BUILD中断或失败，需注意：

由于执行本语句时，系统会将主库（或者某个备库）的控制文件、数据文件、redo日志文件和归档日志文件在线传输至备库的对应目录，过程中若出现错误将报错并中断操作，已传输的文件不会自动清除，再次运行本语句前，需在备库上手动清除脏数据。
对于同时发起的多备库并行BUILD，当某一个备库BUILD操作失败时，所有的备库BUILD操作都将失败。

# 语句定义

build database::=

语法图

代码

syntax

# build database

该语句后面无任何选项时，表示本操作在备库上执行，将主库服务器文件在线传输到备库服务器。

示例（单机、共享集群部署）

--在某个备库上执行
BUILD DATABASE;

# build database to standby

本操作一般在主库上执行，用于指定多个不同备库，将主库服务器文件同时在线传输到这些备库服务器。

在共享集群部署中执行本操作时，只能指定1个备集群。

standby_name

指定备库的DB_UNIQUE_NAME（通过V$ARCHIVE_DEST视图获得该值），在一个HA集群中，DB_UNIQUE_NAME唯一标识了一台备库服务器。

多个standby_name之间以 , 分隔，且不可以重复。

指定与该主库连接的所有的备库。

示例（单机部署）

-- 指定对应的备库DB_UNIQUE_NAME执行BUILD。
BUILD DATABASE TO STANDBY (standby1_name, standby2_name);

-- 指定 * 符号即为该主库的所有备库执行BUILD。
BUILD DATABASE TO STANDBY (*);

示例（共享集群部署）

-- 指定对应的备集群DB_UNIQUE_NAME执行BUILD。
BUILD DATABASE TO STANDBY (standby1_name);

# build database to remote

本操作可以在主库或备库上执行，用于指定多个不同IP，将本机服务器文件同时在线传输到这些服务器。

当某个备库出现异常时，为避免影响主库的业务，可以在一个正常同步备库上执行本语句，通过指定IP地址在线传输服务器文件到异常备库进行修复。

在共享集群部署中执行本操作时，只能指定1个备集群。

standby_address

指定备库的IP地址，需为address:port格式的一个有效地址，例如127.0.0.1:1689。

多个standby_name之间以,指定，且不可以重复。

YashanDB支持指定一个未与主库建立复制链路的IP地址，此时主库仍可以连接该备库且执行BUILD操作（由于未建立链路，该备库只是创建standby库，而不会加入HA集群），但需遵循该主库所处HA集群环境的一切限制，例如指定的IP个数不能超过备库最大限制数量。

示例（单机部署）

BUILD DATABASE TO REMOTE ('127.0.0.1:2901', '127.0.0.1:2902');

示例（共享集群部署）

BUILD DATABASE TO REMOTE ('127.0.0.1:2901');

# build database incremental to standby

当备库与主库间存在较大gap时，在主库上通过standby_name指定备库执行本语句可以快速修复异常备库，缩小主备之间的差距。

本操作每次只能指定一个备库，且指定的备库必须是一个正常open状态的备库（通过V$REPLICATION_STATUS视图查看备库的状态）。

Caution：

本操作会自动重启备库，清理控制文件，且BUILD过程中备库处于非open状态，谨慎使用。

如操作过程中途失败，只能对备库进行全量BUILD修复。

示例（单机部署）

BUILD DATABASE INCREMENTAL TO STANDBY standby1_name;

# build database incremental to remote

当备库与主库间存在较大gap时，在主库上通过standby_address指定备库执行本语句可以快速修复异常备库，缩小主备之间的差距。

为了避免影响主库的业务，也可以在某个正常的同步备库或者主备差距较小的备库上执行本语句。

本操作每次只能指定一个IP地址（通过standby_address指定），且指定的备库必须是一个正常open状态的备库（通过V$REPLICATION_STATUS视图查看备库的状态）。

Caution：

本操作会自动重启备库，清理控制文件，且BUILD过程中备库处于非open状态，谨慎使用。

如操作过程中途失败，只能对备库进行全量BUILD修复。

示例（单机部署）

BUILD DATABASE INCREMENTAL TO REMOTE '127.0.0.1:1689';

# build databse repair standby

当某个备库为need repair状态（通过V$REPLICATION_STATUS视图查看备库的状态）时，在主库上通过standby_name指定备库执行本语句可以快速修复异常备库。

本操作每次只能指定一个备库，且指定的备库必须是某些异常类型（通过V$REPLICATION_STATUS视图查看备库的异常类型）的need repair状态，例如主库归档被清理等，其他的异常只能通过全量BUILD修复，更详细的描述请查看高可用手册备库异常修复。

示例（单机部署）

BUILD DATABASE REPAIR STANDBY standby1_name;

# parallelism integer

指定build database操作的并行度，integer的取值范围为[1,16]，默认的并行度为4。

# disconnect from session

本选项表示不需要等待BUILD操作完成之后再返回succeed，此时BUILD操作由后台线程完成，用户的会话线程不会阻塞。不指定本选项表示用户会话等待BUILD操作完成之后才返回succeed。

示例（单机部署）

BUILD DATABASE TO STANDBY (standby1_name, standby2_name) DISCONNECT FROM SESSION;

示例（共享集群部署）

--在主集群上执行
BUILD DATABASE TO STANDBY (standby1_name) DISCONNECT FROM SESSION;