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

其中为实例主机ip；为开放端口；为业务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表，示例如下：

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

• 为实例主机ip;

• 为开放端口;

• 为业务id;

• 为游戏区id;

• 为业务密码;

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