Quick Start: Java and TimescaleDB

Goal

This quick start guide is designed to get Java developers up and running with TimescaleDB as their database. In this tutorial, you’ll learn how to:

Pre-requisites

To complete this tutorial, you need a cursory knowledge of the Structured Query Language (SQL). The tutorial walks you through each SQL command, but it is helpful if you’ve seen SQL before.

To start, install TimescaleDB. Once your installation is complete, you can proceed to ingesting or creating sample data and finishing the tutorial.

You also need to install Java Development Kit (JDK) and PostgreSQL Java Database Connectivity (JDBC) Driver as well. All code is presented for Java 16 and above. If you are working with older JDK versions, use legacy coding techniques.

Connect Java to TimescaleDB

Step 1: Create a new Java application

For simplicity, this tutorial uses the application in a single file as an example. You can use any of your favorite build tools, including gradle and maven.

Create a separate directory and navigate to it. In it, create a text file with name and extension Main.java and the following content:

  2. package com.timescale.java;
  4. public class Main {
  6.     public static void main(String... args) {
  8.         System.out.println("Hello, World!");
  10.     }
  12. }

From the command line in the current directory, try running the application with this command:

  2. java Main.java

You should see the Hello, World! line output to your console. In case of an error, refer to the documentation and check if the JDK was installed correctly. You don’t have to create directory structure ./com/timescale/java similar to package path in source file. You should just create a single java file in empty folder and run java Main.java from it.

Step 2: Import Postgres JDBC driver

To work with the PostgreSQL, you need to import the appropriate JDBC Driver. If you are using a dependency manager, include PostgreSQL JDBC Driver as dependency. In this case, download jar artifact of JDBC Driver and place it next to the Main.java file.

Now you can import the JDBC Driver into the Java application and display a list of available drivers for the check:

  2. package com.timescale.java;
  4. import java.sql.DriverManager;
  6. public class Main {
  8.     public static void main(String... args) {
  10.         DriverManager.drivers().forEach(System.out::println);
  12.     }
  14. }

Use this command to run all the following examples:

  2. java -cp *.jar Main.java

You should end up with something like [[email protected]](https://docs.timescale.com/cdn-cgi/l/email-protection). This means that you are ready to connect to TimescaleDB from Java.

Step 3: Compose a database connection string

Locate your TimescaleDB credentials. You need these to compose a connection string for JDBC to use to connect to your TimescaleDB instance.

You’ll need these credentials:

  • host
  • port
  • database name
  • username
  • password

Next, compose your connection string variable using this format:

  2. var connUrl = "jdbc:postgresql://<HOSTNAME>:<PORT>/<DATABASE_NAME>?user=<USERNAME>&password=<PASSWORD>";

Full documentation on the formation of the connection string can be found in the official documentation of the PostgreSQL JDBC Driver.

warning

The above method of composing a connection string is for test or development purposes only, for production purposes be sure to make sensitive details like your password, hostname, and port number environment variables.

Step 4: Connect to TimescaleDB instance using the PostgreSQL JDBC driver

Change the code to connect to the database server and verify that all settings are correct:

  2. package com.timescale.java;
  4. import java.sql.DriverManager;
  6. import java.sql.SQLException;
  8. public class Main {
  10.     public static void main(String... args) throws SQLException {
  12.         var connUrl = "jdbc:postgresql://<HOSTNAME>:<PORT>/<DATABASE_NAME>?user=<USERNAME>&password=<PASSWORD>";
  14.         var conn = DriverManager.getConnection(connUrl);
  16.         System.out.println(conn.getClientInfo());
  18.     }
  20. }

Run with the java -cp *.jar Main.java command and you should see this output: {ApplicationName=PostgreSQL JDBC Driver}.

Congratulations, you’ve successfully connected to TimescaleDB using Java.

Create a relational table

Step 1: Formulate your SQL statement

First, compose a string which contains the SQL state that you would use to create a relational table. In this example, we create a table called sensors, with columns id, type and location:

  2. CREATE TABLE sensors (
  4.     id SERIAL PRIMARY KEY,
  6.     type TEXT NOT NULL,
  8.     location TEXT NOT NULL
  10. );

Step 2: Execute the SQL statement and commit changes

Next, execute the CREATE TABLE query by creating a statement, executing the query from Step 1 and check that table was created with SELECT statement:

  2. package com.timescale.java;
  4. import java.sql.DriverManager;
  6. import java.sql.SQLException;
  8. public class Main {
  10.     public static void main(String... args) throws SQLException {
  12.         var connUrl = "jdbc:postgresql://<HOSTNAME>:<PORT>/<DATABASE_NAME>?user=<USERNAME>&password=<PASSWORD>";
  14.         var conn = DriverManager.getConnection(connUrl);
  16.         var createSensorTableQuery = """
  18.                 CREATE TABLE sensors (
  20.                     id SERIAL PRIMARY KEY,
  22.                     type TEXT NOT NULL,
  24.                     location TEXT NOT NULL
  26.                 )
  28.                 """;
  30.         try (var stmt = conn.createStatement()) {
  32.             stmt.execute(createSensorTableQuery);
  34.         }
  36.         var showAllTablesQuery = "SELECT tablename FROM pg_catalog.pg_tables WHERE schemaname = 'public'";
  38.         try (var stmt = conn.createStatement();
  40.              var rs = stmt.executeQuery(showAllTablesQuery)) {
  42.             System.out.println("Tables in the current database: ");
  44.             while (rs.next()) {
  46.                 System.out.println(rs.getString("tablename"));
  48.             }
  50.         }
  52.     }
  54. }

Congratulations, you’ve successfully created a relational table in TimescaleDB using Java.

Generate a hypertable

In TimescaleDB, the primary point of interaction with your data is a hypertable, the abstraction of a single continuous table across all space and time intervals, such that one can query it via standard SQL.

Virtually all user interactions with TimescaleDB are with hypertables. Creating tables and indexes, altering tables, inserting data, and selecting data, can (and should) all be executed on the hypertable.

A hypertable is defined by a standard schema with column names and types, with at least one column specifying a time value.

Step 1: Create sensors data table

First, we create CREATE TABLE SQL statement for our hypertable. Notice how the hypertable has the compulsory time column:

  2. CREATE TABLE sensor_data (
  4.     time TIMESTAMPTZ NOT NULL,
  6.     sensor_id INTEGER REFERENCES sensors (id),
  8.     value DOUBLE PRECISION
  10. );

Step 2: Create hypertable for sensors data

Next, you can formulate the SELECT statement to convert the table we created in Step 1 into a hypertable. Note that you must specify the table name to convert to a hypertable and its time column name as the two arguments, as mandated by the create_hypertable docs:

  2. SELECT create_hypertable('sensor_data', 'time');

Step 3: Execute previous steps from your Java code

Now you can bring it all together by executing the statement from step 1, then executing the statement from step 2 and committing your changes to the database:

  2. package com.timescale.java;
  4. import java.sql.Connection;
  6. import java.sql.DriverManager;
  8. import java.sql.SQLException;
  10. import java.util.List;
  12. public class Main {
  14.     public static void main(String... args) {
  16.         final var connUrl = "jdbc:postgresql://<HOSTNAME>:<PORT>/<DATABASE_NAME>?user=<USERNAME>&password=<PASSWORD>";
  18.         try (var conn = DriverManager.getConnection(connUrl)) {
  20.             createSchema(conn);
  22.             insertData(conn);
  24.         } catch (SQLException ex) {
  26.             System.err.println(ex.getMessage());
  28.         }
  30.     }
  32.     private static void createSchema(final Connection conn) throws SQLException {
  34.         try (var stmt = conn.createStatement()) {
  36.             stmt.execute("""
  38.                     CREATE TABLE sensors (
  40.                         id SERIAL PRIMARY KEY,
  42.                         type TEXT NOT NULL,
  44.                         location TEXT NOT NULL
  46.                     )
  48.                     """);
  50.         }
  52.         try (var stmt = conn.createStatement()) {
  54.             stmt.execute("""
  56.                     CREATE TABLE sensor_data (
  58.                         time TIMESTAMPTZ NOT NULL,
  60.                         sensor_id INTEGER REFERENCES sensors (id),
  62.                         value DOUBLE PRECISION
  64.                     )
  66.                     """);
  68.         }
  70.         try (var stmt = conn.createStatement()) {
  72.             stmt.execute("SELECT create_hypertable('sensor_data', 'time')");
  74.         }
  76.     }
  78. }

Congratulations, you’ve successfully created a hypertable in your TimescaleDB database using Java.

Insert a batch of rows into TimescaleDB

Here’s a typical pattern you could use to insert some data into a table. In the example below, insert the relational data from list of sensors, into the relational table named sensors.

First, open a connection to the database, then using prepared statements formulate the INSERT SQL statement and then execute that statement:

  2. final List<Sensor> sensors = List.of(
  4.         new Sensor("temperature", "bedroom"),
  6.         new Sensor("temperature", "living room"),
  8.         new Sensor("temperature", "outside"),
  10.         new Sensor("humidity", "kitchen"),
  12.         new Sensor("humidity", "outside"));
  14. for (final var sensor : sensors) {
  16.     try (var stmt = conn.prepareStatement("INSERT INTO sensors (type, location) VALUES (?, ?)")) {
  18.         stmt.setString(1, sensor.type());
  20.         stmt.setString(2, sensor.location());
  22.         stmt.executeUpdate();
  24.     }
  26. }

You can insert a batch of rows into TimescaleDB in a couple of different ways. Let’s see what it looks like to insert a number of rows with batching mechanism. For simplicity’s sake, we’ll use PostgreSQL to generate some sample time-series data in order to insert into the sensor_data hypertable:

  2. final var sensorDataCount = 100;
  4. final var insertBatchSize = 10;
  6. try (var stmt = conn.prepareStatement("""
  8.         INSERT INTO sensor_data (time, sensor_id, value)
  10.         VALUES (
  12.             generate_series(now() - INTERVAL '24 hours', now(), INTERVAL '5 minutes'),
  14.             floor(random() * 4 + 1)::INTEGER,
  16.             random()
  18.         )
  20.         """)) {
  22.     for (int i = 0; i < sensorDataCount; i++) {
  24.         stmt.addBatch();
  26.         if ((i > 0 && i % insertBatchSize == 0) || i == sensorDataCount - 1) {
  28.             stmt.executeBatch();
  30.         }
  32.     }
  34. }

Below is a complete listing of the application, from creating tables to filling in the data:

  2. package com.timescale.java;
  4. import java.sql.Connection;
  6. import java.sql.DriverManager;
  8. import java.sql.SQLException;
  10. import java.util.List;
  12. public class Main {
  14.     public static void main(String... args) {
  16.         final var connUrl = "jdbc:postgresql://<HOSTNAME>:<PORT>/<DATABASE_NAME>?user=<USERNAME>&password=<PASSWORD>";
  18.         try (var conn = DriverManager.getConnection(connUrl)) {
  20.             createSchema(conn);
  22.             insertData(conn);
  24.         } catch (SQLException ex) {
  26.             System.err.println(ex.getMessage());
  28.         }
  30.     }
  32.     private static void createSchema(final Connection conn) throws SQLException {
  34.         try (var stmt = conn.createStatement()) {
  36.             stmt.execute("""
  38.                     CREATE TABLE sensors (
  40.                         id SERIAL PRIMARY KEY,
  42.                         type TEXT NOT NULL,
  44.                         location TEXT NOT NULL
  46.                     )
  48.                     """);
  50.         }
  52.         try (var stmt = conn.createStatement()) {
  54.             stmt.execute("""
  56.                     CREATE TABLE sensor_data (
  58.                         time TIMESTAMPTZ NOT NULL,
  60.                         sensor_id INTEGER REFERENCES sensors (id),
  62.                         value DOUBLE PRECISION
  64.                     )
  66.                     """);
  68.         }
  70.         try (var stmt = conn.createStatement()) {
  72.             stmt.execute("SELECT create_hypertable('sensor_data', 'time')");
  74.         }
  76.     }
  78.     private static void insertData(final Connection conn) throws SQLException {
  80.         final List<Sensor> sensors = List.of(
  82.                 new Sensor("temperature", "bedroom"),
  84.                 new Sensor("temperature", "living room"),
  86.                 new Sensor("temperature", "outside"),
  88.                 new Sensor("humidity", "kitchen"),
  90.                 new Sensor("humidity", "outside"));
  92.         for (final var sensor : sensors) {
  94.             try (var stmt = conn.prepareStatement("INSERT INTO sensors (type, location) VALUES (?, ?)")) {
  96.                 stmt.setString(1, sensor.type());
  98.                 stmt.setString(2, sensor.location());
  100.                 stmt.executeUpdate();
  102.             }
  104.         }
  106.         final var sensorDataCount = 100;
  108.         final var insertBatchSize = 10;
  110.         try (var stmt = conn.prepareStatement("""
  112.                 INSERT INTO sensor_data (time, sensor_id, value)
  114.                 VALUES (
  116.                     generate_series(now() - INTERVAL '24 hours', now(), INTERVAL '5 minutes'),
  118.                     floor(random() * 4 + 1)::INTEGER,
  120.                     random()
  122.                 )
  124.                 """)) {
  126.             for (int i = 0; i < sensorDataCount; i++) {
  128.                 stmt.addBatch();
  130.                 if ((i > 0 && i % insertBatchSize == 0) || i == sensorDataCount - 1) {
  132.                     stmt.executeBatch();
  134.                 }
  136.             }
  138.         }
  140.     }
  142.     private record Sensor(String type, String location) {
  144.     }
  146. }
tip

If you are inserting data from a CSV file, we recommend the timescale-parallel-copy tool, which is a command line program for parallelizing PostgreSQL’s built-in COPY functionality for bulk inserting data into TimescaleDB.

Congratulations, you’ve successfully inserted data into TimescaleDB using Java.

Execute queries on TimescaleDB

Step 1: Define the SQL query

First, define the SQL query you’d like to run on the database. The example below contains a query which combines time-series and relational data. It returns the average values for every 15 minute interval for sensors with specific type and location.

  2. SELECT time_bucket('15 minutes', time) AS bucket, avg(value)
  4. FROM sensor_data
  6. JOIN sensors ON sensors.id = sensor_data.sensor_id
  8. WHERE sensors.type = ? AND sensors.location = ?
  10. GROUP BY bucket
  12. ORDER BY bucket DESC;

Notice the use of placeholders for sensor type and location.

Step 2: Execute the query

Now you can execute the query with the prepared statement and read out the result set for all a-type sensors located on the floor:

  2. try (var stmt = conn.prepareStatement("""
  4.         SELECT time_bucket('15 minutes', time) AS bucket, avg(value)
  6.         FROM sensor_data
  8.         JOIN sensors ON sensors.id = sensor_data.sensor_id
  10.         WHERE sensors.type = ? AND sensors.location = ?
  12.         GROUP BY bucket
  14.         ORDER BY bucket DESC
  16.         """)) {
  18.     stmt.setString(1, "temperature");
  20.     stmt.setString(2, "living room");
  22.     try (var rs = stmt.executeQuery()) {
  24.         while (rs.next()) {
  26.             System.out.printf("%s: %f%n", rs.getTimestamp(1), rs.getDouble(2));
  28.         }
  30.     }
  32. }

After executing the statement, you should see something like this in the console:

  2. 2021-05-12 23:30:00.0: 0,508649
  4. 2021-05-12 23:15:00.0: 0,477852
  6. 2021-05-12 23:00:00.0: 0,462298
  8. 2021-05-12 22:45:00.0: 0,457006
  10. 2021-05-12 22:30:00.0: 0,568744
  12. ...

Complete Java snippet for working with TimescaleDB

  2. package com.timescale.java;
  4. import java.sql.Connection;
  6. import java.sql.DriverManager;
  8. import java.sql.SQLException;
  10. import java.util.List;
  12. public class Main {
  14.     public static void main(String... args) {
  16.         final var connUrl = "jdbc:postgresql://<HOSTNAME>:<PORT>/<DATABASE_NAME>?user=<USERNAME>&password=<PASSWORD>";
  18.         try (var conn = DriverManager.getConnection(connUrl)) {
  20.             createSchema(conn);
  22.             insertData(conn);
  24.             executeQueries(conn);
  26.         } catch (SQLException ex) {
  28.             System.err.println(ex.getMessage());
  30.         }
  32.     }
  34.     private static void createSchema(final Connection conn) throws SQLException {
  36.         try (var stmt = conn.createStatement()) {
  38.             stmt.execute("""
  40.                     CREATE TABLE sensors (
  42.                         id SERIAL PRIMARY KEY,
  44.                         type TEXT NOT NULL,
  46.                         location TEXT NOT NULL
  48.                     )
  50.                     """);
  52.         }
  54.         try (var stmt = conn.createStatement()) {
  56.             stmt.execute("""
  58.                     CREATE TABLE sensor_data (
  60.                         time TIMESTAMPTZ NOT NULL,
  62.                         sensor_id INTEGER REFERENCES sensors (id),
  64.                         value DOUBLE PRECISION
  66.                     )
  68.                     """);
  70.         }
  72.         try (var stmt = conn.createStatement()) {
  74.             stmt.execute("SELECT create_hypertable('sensor_data', 'time')");
  76.         }
  78.     }
  80.     private static void insertData(final Connection conn) throws SQLException {
  82.         final List<Sensor> sensors = List.of(
  84.                 new Sensor("temperature", "bedroom"),
  86.                 new Sensor("temperature", "living room"),
  88.                 new Sensor("temperature", "outside"),
  90.                 new Sensor("humidity", "kitchen"),
  92.                 new Sensor("humidity", "outside"));
  94.         for (final var sensor : sensors) {
  96.             try (var stmt = conn.prepareStatement("INSERT INTO sensors (type, location) VALUES (?, ?)")) {
  98.                 stmt.setString(1, sensor.type());
  100.                 stmt.setString(2, sensor.location());
  102.                 stmt.executeUpdate();
  104.             }
  106.         }
  108.         final var sensorDataCount = 100;
  110.         final var insertBatchSize = 10;
  112.         try (var stmt = conn.prepareStatement("""
  114.                 INSERT INTO sensor_data (time, sensor_id, value)
  116.                 VALUES (
  118.                     generate_series(now() - INTERVAL '24 hours', now(), INTERVAL '5 minutes'),
  120.                     floor(random() * 4 + 1)::INTEGER,
  122.                     random()
  124.                 )
  126.                 """)) {
  128.             for (int i = 0; i < sensorDataCount; i++) {
  130.                 stmt.addBatch();
  132.                 if ((i > 0 && i % insertBatchSize == 0) || i == sensorDataCount - 1) {
  134.                     stmt.executeBatch();
  136.                 }
  138.             }
  140.         }
  142.     }
  144.     private static void executeQueries(final Connection conn) throws SQLException {
  146.         try (var stmt = conn.prepareStatement("""
  148.                 SELECT time_bucket('15 minutes', time) AS bucket, avg(value)
  150.                 FROM sensor_data
  152.                 JOIN sensors ON sensors.id = sensor_data.sensor_id
  154.                 WHERE sensors.type = ? AND sensors.location = ?
  156.                 GROUP BY bucket
  158.                 ORDER BY bucket DESC
  160.                 """)) {
  162.             stmt.setString(1, "temperature");
  164.             stmt.setString(2, "living room");
  166.             try (var rs = stmt.executeQuery()) {
  168.                 while (rs.next()) {
  170.                     System.out.printf("%s: %f%n", rs.getTimestamp(1), rs.getDouble(2));
  172.                 }
  174.             }
  176.         }
  178.     }
  180.     private record Sensor(String type, String location) {
  182.     }
  184. }

Congratulations 🎉, you’ve successfully executed a query on TimescaleDB using Java and PostgreSQL JDBC!

Next steps

Now that you’re able to connect, read, and write to a TimescaleDB instance from your Java application, be sure to check out these advanced tutorials: