cobar配置详解

schema.xml中定义了schema逻辑层次图中的所有元素，并利用这些元素以及rule.xml中定义的规则组建分布式数据库系统

dataSource
<!-- 数据源定义，数据源是一个具体的后端数据连接的表示。-->
<!--数据源的名称与类型，Cobar暂时只支持mysql这种类型-->
<dataSource name="ds_single_master" type="mysql">
<!--连接的地址，端口和schema名称-->
<property name="location">
<location>192.168.0.4:3306/single</location>
</property>

<!--连接用户名，密码-->
<property name="user">test</property>
<property name="password"></property>
<!--连接的SQL模式-->
<property name="sqlMode">STRICT_TRANS_TABLES</property>
</dataSource>

上面给出的是单个数据源的配置，名称为ds_single_master, Cobar支持把多个用户名密码相同的数据源合并配置在同一个标签中,如下：

<dataSource name="ds_shard_master" type="mysql">
<property name="location">
<location>192.168.0.4:3306/shard</location>
<!--shard$1-3是shard1、shard2、shard3的缩写，在后续介绍的Cobar配置中，我们也会经常看到类似的缩写形式-->
<location>192.168.0.4:3306/shard$1-3</location>
</property>
<property name="user">test</property>
<property name="password"></property>
<property name="sqlMode">STRICT_TRANS_TABLES</property>
</dataSource>

上例中配置了4个数据源，数据源名称分别为ds_shard_master[0]、ds_shard_master[1]、ds_shard_master[2]、ds_shard_master[3]，按照用户location中配置的顺序，对应关系如下:
数据源名称 数据源地址

ds_shard_master[0] 192.168.0.4:3306/shard
ds_shard_master[1] 192.168.0.4:3306/shard1
ds_shard_master[2] 192.168.0.4:3306/shard2
ds_shard_master[3] 192.168.0.4:3306/shard3


dataNode

<!--数据节点由主、备数据源，心跳，连接池等配置组成。-->
<!--数据节点名称--> <dataNode name="dn_single">
<property name="dataSource">
<!--第一行dataSourceRef表示主数据源-->
<dataSourceRef>ds_single_master</dataSourceRef>
<!--第二行dataSourceRef表示备数据源-->
<dataSourceRef>ds_single_slave</dataSourceRef>
<!--如果需要一主多备的情况，可以将第二备数据源配置在第三行，以此类推-->
<dataSourceRef>ds_single_slave2</dataSourceRef>
</property>
<!--Cobar与后端数据源连接池大小设置-->
<property name="poolSize">256</property>

<!--Cobar通过心跳来实现后端数据源HA，一旦主数据源心跳失败，便切换到备数据源上工作-->
<!--Cobar心跳是通过向后端数据源执行一条SQL语句，根据该语句的返回结果判断数据源的运行情况-->
<property name="heartbeatSQL">select user()</property> （1.2.7版本用这个配置）
<property name="heartbeat">select user()</property> （1.2.6及以前版本用这个配置） </dataNode>

注意：心跳SQL语句可以由用户自定义，数据源心跳配置介绍了一种我们更推荐的配置方式, 后面的例子中，我们也将会用这种推荐的方式配置心跳。
同数据源配置类似，可以将多个数据节点配置合并,只需在每行dataSourceRef中配置多个数据源即可


<dataNode name="dn_shard">
<property name="dataSource">
<!--三个数据节点的主数据源，可用逗号分隔，支持$1-3的缩写形式， 表示ds_shard_master[1], ds_shard_master[2], ds_shard_master[3]-->
<dataSourceRef>ds_shard_master[0], ds_shard_master$1-3</dataSourceRef>
<!--三个数据节点的备数据源，必须与主数据源一一对应(个数，顺序都要对应)-->
<dataSourceRef>ds_shard_slave$0-3</dataSourceRef>
</property>
<property name="poolSize">256</property>
<property name="heartbeatSQL">update xdual set x=now() where id=${(1,10)}</property>
</dataNode>

上例中配置了三个数据节点，按照顺序，名称分别为dn_shard[0], dn_shard[1], dn_shard[2]，dn_shard[3]三个节点的连接池大小与心跳语句都相同，数据节点的主备对应关系如下
节点名称 主数据源 备数据源

dn_shard[0] ds_shard_master[0] ds_shard_slave[0]
dn_shard[1] ds_shard_master[1] ds_shard_slave[1]
dn_shard[2] ds_shard_master[2] ds_shard_slave[2]
dn_shard[3] ds_shard_master[3] ds_shard_slave[3]

注意：Cobar根据每行dataSourceRef中数据源的顺序来对应主备，因此每行dataSourceRef里的数据源不仅个数必须相同，顺序也必须一一对应。如果用户把上例中dataSourceRef的顺序调整一下

<dataSourceRef>ds_shard_master[1], ds_shard_master[0], ds_shard_master$2-3</dataSourceRef>
<dataSourceRef>ds_shard_slave$0-3</dataSourceRef>

主备对应关系立即改变，因此配置时请注意顺序
节点名称 主数据源 备数据源

dn_shard[0] ds_shard_master[1] ds_shard_slave[0]
dn_shard[1] ds_shard_master[0] ds_shard_slave[1]
dn_shard[2] ds_shard_master[2] ds_shard_slave[2]
dn_shard[3] ds_shard_master[3] ds_shard_slave[3]


schema

schema定义了Cobar展示给用户的schema，schema由dataNode以及rule.xml中定义的路由规则共同组成。

tableRule
tableRule主要作用是用来判断SQL语句路由到哪些datanode执行，Cobar是通过在SQL中提取一个或多个字段的值，并根据这些字段的值来决定路由到哪个库执行。因此，tableRule定义两个要素：
1)按表中的哪个字段路由？------下文中我们称此字段为路由字段
2)有了字段值，如何路由？------即路由函数

<!--tableRule名称--><tableRule name="tb1Rule">
<rule>
<!--id为路由字段， id是int型字段-->
<columns>id</columns>
<!--int_4是路由函数，参数为id，int_4在function中定义，稍后介绍-->
<algorithm><![CDATA[int_4(${id})]]></algorithm>
</rule>
</tableRule><tableRule name="tb2Rule">
<rule>
<!--val为路由字段， val是varchar型字段-->
<columns>val</columns>
<!--string_2是路由函数，参数为val-->
<algorithm><![CDATA[string_2(${id})]]></algorithm>
</rule>
</tableRule><tableRule name="tb3Rule">
<rule>
<!--id和val共同组成路由字段， id是int型字段，val是varchar型字段-->
<columns>id, val</columns>
<algorithm><![CDATA[ twoDimensionFunc(${id},${val})]]></algorithm>
</rule>
<!--按多个字段路由时需要考虑SQL中只有一个字段的情况-->
<rule>
<!--当SQL语句中只有id，无val字段时，匹配此规则，val参数设置为null-->
<columns>id</columns>
<algorithm><![CDATA[ twoDimensionFunc(${pid},null)]]></algorithm>
</rule>
<rule>
<!--当SQL语句中只有val，无id字段时, 匹配此规则，id参数设置为null-->
<columns>val</columns>
<algorithm><![CDATA[ twoDimensionFunc(null,${uid})]]></algorithm>
</rule>
</tableRule>

function
Cobar支持按1-2个字段做路由，因此路由算法分为单维路由和多维路由（2维），关于路由算法参见路由算法。


server.xml
system

<!--system中包含系统参数定义，服务端口、管理端口，处理器个数、线程池等定义-->
<!--这些配置都有默认值，一般情况下用户可以完全不用配置-->
<system>
<!--端口定义，如果没有端口冲突，可不用配置-->
<!--Cobar服务端口, 通过此端口执行SQL语句，默认值8066-->
<property name="serverPort">8066</property>
<!--Cobar管理端口，通过此端口执行Cobar管理命令， 默认值9066-->
<property name="managerPort">9066</property>

<!--Cobar内部处理器个数，线程池等定义，默认值为Cobar所在机器处理器个数-->
<!--这些配置主要影响Cobar内部处理性能，可在做性能优化时调整-->
<!--initExecutor:处理初始化任务的线程-->
<property name="initExecutor">16</property>
<!--timerExecutor:处理定时任务的线程-->
<property name="timerExecutor">4</property>
<!--managerExecutor:处理来自9066端口任务的线程-->
<property name="managerExecutor">4</property>
<!--processors:Cobar内部处理器个数，默认与系统cpu个数相同-->
<property name="processors">4</property>
<!--processorHandler:前端处理线程，负责处理所有8066端口前端连接-->
<property name="processorHandler">8</property>
<!--processorExcutor:后端处理线程，负责处理Cobar与MySQL之间的连接，可以适当设置大一些-->
<property name="processorExecutor">8</property>

<!--Cobar与Cobar间心跳的用户名和密码, 默认值即是_HEARTBEAT_USER_和_HEARTBEAT_PASS_-->
<!--如果两台Cobar之间需要心跳，这两项配置必须相同,一般不建议自行配置，使用默认值即可-->
<property name="clusterHeartbeatUser">_HEARTBEAT_USER_</property>
<property name="clusterHeartbeatPass">_HEARTBEAT_PASS_</property>
</system>


user

<!--Cobar的用户定义，包括用户名，密码以及访问权限设置，可以配置任意多个用户-->
<!--普通用户配置-->
<user name="test"> <!--用户名-->
<property name="password">test</property> <!--密码-->
<!--Cobar对用户进行了简单的权限控制，可定义用户对某些schema是否有访问权限-->
<!--这里不区分读写权限，一旦拥有访问权限，便是读写权限-->
<!--以逗号分隔多个schema, test用户只能访问db_single和db_shard两个Cobar定义的schema-->
<property name="schemas">db_single，db_shard</property>
</user>

<!--超级用户配置，超级用户是指对所有schema都有访问权限的用户-->
<user name="root1">
<property name="password">root</property>
<!--不配置任何访问权限，表示对所有schema都有访问权限-->
</user>
<user name="root2">
<property name="password">root</property>
<!--配置为空同样表示对所有schema都有访问权限-->
<property name="schemas"></property>
</user>

cluster
在实际应用中，经常需要部署一个Cobar集群，我们称集群中的一台Cobar为一个Cobar节点。

<!--组建一个Cobar集群，只需在cluster配置中把所有Cobar节点（注意：包括当前Cobar自身）都配置上便可-->
<cluster>
<!--node名称，一个node表示一个Cobar节点，一旦配置了node，当前Cobar便会向此节点定期发起心跳，探测节点的运行情况-->
<node name="cobar1">
<!--Cobar节点IP, 表示当前Cobar将会向192.168.0.1上部署的Cobar发送心跳-->
<property name="host">192.168.0.1</property>
<!--节点的权重，用于客户端的负载均衡，用户可以通过命令查询某个节点的运行情况以及权重-->
<property name="weight">1
</property>
</node>
<!--当前Cobar将会向192.168.0.2上部署的Cobar发送心跳-->
<node name="cobar2">
<property name="host">192.168.0.2</property>
<property name="weight">2</property>
</node>
<!--当前Cobar将会向192.168.0.3上部署的Cobar发送心跳-->
<node name="cobar3">
<property name="host">192.168.0.3</property>
<property name="weight">3</property>
</node>
<!--用户还可以将Cobar节点分组，以便实现schema级别的细粒度负载均衡-->
<group name="group12">
<property name="nodeList">cobar1,cobar2</property>
</group>
<group name="group23">
<property name="nodeList">cobar2,cobar3</property>
</group>
</cluster>

用户只需登录Cobar的服务端口(8066)，运行Cobar自带的查询命令show cobar_cluster，便可查询集群中所有节点的运行情况以及权重，并根据查询结果做负载均衡。

mysql -h192.168.0.1 -utest -ptest -P8066
mysql>show cobar_cluster; #查询cluster配置中正常的Cobar节点
+---------------+--------+|
HOST | WEIGHT
|+---------------+--------+|
192.168.0.1 | 1 ||
192.168.0.2 | 2 ||
192.168.0.3 | 3 |
+---------------+--------+

注意：
1）如果需要配置Cobar集群，当前Cobar自身也需要作为一个节点配置在cluster中，Cobar不会默认向自己发心跳；
2）show cobar_cluster只显示cluster配置中得正常Cobar节点，如果节点异常（如超时或错误），结果中便不会包含此节点。
3）3.4节会介绍更多关于show cobar_cluster以及group配置的用处，详见3.4节->cobar自定义语句->show cobar_status/show cobar_cluster。
在了解show cobar_cluster使用后，用户可以根据如何在多个cobar节点之间做负载均衡选择适合的负载均衡策略。
quarantine

<!-- 隔离区定义，出于安全角度考虑，限定某个主机上只允许某个用户登录。 -->
<quarantine>
<!--从192.168.0.110这台主机连接当前Cobar，只能使用test， test1这两个普通用户登录，不可用root1, root2登录--> <host name="192.168.0.110">
<!--注意：此处配置的用户必须为普通用户，不可以配置超级用户，多个用户用逗号分隔-->
<property name="user">test， test1</property>
</host>
<!--从192.168.0.120这台主机连接当前Cobar，只能使用test用户登录，不可用root1，root2登录-->
<host name="192.168.0.120">
<property name="user">test</property>
</host>
</quarantine>

注意：隔离区内不允许配置当前集群中任何Cobar节点的IP。