1.4 db.xml
db.xml包含具体的数据库组和实例配置,可以配置多组，每组可以配置多个实例
1.4.1 dbGroup配置
- dbGroup
| 配置名称 | 配置内容&示例 | 可选项/默认值 | 详细描述 |
|---|---|---|---|
| name | 节点名称 | 必需项，无默认值 | dbGroup的唯一标识，不允许重复 |
| rwSplitMode | 读操作的负载均衡模式 | 必需项，无默认值，候选值0/1/2/3 | 在进行读负载均衡的时候会根据这个配置进行 0：不做均衡，直接分发到主实例，从实例将被忽略,不会尝试建立连接池，但会有心跳连接 1：读操作在所有从实例中均衡，当所有从实例都不可用时，下发语句会报错。 2：读操作在所有实例中均衡。 3：读操作在所有从实例中均衡，当所有从实例都不可用时，将语句发往主实例。 具体拓扑结构见负载均衡相关章节 |
| delayThreshold | 指定主从延迟阀值，单位毫秒 | 默认-1，表示无延迟 | 1:在进行读取负载均衡的时候会根据最近一次的心跳状态以及读库和主库的延迟进行判断，如果主从复制不工作或者复制延迟超过delayThreshold配置，则认为此节点不适合进行读取，依赖于心跳为show slave status 2:不依赖于心跳语句，通过和delayPeriodMillis参数，delayDatabase参数一起使用，实现延迟检测，具体可参考delay_detection章节 3:此配置会影响到进行读负载均衡的时候延迟检测的开启，如果delayThreshold=-1那么读负载均衡选取的时候不会进行延迟检测 4:如果配置了delayPeriodMillis参数和delayDatabase参数，那么1中的延时检测失效，2中的延迟检测生效 |
| delayPeriodMillis | 指定主从延迟检测周期，单位毫秒 | 默认-1，表示不启用 | 延迟检测周期，需要和delayThreshold和delayDatabase一起使用生效 |
| delayDatabase | 指定延时检测时mysql中的database | 默认null,表示不配置 | 延时检测需要向mysql写入sql，所以需要提供mysql的database，来确定往哪里写入，需要和delayThreshold和delayPeriodMillis一起使用生效 |
| disableHA | 是否禁用该组的高可用切换 | 可配置true/false，默认false | 禁用该组的高可用切换，可能在某些场景下需要 |
| heartbeat | 子元素,心跳语句 | 必选项 | 该配置会在服务启动时设置的心跳任务里面被使用到，用于进行mysql实例状态的判断. 该配置有以下几种建议值: 1.普通心跳只是用于探活，建议使用select 1 2.使用 select @@read_only 探测结点可用性以及可写性 3.使用show slave status,可以探活，检查复制是否正常，以及延迟检测。如果Seconds_Behind_Master返回的状态有延迟，那么会被记入mysql实例的主从延迟中，影响读请求的路由分发，延迟超过指定限制读写分离会变为只读主库。 |
| dbInstance | 子元素，表示组下的实例，可配置多个 | 空 | 具体的物理节点配置 |
- heartbeat
| 配置名称 | 配置内容&示例 | 可选项/默认值 | 详细描述 |
|---|---|---|---|
| timeout | heartbeat子元素,心跳超时阈值，单位：秒 | 默认0 | 心跳超时阈值。前置知识：dble会按照 heartbeatPeriodMillis 的间隔向 dbInstance 发送心跳
心跳发起时候检会查上次心跳是否为不正常的心跳,如果上次心跳尚未返回，并且距离最近的正常心跳的时间大于timeout，则标记该结点不可达。 例如:心跳周期(heartbeatPeriodMillis)2秒，第一次心跳正常，2s后的第二次心跳未返回，4s后第三次心跳发起时候发现上次不正常，不会真的再次下发，而是会根据4s和timeout的大小来确定该节点是否真正超时(该节点使用时候才会真正用到） 如果未超时，则什么也不做，继续下一个周期。如果超时了，则尝试杀掉超时的连接，无论是否杀成功，都会在下一个周期换一个连接继续做心跳，极端情况下会消耗很多连接 2. 心跳连续返回失败后，dble使用该结点时，会检查距离第一次失败的时间差，如果大于timeout，则报该结点不可达。 |
| errorRetryCount | heartbeat子元素,心跳失败后的尝试次数 | 默认1，0表示不重试 | 心跳失败/心跳连接被关闭后,开始重试errorRetryCount次。 1. 心跳失败重试期间，连接池状态为error状态，一旦重试成功，则标记回OK。(目的：防止网络抖动或者连接异常断开场景) 2. 心跳连接被关闭重试期间，连接池状态为ok状态，只有都重试失败后才会置为error状态 3. 重试期间超时，按照超时逻辑处理。 |
| keepAlive | heartbeat子元素,心跳发送后的等待响应时间 | 默认60秒 | dble会按照heartbeatPeriodMillis的间隔向dbInstance发送心跳,发起心跳检查的时候会检查心跳连接是否可用,如果当前检查心跳连接的时间大于(上次心跳返回的正常心跳的时间+heartbeatPeriodMillis+keepAlive)的值，则杀掉该连接，在下一个周期换一个连接继续做心跳。 例如：心跳周期(heartbeatPeriodMillis)10秒，第一次心跳正常，记录心跳返回的时间为13：10：00，接下来的心跳一直没有正常返回，当第九次心跳检测时，当前时间为13：11：20，大于（13：10：00 + 10s + 60s），则认为该连接不可用，则杀掉该连接， 在下一个周期换一个连接继续做心跳。 |
- dbInstance
| 配置名称 | 配置内容&示例 | 可选项/默认值 | 详细描述 |
|---|---|---|---|
| name | 写节点名称 | 空 | 节点名称作为标识 |
| id | id | 默认值为name对应的值 | id标识 |
| url | 写节点地址ip:port | 空 | 被分成IP和PORT用于连接数据库 |
| user | 写节点用户 | 空 | 用于连接数据库 |
| password | 写节点用户密码 | 空 | 用于连接数据库 |
| usingDecrypt | 是否启用加密password | 候选值false/true,默认值false | 如果设置为true，password属性值应该为用工具encrypt.sh加密串 1:{name}:{user}:{password} 得到的串 |
| minCon | 空闲时，保有的最小后端连接数 | 必需项 | 后端连接池中空闲时维持的最小连接数量，即常驻连接数。 实际工作中，minCon不得小于当前dbGroup实际用到的shardingNode的个数（别名 numOfShardingNodes），如果启动时发现minCon小于 numOfShardingNodes 会被调整为 numOfShardingNodes。 |
| maxCon | 最大后端连接数 | 必需项 | 后端连接池最大允许的连接数量。 实际工作中，maxCon不得小于当前dbGroup实际用到的shardingNode的个数（别名 numOfShardingNodes）, 也不得小于 minCon ，如果启动时发现 maxCon 小于 这两个值 会被调整为 这两个值的最大值（即 numOfShardingNodes 和 minCon 当中的最大值）。 如果连接耗尽,将无法下发请求并返回报错。 |
| readWeight | 节点权重(负载均衡时候使用) | 默认不配置表示所有节点等量负载 | 负载均衡过程中会查看所有节点的权重是否相等，如果不相等，那么就会根据权重来配置压力。
该值需是大于等于 0 的整数。如果配为0表示该节点不参与读. 需注意，总权重（所有节点权重之和）必须大于 0。 |
| primary | 主实例需要配置成true | false | 用来标识主节点 |
| disabled | 标记改实例不可用 | false | 高可用切换时候可能会用到 |
| databaseType | 数据库实例类型 | 默认不配置,表示后端数据库为mysql | 后端数据库实例为mysql时，可填写mysql，后端数据库实例为clickhouse时，可填写clickhouse,其余值不支持。
+ 值为mysql时，仅支持shardingUser和rwSplitUser使用， + 值为clickhouse时，支持analysisUser用户以及涉及apNode的hybridTAUser用户使用, 同个dbGroup下的dbInstance需要保证databaseType的值相同 + 知识补充：clickHouse默认大小写敏感且不可更改；因此当db.xml中有效的clickHouse配置时，意味者db.xml中所有mysql实例的lower_case_table_names值必须均为0，否则启动失败 |
| property | 连接池属性 | 空 | 具体的后端连接池属性 |
| dbDistrict | 后端mysql实例所在区域 | 空 | 读写分离本地读场景下读流量转发依据，该参数会和bootstrap.cnf中的district参数匹配 |
| dbDataCenter | 后端mysql实例所在数据中心 | 空 | 读写分离本地读场景下读流量转发依据，该参数会和bootstrap.cnf中的dataCenter参数匹配 |
property
举例如下:
<?xml version="1.0"?>
<dble:db xmlns:dble="http://dble.cloud/">
<dbGroup name="dbGroup1" rwSplitMode="1" delayThreshold="10000">
<heartbeat errorRetryCount="1" timeout="10" keepAlive="60">show slave status</heartbeat>
<dbInstance name="instanceM1" url="ip4:3306" user="your_user" password="your_psw" maxCon="200" minCon="50" primary="true">
<property name="testOnCreate">false</property>
<property name="testOnBorrow">false</property>
<property name="testOnReturn">false</property>
<property name="testWhileIdle">true</property>
<property name="connectionTimeout">30000</property>
<property name="connectionHeartbeatTimeout">20</property>
<property name="timeBetweenEvictionRunsMillis">30000</property>
<property name="idleTimeout">600000</property>
<property name="heartbeatPeriodMillis">10000</property>
<property name="evictorShutdownTimeoutMillis">10000</property>
</dbInstance>
<!-- can have multi read instances -->
<dbInstance name="instanceS1" url="ip5:3306" user="your_user" password="your_psw" maxCon="200" minCon="50" primary="false">
<property name="heartbeatPeriodMillis">60000</property>
</dbInstance>
</dbGroup>
<dbGroup name="dbGroup2" rwSplitMode="1" delayThreshold="1000" delayPeriodMillis="2000" delayDatabase="test">
<heartbeat errorRetryCount="1" timeout="10" keepAlive="60">show slave status</heartbeat>
<dbInstance name="instanceM2" url="ip5:3306" user="your_user" password="your_psw" maxCon="200" minCon="50" primary="true">
</dbInstance>
<!-- can have multi read instances -->
<dbInstance name="instanceS2" url="ip6:3306" user="your_user" password="your_psw" maxCon="200" minCon="50" primary="false">
<property name="heartbeatPeriodMillis">60000</property>
</dbInstance>
</dbGroup>
</dble:db>
1.4.2 MySQL 用户权限声明
为了让 dble 能正常工作，需根据需要，给后端 MySQL 用户开启以下权限。
| 权限项目 | 作用 |
|---|---|
| SELECT | 数据查询权限 |
| INSERT | 新增数据权限 |
| UPDATE | 更新数据权限 |
| DELETE | 删除数据权限 |
| FILE | load data等数据导出导入的权限 |
| CREATE | 建库(管理端)，建表，建索引权限 |
| DROP | 删除表的权限 |
| ALTER | 变更表结构的权限 |
| LOCK TABLES | lock tables的权限 |
| ALTER ROUTINE | (hint)变更/删除存储过程的权限 |
| CREATE ROUTINE | (hint)创建存储过程的权限 |
| EXECUTE | (hint)执行存储过程的权限 |
| INDEX | 建立/删除索引权限 |
| SUPER | 用于KILL功能 |
| SHOW DATABASES | 部分GUI工具会使用INFORMATION_SCHEMA SCHEMATA表 |
| PROCESS | 用于管理端show processlist 功能 |
| REPLICATION CLIENT | 可能场景: 1.用于配置了主从关系的数据结点,使用了读写分离 2.使用show slave status作为心跳 3.需要使用show @@binlog_status功能 |
| REFERENCES | 外键约束(纯语法支持，无使用意义) |
| XA_RECOVER_ADMIN | 当后端mysql版本大于8.0时，后端mysql用户会需要XA_RECOVER_ADMIN权限 |