当前位置：网站首页>[in depth understanding of tcaplus DB technology] Introduction to tcaplus JDBC development

[in depth understanding of tcaplus DB technology] Introduction to tcaplus JDBC development

2022-06-22 20:02:00 【InfoQ】

【 In depth understanding of TcaplusDB technology 】 introduction Tcaplus-JDBC Development

TcaplusDB-JDBC summary

TcaplusDB For use Java Client applications developed in programming languages provide connectivity ,TcaplusDB-JDBC Realized JDBC API And some of its value-added extensions .

TcaplusDB Provides easy to develop features , Including automatic registration with the driver manager 、 Standardization effectiveness check 、 classification SQLExceptions、 Support a large number of update counts .

TcaplusDB-JDBC and Java Version compatibility

**JDBC edition ：**TcaplusDB JDBC Realized JDBC 11.1.0, And compatible with later versions .

**TcaplusDB edition ：**TcaplusDB-JDBC be based on TcaplusDB 3.53.0 Development .

**Java edition ：**TcaplusDB-JDBC be based on java1.8 Development .

Compile required JDK
： compile TcaplusDB-JDBC need JDK8.0 Or later .

TcaplusDB-JDBC Quick start

adopt TcaplusDB-JDBC Connect TcaplusDB, The link format is as follows ：

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

among <instance_ip> For instance host ip;<instance_port> Open port ;<app_id> For the business id,<zone_id> For the game area id, See “ Connect URL grammar ”.

Examples of connecting and reading data ：

import java.sql.*;public class ConnTest { final public static void main(String[] args) { String url = &quot;jdbc:tcaplusdb://192.168.0.1:9999?app_id=2&zone_id=3&quot;; Properties connProperties = new Properties(); connProperties.setProperty(&quot;app_password&quot;, &quot;123456&quot;);//set password try { final Connection connection = DriverManager.getConnection(url,connProperties); try { final Statement statement = connection.createStatement(); try { final String SQL = &quot;SELECT * FROM \&quot;user\&quot; WHERE user_id = '10000'&quot;; 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(&quot;Test failed&quot;); } }}

TcaplusDB-JDBC Installation

Download and install

# Deploy to /root/tcaplusdb-jdbcmkdir /root/tcaplusdb-jdbccd /root/tcaplusdb-jdbc# download wget https://tcaplus-demo-1301716906.cos.ap-guangzhou.myqcloud.com/TcaplusJDBC3.53.1.204689.x86_64_release_20210802.tar.gz# decompression tar -zxvf TcaplusJDBC3.53.1.204689.x86_64_release_20210802.tar.gz

To configure CLASSPATH

decompression

tcaplus-jdbc-[version].jar

To the right place , then JAR bag Java Complete the driver installation in the classpath , Or add its full file path to your

CLASSPATH

environment variable , Or use command line options

-cp

Directly specify the file path to start JVM.

for example , stay Linux On the platform , take TcaplusDB-JDBC Add to

CLASSPATH

According to the command shell Different , Use one of the following forms ：（

Path modification

# 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

You can also set

CLASSPATH

Environment variables in the configuration file , Through the user's local

.profile

.login

, Or other login files , Or by editing the global

/etc/profile

file .

about Windows platform , Environment variables can be set through the system control panel .

Be careful ： Need to add TcaplusDB-JDBC Run the path of the required library to CLASSPATH.

TcaplusDB-JDBC Example

Example table definition

Use xml Definition TcaplusDB surface , Examples are as follows ：

<?xml version=&quot;1.0&quot; encoding=&quot;GBK&quot; standalone=&quot;yes&quot; ?><metalib name=&quot;demo_table&quot; tagsetversion=&quot;1&quot; version=&quot;1&quot;> <struct name=&quot;user&quot; version=&quot;1&quot; primarykey=&quot;user_id,server_id&quot; splittablekey=&quot;user_id&quot;> <entry name=&quot;user_id&quot; type=&quot;string&quot; size=&quot;450&quot; desc=&quot; user ID&quot;/> <entry name=&quot;server_id&quot; type=&quot;uint64&quot; desc=&quot; The server ID&quot; /> <entry name=&quot;nick_name&quot; type=&quot;string&quot; size=&quot;50&quot; desc=&quot; nickname &quot;/> <entry name=&quot;desc&quot; type=&quot;string&quot; size=&quot;1024&quot; desc=&quot; Description information &quot;/> <entry name=&quot;state&quot; type=&quot;Tinyuint&quot; defaultvalue=&quot;0&quot; desc=&quot; User state  0 : AVALIABLE, 1 DELETED&quot;/> <index name=&quot;index1&quot; column=&quot;user_id&quot;/> <index name=&quot;index2&quot; column=&quot;user_id,server_id&quot;/> </struct></metalib>

Elements metalib yes xml The root element of the file .

contain primarykey Of struct Element is a table , It doesn't contain primarykey Of struct The element is an ordinary structure .

Every time the table structure is modified , The version attribute value needs to be added accordingly 1, The initial version is always 1.

primarykey Property specifies the primary key field ; about generic surface , You can specify at most 8 Primary key fields , about list surface , You can specify 7 individual .

splittablekey Property is equivalent to a partition key （shard key）,TcaplusDB Tables are split and stored to multiple storage nodes .splittablekey Must be one of the primary key fields , A good splittablekey It should be highly decentralized , This means a wide range of values , String type is recommended .

desc Property contains the description of the current element .

entry Element defines a field , Supported value types include int32,string,char,int64,double,short etc. .

index Element defines an index , The index must contain splittablekey. Because you can use the primary key to query the table , Therefore, the index should not be the same as the primary key attribute .

Sample table creation

open web Console , After logging in , Follow these steps to create a sample table

# step0, Download table definition file . stay Chrome Browser access ：https://tcaplus-demo-1301716906.cos.ap-guangzhou.myqcloud.com/table-define.xml  Right click the web page , Save as file .# step1, Use Chrome browser , Sign in  web  View console , Open the browser , Input  web  Address :[cvm  Extranet  ip]:80, Account passwords are tcaplus. Open... In the menu bar ： The business management ＝〉 Watch management .# step2, page Tab Column , Choose ： Table to add # step3, Select the business and cluster and check the game area ,  colony ：test_set(1),  Business ：tdr_app(2),  Game Zone ID: 3,  Click again ： Batch add table # step4, In the page that comes out , Browse to the bottom of the page , Click on ： Add... From local file , Select the sample table definition file downloaded from the above resources in the pop-up page :table-define.xml# step5, Click on ： Submit , establish 3 A sample table : user, server, mail# step6, Check whether the table is created ok, Get into ： The business management => Watch management , Select the corresponding business (tdr_app) And the game area (3),  See if user, server, mail Table information

The operation sample ：

step0:

step1:

step2:

step3:

step4&5:

step6:

Get the connection

Use outside the application server JDBC when , use

DriverManager

Class to manage the establishment of connections .

following Java The code shows how to start from

main()

Method to register for the program TcaplusDB-JDBC drive . If you test this code , Make sure that... Is installed correctly TcaplusDB-JDBC, And configured

CLASSPATH

. Besides , Make sure TcaplusDB Configured to accept external data TCP/IP Connect . stay

DriverManager

After registering the driver , You can call

DriverManager.getConnection()

Gets the connection to the specified database

Connection

example .

The following example demonstrates how to start from

DriverManager

obtain

Connection

example , among

getConnection()

Methods have two types of signatures ：

// take app_password Pass in Properties object Connection conn = null;String url=&quot;jdbc:tcaplusdb://192.168.0.1:9999?app_id=2&zone_id=3&quot;;Properties connectProperties = new Properties();connectProperties.setProperty(&quot;app_password&quot;, &quot;123456&quot;);try { conn = DriverManager.getConnection(url,connectProperties);} catch (SQLException e) {}

// stay url It is specified in app_passwordConnection conn = null;String url=&quot;jdbc:tcaplusdb://192.168.0.1:9999?app_id=2&zone_id=3&app_password='123456'&quot;;try { conn = DriverManager.getConnection(url);} catch (SQLException e) {}

Connection

It can be used to create

Statement

and

PreparedStatement

object , And retrieve metadata about databases and tables .

perform sql

Statement

Object can perform basic functions SQL Inquire about , And pass

ResultSet

Class to get the result .

From the

DriverManager.getConnection()

Acquired

Connection

Object call

createStatement()

Method , You can create a

Statement

example , Then you can call

executeQuery(String)

Methods use SQL Statement execution SELECT Inquire about .

If you want to update the data in the database , have access to

executeUpdate(String SQL)

Method , This method returns the number of rows matched by the statement , Not the number of rows modified .

If you don't know in advance sql The sentence is SELECT still UPDATE/INSERT, You can use

execute(String SQL)

Method . If it's time to sql Query is SELECT, This method will return

true

, If it is UPDATE、INSERT or DELETE Then return to

false

When the statement is SELECT when , You can call

getResultSet()

Method to get the query result . When the statement is UPDATE,INSERT,DELETE when , It can be done by

Statement

The instance

getUpdateCount()

Get the number of rows affected .

Here's the execution SELECT Examples of queries ：

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

TcaplusDB-JDBC Reference resources

The driver / Data source class name

TcaplusDB-JDBC To realize

java.sql.Driver

For the name of the

com.tencent.tcaplusdb.Driver

Connect URL grammar

adopt TcaplusDB-JDBC Connect TcaplusDB, The link format is as follows ：

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

<instance_ip> For instance host ip;

<instance_port> Open port ;

<app_id> For the business id;

<zone_id> For the game area id;

<app_password> For business password ;

Example ：

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

Be careful ： For safety reasons , Not recommended in url Appoint app_password attribute , Instead, you specify... When you get a connection later ：

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

API Implementation notes

Main interface introduction ：

BLOB

Use the search method (
getBytes()
( wait ) stay BLOB On the data stream .

For columns with distributed indexes created , You can use column aliases , The value of this column is the same as BLOB The actual name of the is the same , for example ：

 SELECT id, &quot;data&quot; from table_name

BLOB The implementation does not allow local modification ( Such as

DatabaseMetaData.locatorsUpdateCopies()

Method ). therefore , Use corresponding

PreparedStatement.setBlob()

How to save changes back to the database .

Connect

isClosed()
No way ping Server to determine if it is available . according to jdbc standard , Only in
closed()
It returns after being called by the connection true.

Database metadata

It can be done by
getTable()
,
getColumn()
Fetch metadata

PreparedStatement

Be careful when using precompiled statements on the server side
setBlob()
. To re execute a statement that changes any large parameter to a non large parameter , Please call
clearParameters()
And set all parameters again . Here's why ：

During server-side prepared statements and client-side simulation , Only in
PreparedStatement.execute()
Big data will be exchanged only when called .

Once that is done , The stream used to read client data will be closed ( according to JDBC standard ), And cannot be read again .

ResultSet

By default ,ResultSets Will be completely retrieved and stored in memory , If you use stream results , If you want to maintain concurrent access to the tables referenced by the statements that generate the result set , Please deal with them as soon as possible .

data type

TcaplusDB-JDBC Processing TcaplusDB Data types and Java Flexibility in conversion between data types .

Usually , whatever TcaplusDB Data types can be converted to

java.lang.String

, Any number type can be converted to any Java value type , Although rounding may occur 、 Overflow or loss of accuracy .

TcaplusDB and Java Conversion between data types

TcaplusDB and sql Conversion between data types

Character set

TcaplusDB Will use java Default character set for process .

Error code

TcaplusDB Some common error codes and descriptions are as follows ：

TcaplusDB-JDBC High availability

TcaplusDB Deploy mode for cluster , There are usually multiple directory servers （dir） And multiple access servers （proxy）, Both the directory server and the access server are in the multi master deployment mode , Backup each other .

TcaplusDB-JDBC When establishing a connection , First, it will start from a single or multiple... Provided by the user dir Server address , Randomly select one dir The server （ If you fail , Then change one ）, And connect with it , And then it's time to dir The server gets the latest dir Server list and proxy Server list , And cache it locally .

TcaplusDB-JDBC Once the connection is established , Will visit regularly dir The server , Get the latest dir Server list and proxy Server list , And refresh the local cache .

User submitted SQL, Will be TcaplusDB JDBC from Proxy Select an available server from the server list , And will SQL Send to this Proxy Server execution , In the process , If because Proxy Server failure , And the execution failed , The user can choose to resubmit the execution SQL,TcaplusDB-JDBC The available... Will be re selected Proxy Server execution SQL.

The above process , Packaged in TcaplusDB-JDBC Inside , Users don't perceive .

TcaplusDB-JDBC Known problems and SQL limitations

SQL The limitation of grammar

Suppose the data sheet demo share 5 A field ：key1,key2,key3,value1,value2, among ,key1,key2 by partkey,key1,key2,key3 form fullkey.

The insert

The insert operation must explicitly specify all key Value of field , For... Without explicit assignment value Field , If there are user-defined default values in the table definition , be TcaplusDB Populate the corresponding fields with user-defined default values ; otherwise ,TcaplusDB Fill in the corresponding fields with the system default values .

stay TcaplusDB In the system , The system default value for all numeric types is 0, The system default value of string type is empty string （"\0"）, The system default value of binary type is null （ The length is 0）.

Insert the of a single record SQL The sentence form is as follows ：

INSERT INTO demo (key1,key2,key3,value1,value2) VALUES (x1,x2,x3,x4,x5);

Insert multiple records SQL The sentence form is as follows ：

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 Clause syntax restrictions

When the global index is not configured ,where The filter field in the clause consists of two parts ：1、 Required part ：partkey or fullkey;2、 Optional part ： Filter conditions .

partkey or fullkey： Only equivalent queries can be performed , And the composition partkey or fullkey You can only use... Between the fields of AND Connect ;

Filter conditions ： Support NOT、=、>、<、!=、>=、<= Operator , And multiple filter conditions can be used AND or OR Connect , Support key Field or value Field .

1、 Use fullkey When deleting, modifying and querying where The clause form is as follows ：

WHERE key1=x1 AND key2=x2 AND key3=x3;

2、 Use fullkey+ When deleting, modifying, and querying filter conditions where The clause form is as follows , If the filter conditions include OR Operator , The filter conditions must be bracketed ：

WHERE key1=x1 AND key2=x2 AND key3=x3 AND ( Filter conditions );

3、 Use partkey When deleting, modifying and querying where The clause form is as follows ：

WHERE key1=x1 AND key2=x2;

4、 Use partkey+ When deleting, modifying, and querying filter conditions where The clause form is as follows , If the filter conditions include OR Operator , The filter conditions must be bracketed ：

WHERE key1=x1 AND key2=x2 AND ( Filter conditions );

When where The required part in the clause is partkey when ,where Clause may result in multiple records .

Delete operation

1、 adopt fullkey When deleting a single record ,SQL The statement has the following two forms ：

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 ( Filter conditions );

2、 adopt fullkey When deleting records in batch ,SQL The statement has the following two forms ：

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;

Delete / Batch delete operation is not supported partkey, The batch deletion operation does not support the filter criteria .

update operation

1、 adopt fullkey When updating a single record ,SQL The statement has the following two forms ：

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 ( Filter conditions );

2、 adopt fullkey When updating records in batch ,SQL The statement has the following two forms ：

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;

to update / Batch update operation does not support partkey, The batch update operation does not support the filter criteria .

Query operation

1、 adopt fullkey When querying a single record ,SQL Statements have the following four forms ：

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 ( Filter conditions );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 ( Filter conditions );

2、 adopt partkey When querying multiple records ,SQL Statements have the following four forms ：

SELECT * FROM demo WHERE key1=x1 AND key2=x2;SELECT * FROM demo WHERE key1=x1 AND key2=x2 AND ( Filter conditions );SELECT key1,value1 FROM demo WHERE key1=x1 AND key2=x2;SELECT key1,value1 FROM demo WHERE key1=x1 AND key2=x2 AND ( Filter conditions );

3、 adopt fullkey When querying records in batch ,SQL The form of the statement is as follows ：

SELECT * FROM demo WHERE key1=x1 AND key2=x2 AND key3=x3 OR key1=x4 AND key2=x5 AND key3=x6;

The batch query operation does not support the filter criteria .

4、 adopt partkey When querying records in batch ,SQL The form of the statement is as follows ：

SELECT * FROM demo WHERE key1=x1 AND key2=x2 OR key1=x3 AND key2=x4;

The batch query operation does not support the filter criteria .

Global index query

TcaplusDB Provide sql Index query with query statement , among ,sql The field in the query criteria must be a field with a global index , in addition , If it is an aggregate query , Then the field of the aggregate query must also be a field with a global index ;

An index query request , The current limit is to return... At most 3000 Bar record ;

Since data synchronization to the global index module takes about 1 Seconds , therefore , After performing an insert or modify operation , Need to go through 1 It takes about seconds to query the latest data .

Supported by sql Query statement

Conditions of the query

Support =, >, >=, <, <=, !=, between, in, not in, like, not like, and, or , such as :

SELECT * FROM `mail` WHERE user_id>=&quot;10004&quot; AND server_id=100;SELECT * FROM `mail` WHERE user_id BETWEEN 10000 AND 10003 AND server_id=100;SELECT * FROM `mail` WHERE user_id=&quot;10000&quot; AND server_id=100 AND mail_id LIKE &quot;210507%&quot;;SELECT * FROM `mail` WHERE user_id>=&quot;10004&quot; OR server_id<=200;

Be careful ：between When inquiring ,between a and b, The corresponding query range is [a, b], such as between 1 and 100, Yes, it will contain 1 and 100 These two values are , That is, the query range is [1,100]

Be careful ：like Query supports fuzzy matching , among "%" wildcard , matching 0 One or more characters ; “_” wildcard , matching 1 Characters ;

Paging query

Support limit offset Paging query , such as ：

SELECT * FROM mail WHERE user_id>&quot;10000&quot; LIMIT 100 OFFSET 2;

Be careful ： At present limit Must be with offset Use it with , That is not supported limit 1 perhaps limit 0,1 such ;

Aggregate query

Currently supported aggregate queries include ：sum, count, max, min, avg, such as ：

SELECT server_id, COUNT(DISTINCT user_id), COUNT(*), SUM(state) FROM `mail` WHERE user_id>=&quot;10000&quot; AND server_id=100;

Be careful ： Aggregate queries do not support limit offset, namely limit offset Don't take effect ;

Be careful ： At present, only count Support distinct, namely select count(distinct(a)) from table where a > 1000; Nothing else supports distinct

Partial field query

Supports querying the values of some fields , such as ：

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

Don't support sql Query statement

Mixing aggregate queries with non aggregate queries is not supported

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;

I won't support it order by Inquire about

select * from table where a > 1000 order by a;

I won't support it group by Inquire about

select * from table where a > 1000 group by a;

I won't support it having Inquire about

select sum(a) from table where a > 1000 group by a having sum(a) > 10000;

Multi table joint query is not supported

select * from table1 where table1.a > 1000 and table1.a = table2.b;

Nesting... Is not supported select Inquire about

select * from table where a > 1000 and b in (select b from table where b < 5000);

Other queries not supported

（1） I won't support it join Inquire about ;

（2） I won't support it union Inquire about ;

（3） Does not support similar select a+b from table where a > 1000 Query for ;

（4） Does not support similar select * from table where a+b > 1000 Query for ;

（5） Does not support similar select * from table where a >= b Query for ;

（6） Other queries not mentioned are not supported ;

TcaplusDB-JDBC Transaction support

TcaplusDB Cross row transactions are not supported at the moment .

call TcaplusDB-JDBC Of Connection.commit() Method , In fact, it is to add, delete and modify multiple statements （ From the last time commit Pass... At the current time Statement.executeUpdate() Method ） Submit it to the server for execution . What needs to be noted here is , Because multiple statements are sent to the server in the same request , Limited by the size of the requested packet , The current limit for each statement submitted here is 100 strip .

Because cross row transactions are not supported for the time being , Statements submitted in the same batch , It may be partially successful , Partial failure , Now you can go through Statement.getUpdateCount() Method , Get the actual added, deleted and modified data bar , Whether the expectation meets the judgment , At the same time , It can also be done through Statement.getResultSet() Get the data primary key information that failed to add, delete or modify , The background will return the value of the primary key column of the failed data to the application through this interface .

TcaplusDB It's a distributed product of Tencent NoSQL database , The code for storage and scheduling is completely self-developed . With cache + Landing fusion architecture 、PB Levels of storage 、 Millisecond delay 、 Lossless horizontal expansion and complex data structure . At the same time, it has rich ecological environment 、 Easy migration 、 Extremely low operation and maintenance costs and five nine high availability features . Customer coverage game 、 Internet 、 government affairs 、 Finance 、 Manufacturing and the Internet of things .

原网站

版权声明
本文为[InfoQ]所创，转载请带上原文链接，感谢
https://yzsam.com/2022/173/202206221832199969.html