TcaplusDB TDR表 MySQL 协议兼容接口开始使用

为了提升TcaplusDB的易用性，降低用户从MySQL生态切换到TcaplusDB的门槛，TcaplusDB从3.63.x版本开始支持MySQL 5.7协议，用户可以直接使用MySQL-Client、MySQL-Driver、MySQL-Workbench等工具或驱动读写TDR Generic表中的数据（MySQL协议不支持访问List表）。

兼容MySQL协议是TcaplusDB的新特性，目前支持的SQL能力有限。

目前支持的能力有：

支持单表的 SELECT、INSERT、DELETE、UPDATE 语句，且 SELECT、DELETE、UPDTATE 操作的 WHERE 子句中必须明确指定一个或多个主键；
在配置了全局索引的情况下，支持基础的聚合函数；
支持 PREPARED STATEMENT；
支持全表遍历，但与MySQL语法存在差异；
支持有限功能的ORDER BY；
支持SHOW TABLES、DESC TABLE等基本的元数据查询

目前不支持的能力有：

DDL，即 CREATE / DROP TABLE 等；
GROUP BY；
跨表 JOIN

使用MySQL协议访问TcaplusDB的前期准备工作主要包括：

准备环境；
创建业务；
创建游戏区；
创建表格；
收集环境信息；
下载Client或SDK；
连接TcaplusDB。

如果以上准备工作已经完成，可以直接跳过。

1. 准备环境

参考创建集群文档，部署TcaplusDB集群，或者申请TcaplusDB服务。

2. 创建业务

参考创建业务文档，创建业务（App）。

3. 创建游戏区

参考创建游戏区文档，创建游戏区（Zone）。

4. 创建表格

参考创建表格文档，创建Generic表。

4.1. Generic表定义说明

mysql_table表描述文件内容示例：

<?xml version="1.0" encoding="GBK" standalone="yes" ?>
<metalib tagsetversion="1" name="tcaplus" version="1" >
   <struct name="mysql_table" version="1" primarykey="k1,k2,k3" splittablekey="k1" >
       <entry name="k1" type="int32" notnull="true" />
       <entry name="k2" type="int64" />
       <entry name="k3" type="string" size="64" />
       <entry name="v1" type="int16" />
       <entry name="v2" type="float" />
       <entry name="v3" type="double" defaultvalue="9.900000" />
       <entry name="v4" type="string" size="128" />
       <index name="index_k1_k2" column="k1, k2" />
   </struct>
</metalib>

TDR表描述文件格式说明参见TDR表文档。

5. 收集环境信息

使用时，需要用到一些环境相关参数，具体参数和收集方法见下表。

参数	值	获取方法
业务（接入）ID	AppID	获取业务ID
游戏区（表格组）ID	ZoneID	获取游戏区ID
接入地址	AccessIp	获取接入地址
接入端口	AccessPort	获取接入端口
用户名	UserName	获取用户名
用户密码	UserPassword	获取用户密码

6. 下载Client或SDK

TcaplusDB兼容MySQL 5.7协议，使用支持MySQL 5.7协议（包括 5.7）的Client或者SDK都可以进行连接。

实际使用中，可能存在不同版本的兼容差异，我们推荐使用MySQL 5.0以上5.7以下（包括 5.7）的Client或者SDK。

经过我们测试，下述版本的Client或SDK均可正常使用：

MySQL client 5.5.24
mysql-workbench-community-6.2.5
Python的MySQLdb，实际底层使用 mysql c api 的 5.5.24 版本
JDBC，mysql-connector-java-5.1.49
.NET mysql driver 8.0.25
MariaDB C Connector 3.2.5

7. 连接TcaplusDB

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

7.1 使用MySQL Client连接TcaplusDB

与连接MySQL一样，执行以下命令，使用MySQL-client即可连接TcaplusDB：

mysql -hAccessIp -PAccessPort -uUserName -pUserPassword -DAppID.ZoneID

7.2 使用MySQL Driver连接TcaplusDB

此处使用 .NET 5.0和MySQL Connector/NET 8.0.25对初始化连接的过程进行演示：

public class Database
{
    static MySqlConnection conn;          // MySql连接
    const String server = "AccessIp";     // 接入地址
    const String port = "AccessPort";     // 接入端口
    const String uid = "UserName";        // 用户名
    const String pw = "UserPassword";     // 密码
    const String db = "AppID.ZoneID";     // 库名，由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;
        }
    }
}

8. 读写TcaplusDB中的数据

参见MySQL协议兼容语法说明。

9. 常见问题

访问TcaplusDB的过程中，如遇报错，可参考错误码含义和处理方法进行处理。

开始使用

TcaplusDB TDR表 MySQL 协议兼容接口 开始使用