Skip to content

flight_sql_jdbc_driver.rst

Latest commit

 

History

History
298 lines (231 loc) · 8.64 KB

flight_sql_jdbc_driver.rst

File metadata and controls

298 lines (231 loc) · 8.64 KB

Arrow Flight SQL JDBC Driver

The Flight SQL JDBC driver is a JDBC driver implementation that uses the :external+arrow:doc:`Flight SQL protocol <format/FlightSql>` under the hood. This driver can be used with any database that implements Flight SQL.

Installation and Requirements

The driver is compatible with JDK 17+. 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>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&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.

OAuth 2.0 Authentication

The driver supports OAuth 2.0 authentication for obtaining access tokens from an authorization server. Two OAuth flows are currently supported:

  • Client Credentials - For service-to-service authentication where no user interaction is required. The application authenticates using its own credentials (client ID and client secret).
  • Token Exchange (RFC 8693) - For exchanging one token for another, commonly used for federated authentication, delegation, or impersonation scenarios.

OAuth Connection Properties

The following properties configure OAuth authentication. These properties should be provided via the Properties object when connecting, as they may contain special characters that are difficult to encode in a URI.

Common OAuth Properties

Parameter Type Required Default Description
oauth.flow String Yes (to enable OAuth) null The OAuth grant type. Supported values: client_credentials, token_exchange
oauth.tokenUri String Yes null The OAuth 2.0 token endpoint URL (e.g., https://auth.example.com/oauth/token)
oauth.clientId String Conditional null The OAuth 2.0 client ID. Required for client_credentials flow, optional for token_exchange
oauth.clientSecret String Conditional null The OAuth 2.0 client secret. Required for client_credentials flow, optional for token_exchange
oauth.scope String No null Space-separated list of OAuth scopes to request
oauth.resource String No null The resource indicator for the token request (RFC 8707)

Token Exchange Properties

These properties are specific to the token_exchange flow:

Parameter Type Required Default Description
oauth.exchange.subjectToken String Yes null The subject token to exchange (e.g., a JWT from an identity provider)
oauth.exchange.subjectTokenType String Yes null The token type URI of the subject token. Common values: urn:ietf:params:oauth:token-type:access_token, urn:ietf:params:oauth:token-type:jwt
oauth.exchange.actorToken String No null The actor token for delegation/impersonation scenarios
oauth.exchange.actorTokenType String No null The token type URI of the actor token
oauth.exchange.aud String No null The target audience for the exchanged token
oauth.exchange.requestedTokenType String No null The desired token type for the exchanged token