JDBC driver

Firebolt provides a type 4 JDBC driver to connect to Firebolt from Java applications. The driver is released as open source software using a permissive Apache 2 license and can be browsed, forked, downloaded, and contributed to through its GitHub repository.

• Download the JAR file
• Adding the Firebolt JDBC driver as a Maven dependency
• Adding the Firebolt JDBC driver as a gradle dependency
• Connecting to Firebolt with the JDBC driver
• Authentication
  • Available connection parameters
  • System settings as connection parameters
• Applying system settings using SET
• Full reference documentation

Download the JAR file

The Firebolt JDBC driver is provided as a JAR file and requires Java 11 or later.

Download the Firebolt JDBC driver JAR file from the GitHub Releases page.

Adding the Firebolt JDBC driver as a Maven dependency

If you are using Apache Maven, you can configure and build your projects to use the Firebolt JDBC driver to connect to your Firebolt resources. To do this, add the JDBC driver as a dependency in your project pom.xml file by including a link to the Firebolt Maven repository.

See below for an example pom.xml file:

Be sure to replace <version>3.1.0</version> with the latest (highest) version number. You can identify the latest version by viewing the version history in the Firebolt Maven Central repository.

<!-- pom.xml  -->

<project ...>
       <dependency>
            	<groupId>io.firebolt</groupId>
            	<artifactId>firebolt-jdbc</artifactId>
            	<version>3.1.0</version>
       </dependency>
</project>

Adding the Firebolt JDBC driver as a gradle dependency

Be sure to replace <version>0.00</version> with the latest (highest) version number. You can identify the latest version by viewing the version history in the Firebolt Maven Central repository.

/* build.gradle */

repositories {
    mavenCentral()
}

dependencies {
    implementation 'io.firebolt:firebolt-jdbc:3.0.1'
}

Connecting to Firebolt with the JDBC driver

Connection details are provided to the Firebolt JDBC driver in a connection string. The string has the following format:

jdbc:firebolt:<database>?<connection_params>

<database>
The name of the Firebolt database to connect to.

<connection_params>
A list of connection parameters following the standard URL query string format.

Authentication

To authenticate, use a service account ID and secret. A service account is identified by a client_id and a client_secret. For compatibility with various external tools, client_id can be sent as user and client_secret as password.
Learn how to generate an ID and secret here.

Here is an example of a connection details:

• URL that uses client_id/secret_id

    jdbc:firebolt:my_database?client_id=<client_id>&client_secret=<client_secret>&account=my_account&engine=my_database_general_purpose&buffer_size=1000000&connection_timeout_millis=10000
  

• URL that uses that omits authentication details that are passed in properties

  jdbc:firebolt:my_database?account=my_account&engine=my_database_general_purpose&buffer_size=1000000&connection_timeout_millis=10000`
  

  Connection properties:

  client_id=<client_id>
  client_secret=<client_secret>
  

• Minimal URL that sends all additional parameters in connection properties

  jdbc:firebolt:my_database
  

  Connection properties:

  client_id=<client_id>
  client_secret=<client_secret>
  account=my_account
  engine=my_database_general_purpose
  buffer_size=1000000
  connection_timeout_millis=10000
  

• Minimal URL that sends user and password (client_id and client_secret) using connection properties, omits engine name and therefore connects to default engine and relies on default values of other parameters

  jdbc:firebolt:my_database
  

  Connection properties:

  client_id=<client_id>
  client_secret=<client_secret>
  account=my_account
  

  Since the connection string is a URI, make sure to percent-encode any reserved characters or special characters used in parameter keys or parameter values.

Available connection parameters

The table below lists the available connection parameters that can be added to the Firebolt JDBC connection string. All parameter keys are case-sensitive.

Parameter key	Data type	Default value	Range	Description
client_id	TEXT	No default value		The Firebolt service account ID. Required.
client_secret	TEXT	No default value		The secret generated for the Firebolt service account. Required.
account	TEXT	No default value		Your Firebolt account name. Required.
database	TEXT	No default value		The name of the database to connect to. Takes precedence over the database name provided as a path parameter.
engine	TEXT	Default engine attached to chosen database		The name of the engine to connect to.
buffer_size	INTEGER	65536	1 to 2147483647	The buffer used by the driver to read the response from the Firebolt API, in bytes.
connection_timeout_millis	INTEGER	60000	0 to 2147483647	The amount of time in milliseconds to wait to establish a connection with the server before the connection is considered failed. A timeout value of zero is interpreted as an infinite timeout.
max_connections_total	INTEGER	300	1 to 2147483647	The maximum total number of connections.
socket_timeout_millis	INTEGER	0	0 to 2147483647	The socket timeout in milliseconds. This is the timeout for waiting for data – the maximum period of inactivity between two consecutive data packets. A timeout value of zero is interpreted as an infinite timeout.
connection_keep_alive_timeout_millis	INTEGER	300000	1 to 2147483647	Specifies how long to keep a connection with the server alive in the connection pool before closing it.
ssl	BOOLEAN	true	true or false	When set to true, connections use SSL / TLS certificates. This parameter also determines the port used by the driver. If true, it uses port 443. If false, it uses port 80.
ssl_mode	TEXT	strict	strict or none	When set to strict, the certificate is validated to ensure it is correct. If set to none, no certificate verification is used.
ssl_certificate_path	TEXT	No default value		The absolute file path for the SSL root certificate.

System settings as connection parameters

In addition to the parameters specified above, any system setting can be passed as a connection string parameter. For example, if you wanted to set a custom time zone, your connection string would be as follows:

jdbc:firebolt:my_database?time_zone=UTC&<other_connection_params>

Applying system settings using SET

In addition to passing system settings as connection string parameters, any system setting can be passed to Firebolt as a SET command in SQL. Multiple SET statements can be passed at once as long as they immediately follow one after another separated by semicolons, as shown in the following example.

SET time_zone = 'UTC';
SET standard_conforming_strings = false;

Full reference documentation

Complete reference documentation for the classes and methods implemented in the Firebolt JDBC driver can be found here.