> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firebolt.io/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.firebolt.io/feedback
```json
{
"path": "/guides/developing-with-firebolt/connecting-with-jdbc",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
> How to use the Firebolt JDBC driver
# JDBC
Firebolt's [type 4](https://en.wikipedia.org/wiki/JDBC_driver#Type_4_driver_%E2%80%93_Database-Protocol_driver/Thin_Driver\(Pure_Java_driver\)) 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](https://github.com/firebolt-db/jdbc).
## Download the JAR file
The Firebolt JDBC driver is provided as a JAR file and requires [Java 11](https://java.com/en/download/manual.jsp) or later.
Download the driver from [GitHub JDBC releases](https://github.com/firebolt-db/jdbc/releases).
## Adding the Firebolt JDBC driver as a Maven dependency
To connect your project to Firebolt using [Apache Maven](https://maven.apache.org/), add the Firebolt JDBC driver as a dependency in your **pom.xml** configuration file. Link to the [Firebolt Maven repository](https://central.sonatype.com/artifact/io.firebolt/firebolt-jdbc), so that Maven can download and include the JDBC driver in your project, as shown in the following code example:
```xml theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://central.sonatype.com/artifact/io.firebolt/firebolt-jdbc).
## Adding the Firebolt JDBC driver as a Gradle dependency
If you are using the [Gradle Build Tool](https://gradle.org/), you can configure your Gradle project to use the Firebolt JDBC driver by specifying Apache's [Maven Central](https://maven.apache.org/repository/index.html) as a repository and adding the Firebolt JDBC driver as a dependency as follows:
```gradle theme={"theme":{"light":"github-light","dark":"github-dark"}}
/* 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](https://central.sonatype.com/artifact/io.firebolt/firebolt-jdbc).
## 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:?
```
In the previous connection example, the following apply:
* `` - Specifies the name of the Firebolt database to connect to.
* `` - A list of connection parameters formatted as a standard [URL query string](https://en.wikipedia.org/wiki/Query_string#Structure).
## Authentication
To authenticate, use a [service account ID and secret](/guides/managing-your-organization/service-accounts).
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_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_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_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_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](https://en.wikipedia.org/wiki/Percent-encoding) 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 key | Data type | Default value | Range | Description |
| -------------------------------------- | --------- | ------------------------------------------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id` | TEXT | No default value. | | (**Required**) The Firebolt service account ID. |
| `client_secret` | TEXT | No default value. | | (**Required**) The secret generated for the Firebolt service account. |
| `account` | TEXT | No default value. | | (**Required**) Your Firebolt account name. |
| `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 | The default engine attached to the specified database. | | The name of the engine to connect to. |
| `buffer_size` | INTEGER | `65536` | `1` to `2147483647` | The buffer size, in bytes, that the driver uses to read the responses from the Firebolt API. |
| `connection_timeout_millis` | INTEGER | `60000` | `0` to `2147483647` | The 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_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, 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_millis` | INTEGER | `300000` | `1` to `2147483647` | Defines the duration to keep a server connection open in the connection pool before it is closed. |
| `ssl_mode` | TEXT | `strict` | `strict` or `none` | When set to `strict`, the SSL or TLS certificate is validated for accuracy and authenticity. If set to `none`, certificate verification is omitted. |
| `ssl_certificate_path` | TEXT | No default value. | | The absolute file path for the SSL root certificate. |
| `validate_on_system_engine` | BOOLEAN | `FALSE` | `TRUE` or `FALSE` | When 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](#connection-validation). |
| `cache_connection` | BOOLEAN | `TRUE` | `TRUE` or `FALSE` | Keep 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](/reference-sql/system-settings) 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&
```
## Applying system settings using SET
In addition to passing system settings as connection string parameters, any [system setting](/reference-sql/system-settings) can be passed using the SQL `SET` command. Multiple `SET` statements can be run consecutively, separated by semicolons, as shown below:
```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
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&
```
## Full reference documentation
The complete documentation for classes and methods in the Firebolt JDBC driver is available in the [Firebolt JDBC API reference guide](https://jdbc.docs.firebolt.io/javadoc/).