「深入理解 TcaplusDB 技术」入门 MySQL Driver

TcaplusDB 版本在 3.57.1 之后兼容 MySQL 5.7 协议，支持 MySQL 的基本功能和语法。MySQL 生态的客户端驱动、工具均适用于 TcaplusDB。

兼容 MySQL 协议是 TcaplusDB 的新特性，目前支持的 SQL 功能有限，包括以下 7 个要点：

• 支持单表的 SELECT、INSERT、DELETE、UPDATE 语句；

• SELECT、DELETE、UPDTATE 操作的 WHERE 子句中必须明确指定一个或多个主键，详见后文《SQL 语法使用参考》；

• 在配置了全局索引的情况下，支持基础的聚合函数，详见后文《全局索引查询》；

• 暂不支持 prepared statement；

• 暂不支持 DDL，即 CREATE / DROP TABLE 等；

• 不支持 ORDER BY、GROUP BY；

• 不支持跨表 JOIN。

1. 客户端或驱动的版本兼容

TcaplusDB 兼容 MySQL 5.7 协议，使用支持 MySQL 5.7 协议（包括 5.7）的客户端或者驱动皆可进行连接。

在实际使用中，可能存在不同版本的兼容差异，我们推荐使用 MySQL 5.0 以上 5.7（包括 5.7）以下的客户端或者驱动。经过我们测试，下述版本的客户端或驱动均可正常使用：

• MySQL client 工具，5.5.24

• Python 的 MySQLdb，实际底层使用 mysql c api 的 5.5.24 版本

• JDBC，mysql-connector-java-5.1.49

• .NET mysql driver 8.0.25

2. 表定义和建表

2.1 表定义

TcaplusDB 当前不支持通过 SQL 的方式动态建表，为了能够顺利进行示例体验，可以使用 XML 文件（如下面示例）进行表定义，通过 Tcaplus OMS 平台进行建表。

表定义示例：

<?xml version="1.0" encoding="GBK" standalone="yes" ?><metalib name="demo_table" tagsetversion="1" version="1">    <struct name="user" version="1" primarykey="user_id,server_id" splittablekey="user_id">        <entry name="user_id" type="string" size="450" desc="用户ID"/>        <entry name="server_id" type="int64" desc="服务器ID" />        <entry name="nick_name" type="string" size="50" desc="昵称"/>        <entry name="desc" type="string" size="1024" desc="描述信息"/>        <entry name="state" type="Tinyuint" defaultvalue="0" desc="用户状态 0 : AVALIABLE, 1 DELETED"/>        <index name="index1" column="user_id"/>        <index name="index2" column="user_id,server_id"/>    </struct></metalib>

复制代码

• 元素 metalib 是 xml 文件的根元素。

• 包含 primarykey 的 struct 元素是一个表，不包含 primarykey 的 struct 元素为一个普通结构体。

• 每次修改表结构时，版本属性值需要相应地加 1，初始版本始终为 1。

• primarykey 属性指定主键字段；对于 generic 表，您最多可以指定 8 个主键字段，对于 list 表，则可以指定 7 个。

• splittablekey 属性等效于分片键（shard key），TcaplusDB 表被拆分存储到多个存储节点。splittablekey 必须是主键字段之一，一个好的 splittablekey 应该具有高度分散性，这意味着值的范围很广，建议选用字符串类型。

• desc 属性包含当前元素的描述。

• entry 元素定义一个字段，支持的值类型包括 int32，string，char，int64，double，short 等。

• index 元素定义一个索引，该索引必须包含 splittablekey。由于可以使用主键查询表，因此索引不应与主键属性相同。

2.2 建表流程

预备工作：预先部署好 Tcaplus Local 版，注意需要使用 3.57.1 版本。

# step0，使用上述xml格式的表定义，保存为.xml后缀的文本，如table-define.xml。# step1，进入OMS 页面，菜单栏处打开：业务管理＝〉表管理。# step2，页面Tab栏处，选中：表添加# step3，选中业务和集群并勾选出来的游戏区, 集群：test_set(1), 业务：tdr_app(2), 游戏区ID: 3, 再点击：批量新增表# step4，在出来的页面中，浏览页面底部部分，点击：从本地文件中添加，在弹出的页面中选择上述资源下载的示例表定义文件:table-define.xml# step5，点击：提交，创建示例表: demo_table# step6，查看表是否创建ok,进入：业务管理=>表管理，选择对应的业务(tdr_app)及游戏区(3), 查看是否出现demo_table表信息

复制代码

操作示例：

step1:

<div align="left"><img src="https://tcaplusdb-img-1301716906.cos.ap-nanjing.myqcloud.com/image/02_1_step1.png" height="400" width="800" /></dev>

step2:

<div align="left"><img src="https://tcaplusdb-img-1301716906.cos.ap-nanjing.myqcloud.com/image/02_1_step2.png" height="500" width="800" /></dev>

step3:

<div align="left"><img src="https://tcaplusdb-img-1301716906.cos.ap-nanjing.myqcloud.com/image/02_1_step3.png" height="390" width="800" /></dev>

step4&5:

<div align="left"><img src="https://tcaplusdb-img-1301716906.cos.ap-nanjing.myqcloud.com/image/02_1_step4.png" height="410" width="800" /></dev>

step6:

<div align="left"><img src="https://tcaplusdb-img-1301716906.cos.ap-nanjing.myqcloud.com/image/02_1_step6.png" height="400" width="800" /></dev>

3. 快速体验

3.1 连接说明

和标准 MySQL 使用一样，连接数据库需要提供用户名、密码、数据库名称、IP 以及端口号以上信息。

1. MySQL 的数据库的概念对应 TcaplusDB 中一个业务的一个区，使用 'appid.zoneid' 作为数据库名称，如示例表所在的区是 2.3。

2. MySQL 客户端或驱动连接的地址是 Tcaplus Proxy 节点的 IP + 端口，可在 OMS 的 运维平台 => 集群状态 页面查看 IP 和端口号。

3. MySQL 第一次连接前，需创建对应的 MySQL 用户并赋予相应的权限，创建流程见下面图文指引。

查看 Proxy 节点的 MySQL 连接地址，任意属于 'appid.zoneid' 的 proxy 都可以：

<div align="left"><img src="images/03_proxy_mysql_url.png" /></dev>

创建 MySQL 用户：

step0，打开对应业务的维护中心。

<div align="left"><img src="images/03_app_user_entry.png" /></dev>

step1，创建用户，填写用户名和密码。

<div align="left"><img src="images/03_create_mysql_user.png" /></dev>

step2，联系运维审核通过，若当前操作者具有权限可以自己审核通过即可。

<div align="left"><img src="images/03_check_mysql_user.png" /></dev>

step3，给该用户赋予读写权限，这里赋予在该 app 下所有 zone 的读写权限。

<div align="left"><img src="images/03_user_authority.png" /></dev><div align="left"><img src="images/03_user_authority_details.png" /></dev>

说明：TcaplusDB 当前只支持 mysql_native_password 插件鉴权，同时也是 MySQL 5.7 的默认连接鉴权。

3.2 体验示例（使用 mysql client）

与连接 MySQL 一样，执行以下命令，使用 MySQL 的 client 工具即可连接 TcaplusDB 的 proxy

mysql -u user_name -p user_passwd --port=15755 --host=xxx.xxx.xxx.xxx 2.3

复制代码

3.3 体验示例（使用 .NET mysql driver）

兼容 MySQL 5.7 协议的 MySQL Driver 均可正常访问数据库。此处使用 .NET 5.0 和 MySQL Connector/NET 8.0.25 对初始化连接的过程进行演示。

public class Database{    static MySqlConnection conn;                // MySql连接    const String server = "xxx.xxx.xxx.xxx";    // 服务器地址，客户端要连接的 proxy 节点的 IP    const String port = "15755";                // 端口号，客户端要连接的 proxy 节点的 Port    const String uid = "user_name";             // 用户名    const String pw = "user_passwd";            // 密码    const String db = "2.3";                    // 库名，由TcaplusDB中的业务ID和分区ID拼接而成
    public static Boolean Init()    {        try        {            if (conn == null)            {                conn = new MySqlConnection("server=" + server + ";port=" + port + ";user id=" + uid + ";password=" + pw + ";database=" + db);                conn.Open();                Console.WriteLine("database connected.");            }            return true;        }        catch (Exception e)        {            Console.WriteLine("Exception caught: {0}", e);            return false;        }    }}

复制代码

4. 数据类型支持

TcaplusDB 和 MySQL 数据类型对应关系

5. SQL 语法使用参考

假设数据表 demo 共有 5 个字段：key1, key2, key3, value1, value2，其中，key1, key2 为 partkey，key1, key2, key3 组成 fullkey。

5.1 插入操作

插入单条记录的 SQL 语句形式如下：

INSERT INTO demo (key1,key2,key3,value1,value2) values (x1,x2,x3,x4,x5);

复制代码

插入多条记录的 SQL 语句形式如下：

INSERT INTO demo (key1,key2,key3,value1,value2) values (x1,x2,x3,x4,x5); INSERT INTO demo (key1,key2,key3,value1,value2) values (x6,x7,x8,x9,x10);

复制代码

5.2 where 子句语法限制

在未配置全局索引的情况下，where 子句由两部分组成：1、必选部分：partkey 或 fullkey；2、可选部分：过滤条件。

partkey 或 fullkey：只能进行等值查询，且组成 partkey 或 fullkey 的各个字段之间只能用 AND 连接；

过滤条件：支持 NOT、=、>、<、!=、>=、<=运算符，且多个过滤条件之间可以用 AND 或 OR 连接，支持 key 字段或 value 字段。

1、使用 fullkey 进行删改查时的 where 子句形式如下：

WHERE key1=x1 AND key2=x2 AND key3=x3;

复制代码

2、使用 fullkey+过滤条件进行删改查时的 where 子句形式如下，若过滤条件中包含 OR 运算符，则必须对过滤条件加括号：

WHERE key1=x1 AND key2=x2 AND key3=x3 AND (过滤条件);

复制代码

3、使用 partkey 进行删改查时的 where 子句形式如下：

WHERE key1=x1 AND key2=x2;

复制代码

4、使用 partkey+过滤条件进行删改查时的 where 子句形式如下，若过滤条件中包含 OR 运算符，则必须对过滤条件加括号：

WHERE key1=x1 AND key2=x2 AND (过滤条件);

复制代码

当 where 子句中的必选部分为 partkey 时，where 子句的执行结果可能是多条记录。

5.3 删除操作

1、通过 fullkey 删除单条记录时，SQL 语句有以下两种形式：

DELETE FROM demo WHERE key1=x1 AND key2=x2 AND key3=x3;DELETE FROM demo WHERE key1=x1 AND key2=x2 AND key3=x3 AND (过滤条件);

复制代码

2、通过 fullkey 批量删除记录时，SQL 语句形式如下：

DELETE FROM demo WHERE (key1=x1 AND key2=x2 AND key3=x3) OR (key1=x4 AND key2=x5 AND key3=x6);

复制代码

删除/批量删除操作不支持 partkey，批量删除操作暂不支持过滤条件。

5.4 更新操作

1、通过 fullkey 更新单条记录时，SQL 语句有以下两种形式：

UPDATE demo SET value1=x1, value2=x2 WHERE key1=x1 AND key2=x2 AND key3=x3;UPDATE demo SET value1=x1, value2=x2 WHERE key1=x1 AND key2=x2 AND key3=x3 AND (过滤条件);

复制代码

2、通过 fullkey 批量更新记录时，SQL 语句形式如下：

UPDATE demo SET value1=x1, value2=x2 WHERE (key1=x3 AND key2=x4 AND key3=x5) OR (key1=x6 AND key2=x7 AND key3=x8);

复制代码

更新/批量更新操作不支持 partkey，批量更新操作暂不支持过滤条件。

5.5 查询操作

1、通过 fullkey 查询单条记录时，SQL 语句有以下四种形式：

SELECT * FROM demo WHERE key1=x1 AND key2=x2 AND key3=x3;SELECT * FROM demo WHERE key1=x1 AND key2=x2 AND key3=x3 AND (过滤条件);SELECT key1,value1 FROM demo WHERE key1=x1 AND key2=x2 AND key3=x3;SELECT key1,value1 FROM demo WHERE key1=x1 AND key2=x2 AND key3=x3 AND (过滤条件);

复制代码

2、通过 partkey 查询多条记录时，SQL 语句有以下四种形式：

SELECT * FROM demo WHERE key1=x1 AND key2=x2;SELECT * FROM demo WHERE key1=x1 AND key2=x2 AND (过滤条件);SELECT key1,value1 FROM demo WHERE key1=x1 AND key2=x2;SELECT key1,value1 FROM demo WHERE key1=x1 AND key2=x2 AND (过滤条件);

复制代码

3、通过 fullkey 批量查询记录时，SQL 语句的形式如下：

SELECT * FROM demo WHERE (key1=x1 AND key2=x2 AND key3=x3) OR (key1=x4 AND key2=x5 AND key3=x6);

复制代码

批量查询操作暂不支持过滤条件。

4、通过 partkey 批量查询记录时，SQL 语句的形式如下：

SELECT * FROM demo WHERE (key1=x1 AND key2=x2) OR (key1=x3 AND key2=x4);

复制代码

批量查询操作暂不支持过滤条件。

6. 全局索引查询

TcaplusDB 提供 sql 查询语句进行索引查询，其中，sql 查询条件中的字段必须是建立了全局索引的字段。另外，如果是聚合查询，则聚合字段也必须是建立了全局索引的字段。当前版本中，每个索引查询请求最多返回 3000 条记录。

由于数据同步到全局索引模块最多需要 1 秒钟的时间，因此，当执行插入或更新操作以后，最多需要 1 秒左右时间可以查询到最新数据。

6.1 支持的 sql 查询语句

条件查询

支持 =, >, >=, <, <=, !=, between, in, not in, like, not like, and, or , 比如:

SELECT * FROM `mail` WHERE user_id>="10004" AND server_id=100;SELECT * FROM `mail` WHERE user_id BETWEEN 10000 AND 10003 AND server_id=100;SELECT * FROM `mail` WHERE user_id="10000" AND server_id=100 AND mail_id LIKE "210507%";SELECT * FROM `mail` WHERE user_id>="10004" OR server_id<=200;

复制代码

注意：between 查询时，between a and b，对应的查询范围为[a, b]；like 查询是支持模糊匹配，其中"%"通配符，匹配 0 个或者多个字符； “_”通配符，匹配 1 个字符；

分页查询

支持 limit offset 分页查询，比如：

SELECT * FROM mail WHERE user_id>"10000" LIMIT 100 OFFSET 2;

复制代码

注意：当前 limit 必须与 offset 搭配使用，不支持 limit 1 或者 limit 0, 1

聚合查询

当前支持的聚合查询包括：sum, count, max, min, avg，比如：

SELECT server_id, COUNT(DISTINCT user_id), COUNT(*), SUM(state) FROM \`mail\` WHERE user_id>="10000" AND server_id=100;

复制代码

注意：聚合查询不支持 limit offset，即 limit offset 不生效；目前只有 count 支持 distinct，即select count(distinct(a)) from table where a > 1000; 其他情况均不支持 distinct。

---

TcaplusDB 是腾讯出品的分布式 NoSQL 数据库，存储和调度的代码完全自研。具备缓存+落地融合架构、PB 级存储、毫秒级时延、无损水平扩展和复杂数据结构等特性。同时具备丰富的生态、便捷的迁移、极低的运维成本和五个九高可用等特点。客户覆盖游戏、互联网、政务、金融、制造和物联网等领域。