With the release of version TDEngine-2.0.14.0, we have added a new implementation for the JDBC Connector: JDBC-RESTful. It uses a RESTful interface internally instead of TAOSC to connect to the Tdengine server, which enables cross-platform development of Tdengine applications on Linux, Windows, and Mac. In particular, you don’t have to worry about updating TDEngine without synchronizing the upgrade client.

01 Benefits of using JDBC-RESTful

1. Realize the cross-platform application development of TDEngine

Previously, because the JDBC driver for Tdengine relies on native dynamic libraries (libtaos.so on Linux and taos.dll on Windows), developers needed to install the client locally first. Otherwise, the application will report an error:

no taos in java.library.path

Tdengine currently only supports Linux and Windows client packages, and the source code cannot be compiled on other operating systems. For users using MacOS, the need to write code on MacOS and then deploy it to a Linux server for debugging, or use IDE tools such as VS Code to support remote code development, all of which increase the development cost of using Tdengine. That’s why we developed JDBC-RESTful. After using JDBC-RESTful, there is no need to install the client! No need to use an IDE for remote code development! You can also do development on the MacBook.

2. No need to install and upgrade the TDEngine client

With JDBC-RESTful, there is no need to install the TDEngine client, nor to follow the server to upgrade the client. For enterprise application development, TDEngine is maintained and upgraded by dedicated operation personnel. After server upgrade, the application does not need to upgrade the client.

3. Neglect migration and usage costs

To use JDBC-RESTful, you only need to modify the DriverClass and URL. For most Java applications, this is a simple change to the configuration file.

Next, a detailed description of the concepts and usage of JDBC-RESTful is given.

How JDBC-RESTful is implemented

Currently, the JDBC Connector is implemented in two forms: JDBC-JNI and JDBC-RESTful.

  • Jdbc-jni: Use JNI to call local methods of client libtaos.so (or taos. DLL) to communicate with taosd through socket.
  • JDBC-RESTful: The TAOSD example encapsulates the RESTful interface of TDEngine internally, encapsulating SQL as HTTP requests to send to the server side.

The figure above shows three ways that Java applications can access TdEngine using connectors:

  • JDBC – the JNI: Java applications on physical node1 (pnode1) use the JDBC-JNI API and directly call the client API (libtaos.so or taos.dll) to send write and query requests to the Taosd instance on physical node2 (pnode2).
  • RESTful: The application sends the SQL to the RESTful connector on the physical node2 (pnode2) and then calls the client API (libtaos.so).
  • JDBC-RESTful: The Java application encapsulates the SQL into a RESTful request through the JDBC-RESTful API and sends it to the RESTful connector on the physical node 2.

Examples of JDBC-RESTful usage

To use the JDBC-RESTful interface, compared to the previous JDBC-JNI, you only need:

  1. DriverClass designated as “com. Taosdata. JDBC. Rs. RestfulDriver”;
  2. JdbcUrl starts with “JDBC: taos-rs ://”;
  3. Use 6041 as the connection port.

Below, show a complete example of using JDBC-RESTful.

1. Introducing the TAOS – JDBCDDriver dependency in POM.xml

< the dependency > < groupId > com. Taosdata. JDBC < / groupId > < artifactId > taos - jdbcdriver < / artifactId > < version > 2.0.18 < / version > </dependency>

2. Sample code

public class JdbcRestfulDemo { private static final String host = "taos-server"; public static void main(String[] args) { try { // load JDBC-restful driver Class.forName("com.taosdata.jdbc.rs.RestfulDriver"); // use port 6041 in url when use JDBC-restful String url = "jdbc:TAOS-RS://" + host + ":6041/? user=root&password=taosdata"; Properties properties = new Properties(); properties.setProperty("charset", "UTF-8"); properties.setProperty("locale", "en_US.UTF-8"); properties.setProperty("timezone", "UTC-8"); Connection conn = DriverManager.getConnection(url, properties); Statement stmt = conn.createStatement(); stmt.execute("create database if not exists restful_test"); stmt.execute("use restful_test"); stmt.execute("create table restful_test.weather(ts timestamp, temperature float) tags(location nchar(64))"); STMT. ExecuteUpdate ("insert into t1 using restful_test.weather tags(' Beijing ') values(now, 18.2)"); ResultSet rs = stmt.executeQuery("select * from restful_test.weather"); ResultSetMetaData meta = rs.getMetaData(); while (rs.next()) { for (int i = 1; i <= meta.getColumnCount(); i++) { System.out.print(meta.getColumnLabel(i) + ": " + rs.getString(i) + "t"); } System.out.println(); } rs.close(); stmt.close(); conn.close(); } catch (ClassNotFoundException e) { e.printStackTrace(); } catch (SQLException e) { e.printStackTrace(); }}}

JDBC-RESTful Performance

From the above JDBC-RESTful implementation principle, we can see that the JDBC-RESTful approach is equivalent to encapsulating the C methods of libtaos.so twice. The first time, RESTful encapsulates the methods in libtaos.so. The second one is TAOS – JDBCDDriver encapsulating the RESTful interface. In addition, using JDBC-RESTful means that all access requests to the database are sent to the server, and the server side needs to do all the SQL parsing, result aggregation and other work that the client is responsible for. So does using the JDBC-RESTful interface cause performance degradation? We performed performance tests internally on the JDBC-RESTful interface.

Test environment: CPU: Mac Pro (6 cores, Intel Core i7), Memory: 16 GB, Hard Drive: SSD (500GB)

Test record:

Test Conclusions:

  1. JDBC-RESTful write performance is about 50% better than JDBC-JNI when the number of records inserted per SQL is low.
  2. The JDBC-RESTful write performance is about 90% of the JDBC-JNI performance when the number of records inserted per SQL is high.
  3. There is no significant difference in query performance between JDBC-RESTful and JDBC-JNI.

Note: The write performance and query performance of the above tests are dependent on the specific test environment and configuration, with slightly different performance differences in different test environments.

conclusion

Here are some suggestions for Java developers using JDBC-RESTful:

  1. JDBC-RESTful provides cross-platform development features that can be used in a development environment.
  2. JDBC-JNI has certain performance advantages over JDBC-RESTful. If you want to maximize the performance of TDEngine in a production environment, you can use the JDBC-JNI approach.
  3. Switching from JDBC-RESTful to JDBC-JNI is quite simple, usually just by modifying the configuration file.

Click here to give JDBC-RESTful a try.