diff --git a/doc/KingDoc/function_FAQ.md b/doc/KingDoc/function_FAQ.md index 3695aef7..21c280ac 100644 --- a/doc/KingDoc/function_FAQ.md +++ b/doc/KingDoc/function_FAQ.md @@ -1,4 +1,4 @@ -#kingshard的FAQ +# kingshard的FAQ **1. kingshard的线上使用情况和稳定性如何？** diff --git a/doc/KingDoc/how_to_use_kingshard.md b/doc/KingDoc/how_to_use_kingshard.md index ef52dcd9..af9ef0fd 100644 --- a/doc/KingDoc/how_to_use_kingshard.md +++ b/doc/KingDoc/how_to_use_kingshard.md @@ -1,4 +1,4 @@ -#如何利用一个数据库中间件扩展MySQL集群——kingshard使用指南 +# 如何利用一个数据库中间件扩展MySQL集群——kingshard使用指南 上次写了一篇有关kingshard架构设计的[文章](./architecture_of_kingshard_CN.md),得到了很多热心网友的关注。其中有网友提到：希望再写一篇关于如何利用kingshard搭建一个可扩展的MySQL集群的文档。利用假期时间，写了一篇kingshard使用指南，在这篇文章中，我将结合自己对MySQL Proxy的理解，为大家讲述如何正确使用kingshard数据库中间件。 diff --git a/doc/KingDoc/kingshard_admin_api.md b/doc/KingDoc/kingshard_admin_api.md index 75336f24..065c7e7c 100644 --- a/doc/KingDoc/kingshard_admin_api.md +++ b/doc/KingDoc/kingshard_admin_api.md @@ -1,6 +1,6 @@ -#kingshard 管理端API设计 +# kingshard 管理端API设计 -##接口定义和参数说明 +## 接口定义和参数说明 - 采用restful风格API设计。 - 假设kingshard的Web Server IP和端口是：127.0.0.1：9797，web用户名：admin，密码：admin @@ -32,7 +32,7 @@ URL:http://127.0.0.1:9797/api/v1/nodes/status 返回结果：node数组，node中包含Master和Slave信息， 字段意思参考配置文件说明 ``` -####示例 +#### 示例 ``` curl -X GET \ -H 'Content-Type: application/json' \ @@ -71,7 +71,7 @@ URL:http://127.0.0.1:9797/api/v1/nodes/slaves - addr：slave的IP和端口 返回结果：成功:"ok",失败："error message" ``` -####示例 +#### 示例 ``` curl -X POST \ -H 'Content-Type: application/json' \ @@ -90,7 +90,7 @@ URL:http://127.0.0.1:9797/api/v1/nodes/slaves - addr：slave的IP和端口 返回结果：成功:"ok",失败："error message" ``` -####示例 +#### 示例 ``` curl -X DELETE \ -H 'Content-Type: application/json' \ @@ -111,7 +111,7 @@ URL：http://127.0.0.1:9797/api/v1/nodes/slaves/status 返回结果：成功:"ok",失败："error message" ``` -####示例 +#### 示例 ``` curl -X PUT \ -H 'Content-Type: application/json' \ @@ -134,7 +134,7 @@ URL：http://127.0.0.1:9797/api/v1/nodes/masters/status 返回结果：成功:"ok",失败："error message" ``` -####示例 +#### 示例 ``` curl -X PUT \ -H 'Content-Type: application/json' \ @@ -154,7 +154,7 @@ URL:http://127.0.0.1:9797/api/v1/proxy/status 注意：该API主要用于配合LVS平滑下线 ``` -####示例 +#### 示例 ``` curl -X GET \ -H 'Content-Type: application/json' \ @@ -173,7 +173,7 @@ URL:http://127.0.0.1:9797/api/v1/proxy/status ``` -####示例 +#### 示例 ``` curl -X PUT \ -H 'Content-Type: application/json' \ @@ -190,7 +190,7 @@ http://127.0.0.1:9797/api/v1/proxy/schema 参数：无 返回结果:schema数组，但只有一项。字段意思参考配置文件 ``` -####示例 +#### 示例 ``` curl -X GET \ -H 'Content-Type: application/json' \ @@ -302,7 +302,7 @@ URL：http://127.0.0.1:9797/api/v1/proxy/allow_ips 参数：allow_ips，ip列表数组 返回结果：IP列表 ``` -####示例 +#### 示例 ``` curl -X GET \ -H 'Content-Type: application/json' \ @@ -320,7 +320,7 @@ URL：http://127.0.0.1:9797/api/v1/proxy/allow_ips 参数：allow_ips，ip列表数组 返回结果：成功:"ok",失败："error message" ``` -####示例 +#### 示例 ``` curl -X POST \ -H 'Content-Type: application/json' \ @@ -338,7 +338,7 @@ URL：http://127.0.0.1:9797/api/v1/proxy/allow_ips 参数：allow_ips，ip列表数组 返回结果：成功:"ok",失败："error message" ``` -####示例 +#### 示例 ``` curl -X DELETE \ -H 'Content-Type: application/json' \ @@ -356,7 +356,7 @@ http://127.0.0.1：9797/api/v1/proxy/black_sqls 参数：无 返回结果:sql列表 ``` -####示例 +#### 示例 ``` curl -X GET \ -H 'Content-Type: application/json' \ @@ -373,7 +373,7 @@ http://127.0.0.1:9797/api/v1/proxy/black_sqls 返回结果：成功:"ok",失败："error message" ``` -####示例 +#### 示例 ``` curl -X POST \ -H 'Content-Type: application/json' \ @@ -390,7 +390,7 @@ http:// 127.0.0.1:9797/api/v1/proxy/black_sqls 参数：sql（注意：一次只能删除一条SQL） 返回结果：成功:"ok",失败："error message" ``` -####示例 +#### 示例 ``` curl -X DELETE \ -H 'Content-Type: application/json' \ @@ -407,7 +407,7 @@ URL:http://127.0.0.1:9797/api/v1/proxy/slow_sql/status 参数：opt(可选值："on","off") 返回结果：成功:"ok",失败："error message" ``` -####示例 +#### 示例 ``` curl -X PUT \ -H 'Content-Type: application/json' \ @@ -424,7 +424,7 @@ URL:http://127.0.0.1:9797/api/v1/proxy/slow_sql/time 参数：无 返回结果：slow_log 时间，单位ms ``` -####示例 +#### 示例 ``` curl -X GET \ -H 'Content-Type: application/json' \ @@ -440,7 +440,7 @@ URL:http://127.0.0.1:9797/api/v1/proxy/slow_sql/time 参数：slow_time(慢日志时间，单位ms。执行时间超过该值的SQL会输出到慢日志文件) 返回结果：成功:"ok",失败："error message" ``` -####示例 +#### 示例 ``` curl -X PUT \ -H 'Content-Type: application/json' \ @@ -458,7 +458,7 @@ URL:http://127.0.0.1:9797/api/v1/proxy/config/save 返回结果：成功:"ok",失败："error message" 说明：将kingshard的配置写入文件 ``` -####示例 +#### 示例 ``` curl -X PUT \ -H 'Content-Type: application/json' \ diff --git a/doc/KingDoc/kingshard_install_document.md b/doc/KingDoc/kingshard_install_document.md index 829de413..daa485c1 100644 --- a/doc/KingDoc/kingshard_install_document.md +++ b/doc/KingDoc/kingshard_install_document.md @@ -9,7 +9,7 @@ 7. 运行kingshard。./bin/kingshard -config=etc/ks.yaml ``` -##配置文件说明 +## 配置文件说明 ``` # kingshard的地址和端口 @@ -113,7 +113,7 @@ schema : ``` -##注意 +## 注意 **1. kingshard会响应SIGINT,SIGTERM,SIGQUIT这三个信号，平滑退出。在部署kingshard机器上应避免产生这三个信号，以免造成kingshard非正常退出！后台运行kingshard建议使用supervisor工具** diff --git a/doc/KingDoc/kingshard_quick_try.md b/doc/KingDoc/kingshard_quick_try.md index 635e17bb..4065134d 100644 --- a/doc/KingDoc/kingshard_quick_try.md +++ b/doc/KingDoc/kingshard_quick_try.md @@ -1,19 +1,19 @@ -#KingShard快速入门 +# KingShard快速入门 -##环境说明 +## 环境说明 本文仅作为最小实验环境，因此不使用master, slave模式. 单机上使用mysql_mutil运行两个mysql实列 -##初始化数据目录 +## 初始化数据目录 # mysql_install_db --datadir=/var/lib/mysql2/ --user=mysql # mysql_install_db --datadir=/var/lib/mysql3/ --user=mysql -##生成配置文件 +## 生成配置文件 利用mysqld_multi工具生成配置文件 @@ -46,7 +46,7 @@ user = unix_user2 -###启动多个实例 +### 启动多个实例 # mysqld_multi --defaults-extra-file=./mysqld_multi.conf start 或者 mysqld_multi --defaults-extra-file=./mysqld_multi.conf start 2; mysqld_multi --defaults-extra-file=./mysqld_multi.conf start 3(分别启动) @@ -64,11 +64,11 @@ 说明２个实例都已经启动了。 -##安装Kingshard +## 安装Kingshard 参考[kingshard install](https://github.com/doumadou/kingshard/blob/master/doc/KingDoc/kingshard_install_document.md) -##配置Kingshard +## 配置Kingshard 修改/etc/hosts文件, 添加如下二行 @@ -161,37 +161,37 @@ ``` -##设置mysql实例信息 +## 设置mysql实例信息 -###设置用户 +### 设置用户 分类登陆mysqld2, mysqld3, 创建root用户(该用户是给kingshard管理的，测试为了方便所以直接使用root) 若用户存在，跳过此步 /usr/bin/mysqladmin -h 127.0.0.1 -P 3307 -u root password 'root' /usr/bin/mysqladmin -h 127.0.0.1 -P 3308 -u root password 'root' -###建数据库 +### 建数据库 分类登陆mysqld2, mysqld2，创建kingshard数据库 /usr/bin/mysql -h 127.0.0.1 -P 3307 -u root -proot -e "create database kingshard;" /usr/bin/mysql -h 127.0.0.1 -P 3308 -u root -proot -e "create database kingshard;" -##启动Kingshard +## 启动Kingshard # ./bin/kingshard -config=etc/ks.yaml -##测试shard功能 +## 测试shard功能 使用test_shard_hash测试 shard　hash分表功能. -###创建分表 +### 创建分表 创建test_shard_hash分表(_0000~_0007), _0001~_0003在node1(mysqld2)上创建, _0004~_0007在node2(mysqld3)上创建。 for i in `seq 0 3`;do /usr/bin/mysql -h 127.0.0.1 -P 3307 -u root -proot kingshard -e "CREATE TABLE IF NOT EXISTS test_shard_hash_000"${i}" ( id BIGINT(64) UNSIGNED NOT NULL, str VARCHAR(256), f DOUBLE, e enum('test1', 'test2', 'test3', 'test4', 'test5', 'test6', 'test7', 'test8', 'test9', 'test10'), u tinyint unsigned, i tinyint, ni tinyint, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;";done for i in `seq 4 7`;do /usr/bin/mysql -h 127.0.0.1 -P 3308 -u root -proot kingshard -e "CREATE TABLE IF NOT EXISTS test_shard_hash_000"${i}" ( id BIGINT(64) UNSIGNED NOT NULL, str VARCHAR(256), f DOUBLE, e enum('test1', 'test2', 'test3', 'test4', 'test5', 'test6', 'test7', 'test8', 'test9', 'test10'), u tinyint unsigned, i tinyint, ni tinyint, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;";done -###插入数据 +### 插入数据 mysql连接到kingshard插入数据 @@ -223,7 +223,7 @@ kingshard日志如下： 通过kingshard的日志可以看到数据插入时根据不同的hash值，插入到不同的子表里面去了。 -###查看数据 +### 查看数据 [root@testnode kingshard]# mysql -h 127.0.0.1 -P 9696 -u kingshard -pkingshard -e "select * from test_shard_hash where id in (2, 3, 4, 5)" +----+------+------+-------+------+------+------+ diff --git a/doc/KingDoc/kingshard_sharding_introduce.md b/doc/KingDoc/kingshard_sharding_introduce.md index cd763785..51998c8f 100644 --- a/doc/KingDoc/kingshard_sharding_introduce.md +++ b/doc/KingDoc/kingshard_sharding_introduce.md @@ -1,4 +1,4 @@ -#kingshard sharding介绍 +# kingshard sharding介绍 现在开源的MySQL Proxy已经有几款了，并且有的已经在生产环境上广泛应用。但这些proxy在sharding方面，都是不能分子表的。也就是说一个node节点只能分一张表。但我们的线上需求通常是这样的： **我有一张非常大的表，行数超过十亿，需要进行拆分处理。假设拆分因子是512。 @@ -13,19 +13,19 @@ 2.将shardKey通过hash或range方式定位到其要操作的记录在哪张子表上。 3.子表落在哪个node上通过配置文件设置。 -##sharding支持的操作 +## sharding支持的操作 目前kingshard sharding支持insert, delete, select, update和replace语句, 所有这五类操作都支持跨子表。但写操作仅支持单node上的跨子表，select操作则可以跨node，跨子表。 -##sharding方式 +## sharding方式 -###range方式 +### range方式 基于整数范围划分来得到子表下标。该方式的优点：基于范围的查询或更新速度快，因为查询（或更新）的范围有可能落在同一张子表中。这样可以避免全部子表的查询（更新）。缺点：数据热点问题。因为在一段时间内整个集群的写压力都会落在一张子表上。此时整个mysql集群的写能力受限于单台mysql server的性能。并且，当正在集中写的mysql 节点如果宕机的话，整个mysql集群处于不可写状态。基于range方式的分表字段类型受限。 -###hash方式 +### hash方式 kingshard采用（shardKey%子表个数）的方式得到子表下标。优点：数据分布均匀，写压力会比较平均地落在后端的每个MySQL节点上，整个集群的写性能不会受限于单个MySQL节点。并且当某个分片节点宕机，只会影响到写入该节点的请求，其他节点的写入请求不受影响。分表字段类型不受限。因为任何一个类型的分表字段，都可以通过一个hash函数计算得到一个整数。缺点：基于范围的查询或更新，都需要将请求发送到全部子表，对性能有一定影响。但如果不是基于范围的查询或更新，则性能不会受到影响。 -##sharding相关的配置介绍 +## sharding相关的配置介绍 在配置文件中，有关sharding设置是通过schema设置： ``` @@ -78,11 +78,11 @@ kingshard采用（shardKey%子表个数）的方式得到子表下标。优点 - default，默认分表规则。所有操作不在shard（default规则下面的规则）中的表的SQL语句都会发向该node。 - hash，hash分表方式。 - range，range分表方式 -##kingshard架构图 +## kingshard架构图 ![](http://ww3.sinaimg.cn/large/6e5705a5gw1eu7wfrubi3j20qo0k0ab4.jpg) -##基于kingshard的子表迁移方案 +## 基于kingshard的子表迁移方案 通过kingshard可以非常方便地动态迁移子表，从而保证MySQL节点的不至于负载压力太大。大致步骤如下所述： 1. 通过自动数据迁移工具开始数据迁移。 @@ -91,7 +91,7 @@ kingshard采用（shardKey%子表个数）的方式得到子表下标。优点 4. 更改kingshard配置文件中的对应子表的路由规则。 4. 删除老节点上的子表。 -##Example +## Example 简单演示一下kingshard的相关操作，感兴趣的同学可以自己试一试。:) ``` diff --git a/doc/KingDoc/kingshard_support_sql.md b/doc/KingDoc/kingshard_support_sql.md index c0afa0cb..290e7413 100644 --- a/doc/KingDoc/kingshard_support_sql.md +++ b/doc/KingDoc/kingshard_support_sql.md @@ -1,6 +1,6 @@ -#Kingshard支持SQL的范围 +# Kingshard支持SQL的范围 -##1.简要说明 +## 1.简要说明 kingshard在非分表的情况下支持绝大部分MySQL语法和协议，包括类似SHOW DATABASES, SHOW TABLES, 以及各种DML语句和DDL语句。在分表的情况下，目前只支持有限的DML语句，主要包含：SELECT,UPDATE,INSERT,REPLACE, DELETE这五种SQL操作。并且不支持自动建子表功能。以及有限的kingshard自定义管理端命令。在分表和非分表的情况下，都不支持以下情形： - 暂不支持用户自定义数据类型、自定义函数。 - 暂不支持视图、存储过程、触发器、游标。 @@ -8,7 +8,7 @@ kingshard在非分表的情况下支持绝大部分MySQL语法和协议，包括 - 暂不支类似 IF,WHILE 等流程控制类语句。 下面分两部分介绍kingshard支持SQL的情况：非分表情况下SQL支持范围和分表情况下SQL支持范围。 -##2.非分表情况下SQL的支持范围 +## 2.非分表情况下SQL的支持范围 以下说明都是基于非分表的情况下，SQL的支持情况。 2.1 数据库DDL语法 - CREATE TABLE Syntax @@ -36,7 +36,7 @@ kingshard在非分表的情况下支持绝大部分MySQL语法和协议，包括 - SELECT INTO OUTFILE/INTO DUMPFILE/INTO var_name 暂不支持 - Last_insert_id特性 -###2.3 事务的支持 +### 2.3 事务的支持 - START TRANSACTION, COMMIT, and ROLLBACK Syntax - 暂不支持transaction_characteristic定义 - 暂不支持savepoint嵌套事务的相关语法 @@ -47,7 +47,7 @@ kingshard在非分表的情况下支持绝大部分MySQL语法和协议，包括 - SET TRANSACTION Syntax - 暂不支持对global的事务隔离级别进行调整 -###2.4 预处理的支持 +### 2.4 预处理的支持 - Prepared Statements 支持主流语言（java,php,python,C/C++,Go)SDK的MySQL的Prepare语法。 @@ -59,17 +59,17 @@ kingshard在非分表的情况下支持绝大部分MySQL语法和协议，包括 - KILL Syntax 目前不支持KILL QUERY processlist_id -###2.6 数据库管理语法的支持 +### 2.6 数据库管理语法的支持 - DESCRIBE Syntax - EXPLAIN Syntax - USE Syntax -###2.7 数据库系统函数的支持 +### 2.7 数据库系统函数的支持 默认都支持（未测试） -##3.分表的情况下SQL的支持范围 +## 3.分表的情况下SQL的支持范围 -###3.1 数据库DDL语法 +### 3.1 数据库DDL语法 - CREATE TABLE Syntax - CREATE INDEX Syntax - DROP TABLE Syntax @@ -83,7 +83,7 @@ kingshard在非分表的情况下支持绝大部分MySQL语法和协议，包括 **注：** `truncate`如果不指定节点注释则会将所有分表都清空，例如：`truncate stu` -###3.2 数据库DML语法 +### 3.2 数据库DML语法 - INSERT Syntax - INSERT DELAYED Syntax 不支持 - INSERT INTO SELECT 不支持 @@ -96,7 +96,7 @@ kingshard在非分表的情况下支持绝大部分MySQL语法和协议，包括 - SELECT Syntax 对于UPDATE，DELETE和SELECT三种SQL中WHERE后面的条件不能包含子查询，函数等。只能是字段名。 -###3.3 数据库管理语法的支持 +### 3.3 数据库管理语法的支持 - DESCRIBE Syntax 通过SQL语句hint方式支持，例如:` /*node2*/describe table_name` - EXPLAIN Syntax @@ -111,10 +111,10 @@ kingshard在非分表的情况下支持绝大部分MySQL语法和协议，包括 - min函数 不支持distinct后聚合，例如:` select count(distinct id) from xxxx` -###3.4 分表group by,order by,limit支持 +### 3.4 分表group by,order by,limit支持 支持分表情况下的group by, order by, limit -###3.5 其他情形说明 +### 3.5 其他情形说明 - 不支持分布式事务，支持以非事务的方式更新多node上的数据。 - 不支持预处理。 - 不支持数据库管理语法。