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的过程中，如遇报错，可参考错误码含义和处理方法进行处理。