【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:

step2:

step3:

step4&5:

step6:

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 都可以：

创建 MySQL 用户：

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

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

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

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

说明：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 数据类型对应关系

TcaplusDB数据类型	SQL类型
int8	TINYINT (TINYINT)
uint8	TINYINT (TINYINT UNSIGNED)
int16	SMALLINT (SMALLINT)
uint16	SMALLINT (SMALLINT UNSIGNED)
int32	INTEGER (INT)
uint32	INTEGER (INT UNSIGNED)
int64	BIGINT (BIGINT)
uint64	BIGINT (BIGINT UNSIGNED)
float	REAL (FLOAT)
double	DOUBLE (DOUBLE)
string	VARCHAR (VARCHAR)
binary	VARBINARY (BLOB)

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级存储、毫秒级时延、无损水平扩展和复杂数据结构等特性。同时具备丰富的生态、便捷的迁移、极低的运维成本和五个九高可用等特点。客户覆盖游戏、互联网、政务、金融、制造和物联网等领域。