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.