Arrow Flight SQL JDBC Driver#
The Flight SQL JDBC driver is a JDBC driver implementation that usestheFlight 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 JVMparameter is required:
java--add-opens=java.base/java.nio=ALL-UNNAMED...
To add a dependency via Maven, use apom.xml like the following:
<?xml version="1.0" encoding="UTF-8"?><projectxmlns="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>18.1.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¶m2=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 onlocalhost onport 12345. It will create a secure, encrypted connection, andauthenticate using the usernameadmin and the passwordpass.
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 arecase-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 asan alternative to |
clientCertificate | null | Path to PEM-encoded client mTLS certificate when the FlightSQL server requires client verification. |
clientKey | null | Path to PEM-encoded client mTLS key when the FlightSQL 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 subsequentinternal connections when retrieving streams from separate endpoints. |
retainAuth | true | Whether to use bearer tokens obtained from the initial connectionin subsequent internal connections used for retrieving streamsfrom separate endpoints. |
Note that URI values must be URI-encoded if they contain characters suchas !, @, $, etc.
Any URI parameters that are not handled by the driver are passed tothe 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 FlightSQL service running onlocalhost on port 12345. Each request willalso include adatabase=mydb gRPC header.
Connection parameters may also be supplied using the Properties objectwhen using the JDBC Driver Manager to connect. When supplying usingthe Properties object, values shouldnot be URI-encoded.
Parameters specified by the URI supercede parameters supplied by theProperties object. When calling theuser/password overload ofDriverManager#getConnection(),the username and password supplied on the URI supercede the username andpassword arguments to the function call.