Firebolt’s type 4 JDBC driver lets Java applications connect to Firebolt. The JDBC driver is open-source software released under an Apache 2 license. You can browse, fork, download, and contribute to its development on GitHub.

​
Download the JAR file

The Firebolt JDBC driver is provided as a JAR file and requires Java 11 or later. Download the driver from GitHub JDBC releases.

​
Adding the Firebolt JDBC driver as a Maven dependency

To connect your project to Firebolt using Apache Maven, add the Firebolt JDBC driver as a dependency in your pom.xml configuration file. Link to the Firebolt Maven repository, so that Maven can download and include the JDBC driver in your project, as shown in the following code example: 
<!-- pom.xml  -->
<project ...>
  <dependency>
    <groupId>io.firebolt</groupId>
    <artifactId>firebolt-jdbc</artifactId>
    <version>3.3.0</version>
  </dependency>
</project>
In the previous code example, replace <version>3.3.0</version> with the latest version available in the Firebolt Maven Central repository.

​
Adding the Firebolt JDBC driver as a Gradle dependency

If you are using the Gradle Build Tool, you can configure your Gradle project to use the Firebolt JDBC driver by specifying Apache’s Maven Central as a repository and adding the Firebolt JDBC driver as a dependency as follows: 
/* build.gradle */

repositories {
    mavenCentral()
}

dependencies {
    implementation 'io.firebolt:firebolt-jdbc:3.3.0'
}
In the previous code example, replace 3.3.0 with the latest version available in the Firebolt Maven Central repository.

​
Connecting to Firebolt with the JDBC driver

Provide connection details to the Firebolt JDBC driver using a connection string in the following format: 
jdbc:firebolt:<database>?<connection_params>
In the previous connection example, the following apply:
  • <database> - Specifies the name of the Firebolt database to connect to.
  • <connection_params> - A list of connection parameters formatted as a standard URL query string.

​
Authentication

To authenticate, use a service account ID and secret. A service account, which is used for programmatic access to Firebolt, uses a client_id and a client_secret for identification. To ensure compatibility with tools external to Firebolt, you can specify the service account’s client_id as user and client_secret as password. The following are examples of how to specify connection strings for authentication and configuration: Example The following example connection string configures the Firebolt JDBC driver to connect to my_database using a specified client_id and secret_id for authentication: 
jdbc:firebolt:my_database?client_id=<client_id>&client_secret=<client_secret>&account=my_account&engine=my_engine&buffer_size=1000000&connection_timeout_millis=10000
The previous example string also specifies an account name my_account, an engine name my_engine, a buffer size of 1000000 bytes, and a connection timeout of 10000 milliseconds, or 10 seconds. Example The following example provides client_id and client_secret as separate properties, rather than embedding them directly in the connection string, as shown in the previous example. Connection string: 
jdbc:firebolt:my_database?account=my_account&engine=my_engine&buffer_size=1000000&connection_timeout_millis=10000`
Connection properties: 
client_id=<client_id>
client_secret=<client_secret>
Example The following example connects to my_database using only connection properties for authentication and parameters, without including any parameters directly in the string. Connection string: 
jdbc:firebolt:my_database
Connection properties: 
client_id=<client_id>
client_secret=<client_secret>
account=my_account
engine=my_engine
buffer_size=1000000
connection_timeout_millis=10000
Example The following example is a minimal URL that connects to my_database using client_id and client_secret as connection properties for authentication, omitting the engine name and therefore connects to default engine and relying on default values for all other parameters: Connection string: 
jdbc:firebolt:my_database
Connection properties: 
client_id=<client_id>
client_secret=<client_secret>
account=my_account
Because the previous configuration example omits specifying the engine name, my_database connects to the default engine.
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 following table lists the available parameters that can be added to a Firebolt JDBC connection string. All parameter keys are case-sensitive.
Parameter keyData typeDefault valueRangeDescription
client_idTEXTNo default value.(Required) The Firebolt service account ID.
client_secretTEXTNo default value.(Required) The secret generated for the Firebolt service account.
accountTEXTNo default value.(Required) Your Firebolt account name.
databaseTEXTNo default value.The name of the database to connect to. Takes precedence over the database name provided as a path parameter.
engineTEXTThe default engine attached to the specified database.The name of the engine to connect to.
buffer_sizeINTEGER655361 to 2147483647The buffer size, in bytes, that the driver uses to read the responses from the Firebolt API.
connection_timeout_millisINTEGER600000 to 2147483647The wait time in milliseconds before a connection to the server is considered failed. A timeout value of zero means that the connection will wait indefinitely.
max_connections_totalINTEGER3001 to 2147483647The maximum total number of connections.
socket_timeout_millisINTEGER00 to 2147483647The socket timeout, in milliseconds, which specifies the maximum wait time for data, defining the longest allowed inactivity between consecutive data packets. A value of zero means that there is no timeout limit.
connection_keep_alive_timeout_millisINTEGER3000001 to 2147483647Defines the duration to keep a server connection open in the connection pool before it is closed.
ssl_modeTEXTstrictstrict or noneWhen set to strict, the SSL or TLS certificate is validated for accuracy and authenticity. If set to none, certificate verification is omitted.
ssl_certificate_pathTEXTNo default value.The absolute file path for the SSL root certificate.
validate_on_system_engineBOOLEANFALSETRUE or FALSEWhen set to TRUE, the connection is always validated against a system engine, even if it’s connected to a regular engine. For more information, see Connection validation.
cache_connectionBOOLEANTRUETRUE or FALSEKeep this enabled for better performance when interacting with Firebolt. If you experience connection issues that might be related to stale cache set this to FALSE. Available only with JDBC driver version 3.6.1 and above.

​
System settings as connection parameters

In addition to the parameters specified in the previous table, any system setting can be passed as a connection string parameter. For example, to set a custom time zone, use the following format: 
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 using the SQL SET command. Multiple SET statements can be run consecutively, separated by semicolons, as shown below: 
    SET time_zone = 'UTC';
    SET standard_conforming_strings = false;

​
Connection validation

The Firebolt JDBC driver validates the connection by sending a SELECT 1 query to the system engine. If this query fails, the driver throws an exception. You can use the validate_on_system_engine parameter to customize validation. When it is set to true, the validation query is sent to the system engine, even if the connection is established with a regular engine. This feature can be useful if you want to stop the regular engine but still need to validate the connection. The following example configures the Firebolt JDBC driver to connect to my_database and validate the connection using the system engine with additional connection parameters specified in other_connection_parameters: 
jdbc:firebolt:my_database?validate_on_system_engine=true&<other_connection_params>

​
Full reference documentation

The complete documentation for classes and methods in the Firebolt JDBC driver is available in the Firebolt JDBC API reference guide.