【TcaplusDB知识库】Tcaplus-JDBC开发入门指南

TcaplusDB-JDBC 概述
TcaplusDB为用Java编程语言开发的客户端应用程序提供了可连接性，TcaplusDB-JDBC实现了JDBC API以及它的一些增值扩展。

TcaplusDB提供了易于开发的特性，包括向驱动程序管理器自动注册、标准化有效性检查、分类SQLExceptions、支持大量更新计数。

TcaplusDB-JDBC和Java版本的兼容性
**JDBC版本：**TcaplusDB JDBC实现了JDBC 11.1.0，并兼容更高版本。
**TcaplusDB版本：**TcaplusDB-JDBC基于TcaplusDB 3.53.0开发。
**Java版本：**TcaplusDB-JDBC基于java1.8开发。
编译所需的JDK：编译TcaplusDB-JDBC需要JDK8.0或更高版本。
TcaplusDB-JDBC快速入门
通过TcaplusDB-JDBC连接TcaplusDB，链接格式如下：

jdbc:tcaplusdb://<instance_ip>:<instance_port>?app_id=<app_id>&zone_id=<zone_id>

其中<instance_ip>为实例主机ip；<instance_port>为开放端口；<app_id>为业务id，<zone_id>为游戏区id，详见“连接URL语法”。

连接与读取数据示例：

import java.sql.*;public class ConnTest { final public static void main(String[] args) { String url = "jdbc:tcaplusdb://192.168.0.1:9999?app_id=2&zone_id=3"; Properties connProperties = new Properties(); connProperties.setProperty("app_password", "123456");//set password try { final Connection connection = DriverManager.getConnection(url,connProperties); try { final Statement statement = connection.createStatement(); try { final String SQL = "SELECT * FROM \"user\" WHERE user_id = '10000'"; final ResultSet resultSet = statement.executeQuery(SQL); try { while (resultSet.next()) { System.out.println(resultSet.getString(1)); } } finally { resultSet.close(); } } finally { statement.close(); } } finally { connection.close(); } } catch (Exception e) { e.printStackTrace(); System.out.println("Test failed"); } }}

TcaplusDB-JDBC 的安装
下载及安装
#部署到/root/tcaplusdb-jdbcmkdir /root/tcaplusdb-jdbccd /root/tcaplusdb-jdbc#下载wget https://tcaplus-demo-1301716906.cos.ap-guangzhou.myqcloud.com/TcaplusJDBC3.53.1.204689.x86_64_release_20210802.tar.gz#解压tar -zxvf TcaplusJDBC3.53.1.204689.x86_64_release_20210802.tar.gz

配置CLASSPATH
解压tcaplus-jdbc-[version].jar到正确的位置，再将JAR包放在Java类路径中完成驱动程序的安装，或者将其完整的文件路径添加到您的CLASSPATH环境变量，或者使用命令行选项-cp直接指定文件路径启动JVM。

例如，在Linux平台上，将TcaplusDB-JDBC添加到CLASSPATH根据命令shell的不同，使用以下形式之一：（路径修改

# Bourne-compatible shell (sh, ksh, bash, zsh):shell> export CLASSPATH=/path/tcaplus-jdbc-[version].jar:$CLASSPATH# C shell (csh, tcsh):shell> setenv CLASSPATH /path/tcaplus-jdbc-[version].jar:$CLASSPATH

您还可以设置CLASSPATH配置文件中的环境变量，通过用户本地的.profile, .login，或其他登录文件，或通过编辑全局/etc/profile文件。

对于Windows平台，可以通过系统控制面板设置环境变量。

注意：需要添加TcaplusDB-JDBC运行所需库的路径到CLASSPATH。

TcaplusDB-JDBC 示例
示例表定义
使用xml定义TcaplusDB表，示例如下：

<?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="uint64" 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。由于可以使用主键查询表，因此索引不应与主键属性相同。
示例表创建
打开 web 控制台，登录后，按如下步骤创建示例表

# step0，下载表定义文件。在Chrome浏览器进入：https://tcaplus-demo-1301716906.cos.ap-guangzhou.myqcloud.com/table-define.xml 右键网页，另存为文件。# step1，使用Chrome浏览器，登录 web 查看控制台,打开浏览器，输入 web 地址:[cvm 外网 ip]:80，账号密码均为tcaplus。菜单栏处打开：业务管理＝〉表管理。# step2，页面Tab栏处，选中：表添加# step3，选中业务和集群并勾选出来的游戏区, 集群：test_set(1), 业务：tdr_app(2), 游戏区ID: 3, 再点击：批量新增表# step4，在出来的页面中，浏览页面底部部分，点击：从本地文件中添加，在弹出的页面中选择上述资源下载的示例表定义文件:table-define.xml# step5，点击：提交，创建3张示例表: user, server, mail# step6，查看表是否创建ok,进入：业务管理=>表管理，选择对应的业务(tdr_app)及游戏区(3), 查看是否出现user, server, mail表信息

操作示例：
step0:

step1:

step2:

step3:

step4&5:

step6:

获取连接
在应用程序服务器以外使用JDBC时，用DriverManager类来管理连接的建立。

以下Java代码展示如何从main()方法为程序注册TcaplusDB-JDBC驱动。如果测试此代码，请确保已正确安装TcaplusDB-JDBC，并已配置CLASSPATH。此外，确保TcaplusDB配置为接受外部TCP/IP连接。
在DriverManager注册驱动后，可以通过调用DriverManager.getConnection()获取连接到指定数据库的Connection实例。

以下示例演示如何从DriverManager获取Connection实例，其中getConnection()方法有两种签名：

//将app_password传入Properties对象Connection conn = null;String url="jdbc:tcaplusdb://192.168.0.1:9999?app_id=2&zone_id=3";Properties connectProperties = new Properties();connectProperties.setProperty("app_password", "123456");try { conn = DriverManager.getConnection(url,connectProperties);} catch (SQLException e) {}

//在url中指定app_passwordConnection conn = null;String url="jdbc:tcaplusdb://192.168.0.1:9999?app_id=2&zone_id=3&app_password='123456'";try { conn = DriverManager.getConnection(url);} catch (SQLException e) {}

Connection建立后可以用来创建Statement和PreparedStatement对象，以及检索有关数据库和表的元数据。

执行sql
Statement对象可以执行基本SQL查询，并通过ResultSet类获取结果。

对从DriverManager.getConnection()获取的Connection对象调用createStatement()方法，则可创建一个Statement实例，之后就可以通过调用executeQuery(String)方法使用SQL语句执行SELECT查询。

如果要更新数据库中的数据，可以使用executeUpdate(String SQL)方法，该方法返回语句匹配的行数，而不是修改的行数。

如果事先不知道sql语句是SELECT还是UPDATE/INSERT，则可以使用execute(String SQL)方法。如果该sql查询是SELECT，该方法将返回true，如果是UPDATE、INSERT或DELETE则返回false。

当语句是SELECT时，可以通过调用getResultSet()方法获取查询结果。当语句是UPDATE，INSERT，DELETE时，可以通过对Statement实例调用getUpdateCount()获取受影响的行数。

以下是执行SELECT查询的示例：

import java.sql.*;public class Demo{ public static void main(String[] args){ Connection connection = null; String url="jdbc:tcaplusdb://192.168.0.1:9999?app_id=2&zone_id=3"; Properties connectProperties = new Properties(); connectProperties.setProperty("app_password", "123456"); try { connection = DriverManager.getConnection(connectURL, connectProperties); Statement statement = connection.createStatement(); try { String SQL = "SELECT * FROM \"user\" WHERE user_id='10000';"; ResultSet resultSet = statement.executeQuery(SQL); try { printResultSet(resultSet); } finally { resultSet.close(); } } finally { statement.close(); } } finally { connection.close(); } }}

TcaplusDB-JDBC参考
驱动程序/数据源类名称
TcaplusDB-JDBC中实现java.sql.Driver的名称为com.tencent.tcaplusdb.Driver。

连接URL语法
通过TcaplusDB-JDBC连接TcaplusDB，链接格式如下：

jdbc:tcaplusdb://<instance_ip>:<instance_port>?app_id=<app_id>&zone_id=<zone_id>&app_password=<app_password>

<instance_ip>为实例主机ip;

<instance_port>为开放端口;

<app_id>为业务id;

<zone_id>为游戏区id;

<app_password>为业务密码;

示例：jdbc:tcaplusdb://127.0.0.1:9999?app_id=2&zone_id=3&app_password="123456"

注意：出于安全考虑，不建议在url指定app_password属性，而是在后续获取连接时指定：

jdbc:tcaplusdb://<instance_ip>:<instance_port>?app_id=<app_id>&zone_id=<zone_id>

API实现说明
主要接口介绍：

BLOB

使用检索方法( getBytes()(等等)在BLOB数据流上。

对于创建了分布式索引的列，您可以使用列别名，该列的值与BLOB的实际名称相同，例如：

SELECT id, "data" from table_name

BLOB实现不允许就地修改(如DatabaseMetaData.locatorsUpdateCopies()方法)。因此，使用相应的PreparedStatement.setBlob()将更改保存回数据库的方法。

连接

isClosed()方法不会ping服务器以确定其是否可用。根据jdbc规范，只有在closed()被连接调用后才返回true。

数据库元数据

可通过getTable(),getColumn()获取元数据

PreparedStatement

在服务器端使用预编译语句时要小心大量使用 setBlob()。若要重新执行将任何大型参数更改为非大型参数的语句，请调用clearParameters()并再次设置所有参数。原因如下：

在服务器端准备的语句和客户端模拟期间，只有在PreparedStatement.execute()被调用情况下才会交换大数据。

一旦完成，用于读取客户端数据的流将被关闭(按照JDBC规范)，并且不能再次读取。

ResultSet

默认情况下，ResultSets将被完全检索并存储在内存中，如果使用流结果，如果希望保持对生成结果集的语句引用的表的并发访问，请尽快处理它们。

数据类型
TcaplusDB-JDBC在处理TcaplusDB数据类型和Java数据类型之间的转换方面具有灵活性。

通常，任何TcaplusDB数据类型都可以转换为java.lang.String，任何数字类型都可以转换为任何Java数值类型，尽管可能会出现舍入、溢出或精度下降的情况。

TcaplusDB和Java数据类型之间的转换

TcaplusDB数据类型 java类型
int8 java.lang.Byte
uint8 java.lang.Byte
int16 java.lang.Short
uint16 java.lang.Short
int32 java.lang.Integer
uint32 java.lang.Integer
int64 java.lang.Long
uint64 java.lang.Long
float java.lang.Float
double java.lang.Double
string java.lang.String
binary byte[]
TcaplusDB和sql数据类型之间的转换

TcaplusDB数据类型 sql类型
int8 sql::DataType::TINYINT (TINYINT)
uint8 sql::DataType::TINYINT (TINYINT UNSIGNED)
int16 sql::DataType::SMALLINT (SMALLINT)
uint16 sql::DataType::SMALLINT (SMALLINT UNSIGNED)
int32 sql::DataType::INTEGER (INT)
uint32 sql::DataType::INTEGER (INT UNSIGNED)
int64 sql::DataType::BIGINT (BIGINT)
uint64 sql::DataType::BIGINT (BIGINT UNSIGNED)
float sql::DataType::REAL (FLOAT)
double sql::DataType::DOUBLE (DOUBLE)
string sql::DataType::VARCHAR (VARCHAR)
binary sql::DataType::VARBINARY (BLOB)
字符集
TcaplusDB将使用java进程的默认字符集。

错误码
TcaplusDB部分常见错误码及说明如下：

错误码 SQL state 描述 说明
-13841 42601 PROXY_ERR_FIELD_NUM_NOT_EQUAL_VALUE_NUM SQL语句中的字段名和字段值数目不相等
3345 42601 PROXY_ERR_INVALID_DATETIME_STRING SQL语句中的日期字符串格式不合法
2065 42703 PROXY_ERR_FIELD_NOT_EXIST SQL语句中的字段不存在
2577 42703 PROXY_ERR_FIELD_IS_NOT_KEY_FIELD SQL语句中的字段不是key字段
2833 42703 PROXY_ERR_FIELD_IS_NOT_VALUE_FIELD SQL语句中的字段不是value字段
785 42P01 PROXY_ERR_NO_SUCH_TABLE SQL语句中的数据表不存在
1297 54011 PROXY_ERR_OVER_MAX_VALUE_FIELD_NUM SQL语句中的字段个数超过了大值
2321 42804 PROXY_ERR_FIELD_TYPE_NOT_MATCH SQL语句中的字段值的类型与表定义中的类型不匹配
-3601 TC004 PROXY_ERR_OVER_MAX_RECORD SQL语句中批量查询的记录数超过了大值
529 TC005 PROXY_ERR_SQL_NOT_SUPPORT 不支持的SQL语句
2309 TXHDB_ERR_RECORD_IS_NOT_SET_TTL 记录未设置过期时间
261 TXHDB_ERR_RECORD_NOT_EXIST 该记录不存在
-261 TXHDB_ERR_INVALID_ARGUMENTS 内部参数错误
-273 PROXY_ERR_INVALID_PARAMS 内部参数错误
-275 API_ERR_OVER_MAX_KEY_FIELD_NUM 主键字段个数超过限制，Generic表限制数为4, List表限制数为3
-517 TXHDB_ERR_INVALID_MEMBER_VARIABLE_VALUE 内部参数错误
-525 SVR_ERR_FAIL_TIMEOUT 存储层请求超时
-529 PROXY_ERR_NO_NEED_ROUTE_BATCHGET_ACTION_MSG_WHEN_NODE_IS_IN_SYNC_STATUS 有损搬迁中部分命令不支持， 目前大多为无损搬迁，不会有该错误码
-531 API_ERR_OVER_MAX_VALUE_FIELD_NUM 非主键字段个数超过限制，Generic表限制数为128, List表限制数：127
-773 TXHDB_ERR_ALREADY_OPEN 引擎文件重复打开
-781 SVR_ERR_FAIL_SHORT_BUFF buf太短，内部错误
-785 PROXY_ERR_NO_NEED_ROUTE_WHEN_NODE_IS_IN_REJECT_STATUS 有损搬迁中部分命令不支持， 目前大多为无损搬迁，不会有该错误码
-787 API_ERR_OVER_MAX_FIELD_NAME_LEN 字段名称大小超过限制（32B）
-1037 SVR_ERR_FAIL_SYSTEM_BUSY 存储层过载， 请联系DBA
-1043 API_ERR_OVER_MAX_FIELD_VALUE_LEN 字段值长度指超过限制
-1293 SVR_ERR_FAIL_RECORD_EXIST insert的记录已存在
-1299 API_ERR_FIELD_NOT_EXSIST 访问的字段不存在， 请确定字段名拼写正确
-1549 SVR_ERR_FAIL_INVALID_FIELD_NAME 访问的字段不存在， 请确定表结构已更新到后端
-1555 API_ERR_FIELD_TYPE_NOT_MATCH 字段值的数据类型与其定义类型不匹配
-1792 GEN_ERR_TABLE_READONLY 表处于只读模式，请检查RCU, WCU或容量是否超出用户设定的阈值
-1805 SVR_ERR_FAIL_VALUE_OVER_MAX_LEN 记录超过大长度，序列化后不能超过10MB
-1811 API_ERR_PARAMETER_INVALID 参数错误
-2048 GEN_ERR_TABLE_READ_DELETE 容量超限， 可读可删， 但不能写
-2061 SVR_ERR_FAIL_INVALID_FIELD_TYPE 表字段类型错误
-2067 API_ERR_OPERATION_TYPE_NOT_MATCH 表类型和命令字不匹配。比如generic表用了list表的命令字
-2304 GEN_ERR_ACCESS_DENIED 拒绝访问
-2317 SVR_ERR_FAIL_SYNC_WRITE tcapsvr_fail_sync_write
-2323 API_ERR_PACK_MESSAGE 打包错误，请联系管理员
-2560 GEN_ERR_INVALID_ARGUMENTS 参数错误，请联系管理员
-2573 SVR_ERR_FAIL_WRITE_RECORD 写引擎错误，请联系管理员
-2579 API_ERR_UNPACK_MESSAGE 解包错误，请联系管理员
-2816 GEN_ERR_UNSUPPORT_OPERATION 不支持的操作，请联系管理员
-2823 ENG_ERR_ENGINE_ERROR 引擎错误，请联系管理员
-2829 SVR_ERR_FAIL_DELETE_RECORD 删除引擎记录失败，请联系管理员
-3072 GEN_ERR_NOT_ENOUGH_MEMORY 内存不足
-3079 ENG_ERR_DATA_ERROR 数据错误，请联系管理员
-3085 SVR_ERR_FAIL_DATA_ENGINE SetFieldName操作指定了错误的字段
-3091 API_ERR_OVER_MAX_RECORD_NUM 客户端访问的表个数超过限制，通常不会出现，出现说明有bug，请联系管理员
-3328 GEN_ERR_NOT_SATISFY_INSERT_FOR_SORTLIST sortlist相关错误码。
-3341 SVR_ERR_FAIL_RESULT_OVERFLOW 字段值大小超过其定义类型的限制
-3347 API_ERR_INVALID_COMMAND 回包的命令不匹配
-3603 API_ERR_NO_MORE_RECORD 没有记录了
-3859 API_ERR_OVER_KEY_FIELD_NUM 超过大key个数限制，当前大8个key，list表少一个
-4109 SVR_ERR_FAIL_INVALID_INDEX list数据类型元素下标超过范围
-4115 API_ERR_OVER_VALUE_FIELD_NUM 超过大value个数限制，当前大256个value，list表少一个
-4365 SVR_ERR_FAIL_OVER_MAXE_FIELD_NUM 超过大字段个数
-4371 API_ERR_OBJ_NEED_INIT API未初始化(或未RegisterTable)
-4621 SVR_ERR_FAIL_MISS_KEY_FIELD 请求缺少主键字段或索引字段
-4627 API_ERR_INVALID_DATA_SIZE 数据大小不对，通常是用户的本地表定义和服务端不一致。
-4883 API_ERR_INVALID_ARRAY_COUNT 数组大小
-5137 PROXY_ERR_PACK_MSG 打包失败
-5139 API_ERR_INVALID_UNION_SELECT 的union的select
-5393 PROXY_ERR_SEND_MSG 发送消息失败
-5395 API_ERR_MISS_PRIMARY_KEY 请求中缺少主键
-5649 PROXY_ERR_ALLOCATE_MEMORY 内存不足
-5651 API_ERR_UNSUPPORT_FIELD_TYPE 不支持的字段类型
-5905 PROXY_ERR_PARSE_MSG 解析消息失败
-5907 API_ERR_ARRAY_BUFFER_IS_SMALL 内存太小
-6157 SVR_ERR_FAIL_LIST_FULL list表元素个数超过定义范围,请设置元素淘汰
-6161 PROXY_ERR_INVALID_MSG 的消息
-6412 SVR_ERR_FAIL_LOW_VERSION 版本太低
-6417 PROXY_ERR_FAILED_PROC_REQUEST_BECAUSE_NODE_IS_IN_SYNC_STASUS 有损搬迁，部分命令不支持，当前主要是无损搬迁，不会遇到该问题
-6669 SVR_ERR_FAIL_HIGH_VERSION 版本太高
-6673 PROXY_ERR_KEY_FIELD_NUM_IS_ZERO 没有key字段
-6925 SVR_ERR_FAIL_INVALID_RESULT_FLAG result_flag设置错误，请参考SDK中result_flag说明
-6929 PROXY_ERR_LACK_OF_SOME_KEY_FIELDS 请求中缺少key字段
-7181 SVR_ERR_FAIL_PROXY_STOPPING 接入层正在停止，业务无需关注，API或自动切换新的接入层
-7185 PROXY_ERR_FAILED_TO_FIND_NODE 找不到路由节点，请联系管理员
-7437 SVR_ERR_FAIL_SVR_READONLY 存储层只读，通常磁盘写满或在进行主备切换
-7441 PROXY_ERR_INVALID_COMPRESS_TYPE 不支持的压缩类型
-7443 API_ERR_INCOMPATIBLE_META 不兼容的表结构， 请检查本地表结构和服务端表结构是否兼容。
-7669 API_ERR_PACK_ARRAY_DATA 打包数组字段失败
-7693 SVR_ERR_FAIL_SVR_READONLY_BECAUSE_IN_SLAVE_MODE 请求发向存储层备节点，可能是正在主备切换。若长时间返回该错误码，请联系管理员
-7697 PROXY_ERR_REQUEST_OVERSPEED 请求速度超过配额
-7949 SVR_ERR_FAIL_INVALID_VERSION 请检查乐观锁，请求记录版本号与实际记录版本号不一致
-7953 PROXY_ERR_SWIFT_TIMEOUT 接入层超时
-7955 API_ERR_PACK_UNION_DATA 打包union数据失败
-8205 SVR_ERR_FAIL_SYSTEM_ERROR 存储层内部错误，请联系管理员
-8209 PROXY_ERR_SWIFT_ERROR 接入层事务非超时类错误，请联系管理员
-8211 API_ERR_PACK_STRUCT_DATA 打包struct失败
-8461 SVR_ERR_FAIL_OVERLOAD 存储层过载
-8465 PROXY_ERR_DIRECT_RESPONSE 接入层直接回包， 相当于不走业务逻辑，通常用于测试API
-8467 API_ERR_UNPACK_ARRAY_DATA 解包数组字段失败
-8717 SVR_ERR_FAIL_NOT_ENOUGH_DADADISK_SPACE 存储层数据盘磁盘空间不足
-8721 PROXY_ERR_INIT_TLOG 初始化日志模块失败
-8723 API_ERR_UNPACK_UNION_DATA 解包union数据失败
-8973 SVR_ERR_FAIL_NOT_ENOUGH_ULOGDISK_SPACE 存储层binlog流水盘磁盘空间不足
-8979 API_ERR_UNPACK_STRUCT_DATA 解包struct数据失败
-9229 SVR_ERR_FAIL_UNSUPPORTED_PROTOCOL_MAGIC 内部错误，不支持的接入层协议magic
-9233 PROXY_ERR_REQUEST_ACCESS_CTRL_REJECT 接入层拒绝访问
-9235 API_ERR_INVALID_INDEX_NAME index不存在
-9485 SVR_ERR_FAIL_UNSUPPORTED_PROTOCOL_CMD 不支持的命令字
-9489 PROXY_ERR_NOT_ALL_NODES_ARE_IN_NORMAL_OR_WAIT_STATUS 遍历请求返回该错误码，因为该表处于搬迁状态
-9491 API_ERR_MISS_PARTKEY_FIELD 缺少partkey字段
-9745 PROXY_ERR_ALREADY_CACHED_REQUEST_TIMEOUT 路由变更时，cache的请求已超时
-9747 API_ERR_ALLOCATE_MEMORY 分配内存失败
-9997 SVR_ERR_FAIL_MERGE_VALUE_FIELD 合并value字段失败，内部错误，请联系管理员
-10001 PROXY_ERR_FAILED_TO_CACHE_REQUEST 路由变更时，cache请求失败
-10003 API_ERR_GET_META_SIZE api_get_meta_size_error
-10253 SVR_ERR_FAIL_CUT_VALUE_FIELD 合并value字段失败，内部错误，请联系管理员
-10257 PROXY_ERR_NOT_EXIST_CACHED_REQUEST 路由变更时，不存在cache请求
-10259 API_ERR_MISS_BINARY_VERSION 内部错误，二进制字段缺失版本
-10509 SVR_ERR_FAIL_PACK_FIELD 内部错误，打包字段失败，请联系管理员
-10513 PROXY_ERR_FAILED_NOT_ENOUGH_CACHE_BUFF 路由变更时，buff不足
-10765 SVR_ERR_FAIL_UNPACK_FIELD 存储层解包失败
-10769 PROXY_ERR_FAILED_PROCESS_CACHED_REQUEST 接入层处理缓存的请求失败
-10771 API_ERR_INVALID_RESULT_FLAG 的result flag
-11021 SVR_ERR_FAIL_LOW_API_VERSION api版本太低，请升级api
-11027 API_ERR_OVER_MAX_LIST_INDEX_NUM list表超过大元素个数
-11277 SVR_ERR_COMMAND_AND_TABLE_TYPE_IS_MISMATCH 操作表的方法不存在
-11283 API_ERR_INVALID_OBJ_STATUE 未初始化， 通常出现在遍历请求中
-11533 SVR_ERR_FAIL_TO_FIND_CACHE 存储层未找到数据分片，内部错误，请联系管理员
-11537 PROXY_ERR_SWIFT_SEND_BUFFER_FULL 发送缓冲区已满， API处理响应太慢
-11539 API_ERR_INVALID_REQUEST 的请求
-11789 SVR_ERR_FAIL_TO_FIND_META 存储层未找到表定义， 内部错误，请联系管理员
-11793 PROXY_ERR_REQUEST_OVERLOAD_CTRL_REJECT 接入层过载
-12045 SVR_ERR_FAIL_TO_GET_CURSOR 存储层获取遍历游标失败， 可能是同时进行的遍历请求太多，通常不会遇到
-12049 PROXY_ERR_SQL_QUERY_MGR_IS_NULL 未创建索引？
-12051 API_ERR_TABLE_NAME_MISSING 未设置表名
-12301 SVR_ERR_FAIL_OUT_OF_USER_DEF_RANGE 超过用户定义的范围
-12307 API_ERR_SOCKET_SEND_BUFF_IS_FULL 请求发送失败，网络过载，请联系管理员。
-12557 SVR_ERR_INVALID_ARGUMENTS 内部参数错误
-12561 PROXY_ERR_GET_TRANSACTION_FAILED 分配失败失败，请联系管理员增加事务并发的配置
-12563 API_ERR_INVALID_MAGIC magic不对，通信出现问题，若一直有该问题，请联系管理员
-12817 PROXY_ERR_ADD_TRANSACTION_FAILED 分配失败失败，请联系管理员增加事务并发的配置
-12819 API_ERR_TABLE_IS_NOT_EXIST 表不存在
-13069 SVR_ERR_NULL_CACHE 不存在该数据分片
-13073 PROXY_ERR_QUERY_FROM_INDEX_SERVER_FAILED 查询全局索引失败
-13075 API_ERR_SHORT_BUFF buff太短
-13329 PROXY_ERR_QUERY_FROM_INDEX_SERVER_TIMEOUT 查询全局索引超时
-13331 API_ERR_FLOW_CONTROL api_flow_control
-13581 SVR_ERR_METALIB_VERSION_LESS_THAN_ENTRY_VERSION the metalib version in request is less than entry version
-13585 PROXY_ERR_QUERY_FOR_CONVERT_TCAPLUS_REQ_TO_INDEX_SERVER_REQ_FAILED 解析全局索引的sql语句失败
-13587 API_ERR_COMPRESS_SWITCH_NOT_SUPPORTED_REGARDING_THIS_CMD 对不支持协议压缩的命令调用的协议压缩SetCompressSwitch
-13837 SVR_ERR_INVALID_SELECT_ID_FOR_UNION 内部错误，请联系管理员
-13841 TC003 PROXY_ERR_QUERY_INDEX_FIELD_NOT_EXIST 索引字段不存在
-13843 API_ERR_FAILED_TO_FIND_ROUTE 后台网络异常，请求无法发送成功，如持续存在请联系管理员
-14093 SVR_ERR_CAN_NOT_FIND_SELECT_ENTRY_FOR_UNION 内部错误，请联系管理员
-14097 TC005 PROXY_ERR_THIS_SQL_IS_NOT_SUPPORT 不支持的SQL
-14099 API_ERR_OVER_MAX_PKG_SIZE 插入的记录超过大小限制（1MB）
-14353 PROXY_ERR_NO_SUCH_APPID 接入层认证失败，未找到该业务认证信息
-14605 SVR_ERR_TCAPSVR_PROCESS_NOT_NORMAL tcapsvr process in abnormal
-14609 PROXY_ERR_NO_APP_USER_PASSWD 接入层找不到用户认证信息
-14865 PROXY_ERR_NO_APP_USER_PASSWD_RECORD 接入层找不到用户认证信息
-15117 SVR_ERR_INVALID_ARRAY_COUNT 的数组大小
-15121 PROXY_ERR_NO_APP_USER_OPT 接入层找不到用户认证信息
-15123 API_ERR_ADD_RECORD failed to add a new record into request
-15373 SVR_ERR_REJECT_REQUEST_BECAUSE_ROUTE_IN_REJECT_STATUS 拒绝请求，svr处于搬迁状态，路由错误。
-15377 PROXY_ERR_NO_APP_USER_OPT_RECORD 接入层未找到用户认证信息
-15379 API_ERR_ZONE_IS_NOT_EXIST 不存在的zone
-15635 API_ERR_TRAVERSER_IS_NOT_EXIST 遍历器不存在
-15885 SVR_ERR_FAIL_INVALID_FIELD_VALUE 的字段值
-16141 SVR_ERR_FAIL_PROTOBUF_FIELD_GET PB表GetRecord操作失败，请联系管理员
-16147 API_ERR_INSTANCE_INIT_LOG_FAILURE 初始化日志模块失败
-16389 TXHDB_ERR_INVALID_VALUE_DATABLOCK_NUM 存储层value块个数异常，请联系管理员
-16397 SVR_ERR_FAIL_PROTOBUF_VALUE_BUFF_EXCEED PB表非主键字段值超过限定大小(256KB)
-16403 API_ERR_CONNECTOR_IS_ABNORMAL 连接异常
-16653 SVR_ERR_FAIL_PROTOBUF_FIELD_UPDATE PB表FieldSetRecord操作失败，请联系管理员
-16659 TC001 API_ERR_WAIT_RSP_TIMEOUT 超时
-16901 TXHDB_ERR_COMPRESSION_FAIL 压缩失败
-16909 SVR_ERR_FAIL_PROTOBUF_FIELD_INCREASE PB表FieldIncRecord操作失败，请联系管理员
-17157 TXHDB_ERR_DECOMPRESSION_FAIL 解压失败
-17165 SVR_ERR_FAIL_PROTOBUF_FIELD_TAG_MISMATCH PB表tag不匹配
-18445 SVR_ERR_FAIL_DOCUMENT_NOT_SUPPORT 不支持Document类请求
-18701 SVR_ERR_FAIL_PARTKEY_INSERT_NOT_SUPPORT 不支持InsertByPartkey
-18957 SVR_ERR_FAIL_SQL_FILTER_FAILED 分布式索引中，执行sql过滤失败
-33541 TXHDB_ERR_ADD_LSIZE_EXCEEDS_MAX_TSD_VALUE_BUFF_SIZE 内部错误，请联系管理员
-34053 TXHDB_ERR_TOO_BIG_KEY_BIZ_SIZE key超过大限制1KB
-34309 TXHDB_ERR_TOO_BIG_VALUE_BIZ_SIZE value超过大限制， 10MB
-34565 TXHDB_ERR_INDEX_NO_EXIST 索引不存在
-39685 TXHDB_ERR_FILE_EXCEEDS_LSIZE_LIMIT 单数据分片超过256GB的大限制，写入失败
TcaplusDB-JDBC的高可用
TcaplusDB为集群部署模式，通常会有多个目录服务器（dir）和多个接入服务器（proxy），目录服务器和接入服务器均为多主部署模式，互为备份。

TcaplusDB-JDBC建立连接时，首先会从用户提供的单个或者多个dir服务器地址中，随机选择一台dir服务器（如果失败，则换一台），并与之建立连接，再从该dir服务器获取到当前新的dir服务器列表和proxy服务器列表，并缓存在本地。

TcaplusDB-JDBC建立连接后，会定时访问dir服务器，获取到当前新的dir服务器列表和proxy服务器列表，并刷新本地缓存。

用户提交的SQL，会由TcaplusDB JDBC从Proxy服务器列表中选取一台可用的，并将SQL发送给该Proxy服务器执行，在些过程中，如果因为Proxy服务器故障，而执行失败，用户可以选择重新提交执行该SQL，TcaplusDB-JDBC会重新选择可用的Proxy服务器执行SQL。

以上过程，封装在TcaplusDB-JDBC内部，用户不感知。

TcaplusDB-JDBC已知问题和SQL局限性
SQL语法的限制
假设数据表demo共有5个字段：key1,key2,key3,value1,value2，其中，key1,key2为partkey，key1,key2,key3组成fullkey。

插入操作
插入操作必须显式指定所有key字段的值，对于没有显式赋值的value字段，如果表定义中有用户定义的默认值，则TcaplusDB以用户定义的默认值填充对应字段；否则，TcaplusDB以系统默认值填充对应字段。

在TcaplusDB系统中，所有数值类型的系统默认值为0，字符串类型的系统默认值为空串（"\0"），二进制类型的系统默认值为空（长度为0）。

插入单条记录的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);

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子句的执行结果可能是多条记录。

删除操作
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;DELETE FROM demo WHERE key1=x1 AND key2=x2 AND key3=x3; DELETE FROM demo WHERE key1=x4 AND key2=x5 AND key3=x6;

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

更新操作
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=x8 AND key2=x9 AND key3=x10;UPDATE demo SET value1=x1, value2=x2 WHERE key1=x3 AND key2=x4 AND key3=x5; UPDATE demo SET value1=x6, value2=x7 WHERE key1=x8 AND key2=x9 AND key3=x10;

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

查询操作
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;

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

全局索引查询
TcaplusDB提供sql查询语句进行索引查询，其中，sql查询条件中的字段必须是建立了全局索引的字段，另外，如果是聚合查询，那么聚合查询的字段也必须是建立了全局索引的字段；

一个索引查询请求，当前限制多返回3000条记录；

由于数据同步到全局索引模块需要约1秒钟的时间，因此，当执行插入或修改操作以后，需要经过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]，比如 between 1 and 100, 是会包含1和100这两个值的，即查询范围为[1,100]

注意：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

部分字段查询
支持查询部分字段的值，比如：

SELECT user_id, `subject` FROM mail WHERE user_id>="10000";

不支持的sql查询语句
不支持聚合查询与非聚合查询混用
select *, a, b from table where a > 1000;

select sum(a), a, b from table where a > 1000;

select count(*), * from table where a > 1000;

不支持order by查询
select * from table where a > 1000 order by a;

不支持group by查询
select * from table where a > 1000 group by a;

不支持having查询
select sum(a) from table where a > 1000 group by a having sum(a) > 10000;

不支持多表联合查询
select * from table1 where table1.a > 1000 and table1.a = table2.b;

不支持嵌套select查询
select * from table where a > 1000 and b in (select b from table where b < 5000);

不支持的其他查询
（1）不支持join查询；

（2）不支持union查询；

（3）不支持类似 select a+b from table where a > 1000 的查询；

（4）不支持类似 select * from table where a+b > 1000 的查询；

（5） 不支持类似 select * from table where a >= b 的查询；

（6）不支持其他未提到的查询；

TcaplusDB-JDBC事务支持
TcaplusDB暂不支持跨数据行的事务。

调用TcaplusDB-JDBC的Connection.commit()方法，实际上是将多条增删改语句（从上次commit到当前时间通过Statement.executeUpdate()方法执行的语句）一并提交给服务端执行。这里需要注意的是，由于多条语句是在同一个请求中发送到服务端，受请求包大小的限制，这里当前限制每次提交的语句上限是100条。

由于暂不支持跨数据行的事务，同一批提交的语句，有可能部分成功，部分失败，此时可以先通过Statement.getUpdateCount()方法，获取实际增删改的数据条，判断是否符合预期，与些同时，也可以通过Statement.getResultSet()获取增删改失败的数据主键信息，后台会通过该接口将失败的数据的主键列的值返回给应用。

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