Arrow Flight SQL JDBC Driver

The Flight SQL JDBC driver is a JDBC driver implementation that uses the Flight SQL protocol under the hood. This driver can be used with any database that implements Flight SQL.

Installation and Requirements

The driver is compatible with JDK 11+. Note that the following JVM parameter is required:

java --add-opens=java.base/java.nio=ALL-UNNAMED ...

To add a dependency via Maven, use a pom.xml like the following:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.example</groupId>
  <artifactId>demo</artifactId>
  <version>1.0-SNAPSHOT</version>
  <properties>
    <arrow.version>10.0.0</arrow.version>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.apache.arrow</groupId>
      <artifactId>flight-sql-jdbc-driver</artifactId>
      <version>${arrow.version}</version>
    </dependency>
  </dependencies>
</project>

Connecting to a Database

The URI format is as follows:

jdbc:arrow-flight-sql://HOSTNAME:PORT[/?param1=val1&param2=val2&...]

For example, take this URI:

jdbc:arrow-flight-sql://localhost:12345/?username=admin&password=pass&useEncryption=1

This will connect to a Flight SQL service running on localhost on port 12345. It will create a secure, encrypted connection, and authenticate using the username admin and the password pass.

The components of the URI are as follows.

• The URI scheme must be jdbc:arrow-flight-sql://.

• HOSTNAME is the hostname of the Flight SQL service.

• PORT is the port of the Flight SQL service.

Additional options can be passed as query parameters. Parameter names are case-sensitive. The supported parameters are:

Parameter	Default	Description
disableCertificateVerification	false	When TLS is enabled, whether to verify the server certificate
password	null	The password for user/password authentication
threadPoolSize	1	The size of an internal thread pool
token	null	The token used for token authentication
trustStore	null	When TLS is enabled, the path to the certificate store
trustStorePassword	null	When TLS is enabled, the password for the certificate store
tlsRootCerts	null	Path to PEM-encoded root certificates for TLS - use this as an alternative to trustStore
clientCertificate	null	Path to PEM-encoded client mTLS certificate when the Flight SQL server requires client verification.
clientKey	null	Path to PEM-encoded client mTLS key when the Flight SQL server requires client verification.
useEncryption	true	Whether to use TLS (the default is an encrypted connection)
user	null	The username for user/password authentication
useSystemTrustStore	true	When TLS is enabled, whether to use the system certificate store
retainCookies	true	Whether to use cookies from the initial connection in subsequent internal connections when retrieving streams from separate endpoints.
retainAuth	true	Whether to use bearer tokens obtained from the initial connection in subsequent internal connections used for retrieving streams from separate endpoints.

Note that URI values must be URI-encoded if they contain characters such as !, @, $, etc.

Any URI parameters that are not handled by the driver are passed to the Flight SQL service as gRPC headers. For example, the following URI

jdbc:arrow-flight-sql://localhost:12345/?useEncryption=0&database=mydb

This will connect without authentication or encryption, to a Flight SQL service running on localhost on port 12345. Each request will also include a database=mydb gRPC header.

Connection parameters may also be supplied using the Properties object when using the JDBC Driver Manager to connect. When supplying using the Properties object, values should not be URI-encoded.

Parameters specified by the URI supercede parameters supplied by the Properties object. When calling the user/password overload of DriverManager#getConnection(), the username and password supplied on the URI supercede the username and password arguments to the function call.