Arrow Flight SQL JDBC 驱动程序

Flight SQL JDBC 驱动程序是一种 JDBC 驱动程序实现，其底层使用了 Flight SQL 协议。此驱动程序可与任何实现 Flight SQL 的数据库配合使用。

安装与要求

该驱动程序兼容 JDK 11+。请注意，需要以下 JVM 参数

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

若要通过 Maven 添加依赖项，请使用如下所示的 pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="https://w3org.cn/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>

连接到数据库

URI 格式如下

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

例如，采用此 URI

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

这将连接到运行在 localhost 端口 12345 上的 Flight SQL 服务。它将创建一个安全的加密连接，并使用用户名 admin 和密码 pass 进行身份验证。

URI 的组成部分如下。

  • URI 方案必须为 jdbc:arrow-flight-sql://。

  • HOSTNAME 是 Flight SQL 服务的主机名。

  • PORT 是 Flight SQL 服务的端口。

附加选项可以通过查询参数传递。参数名称区分大小写。支持的参数有

参数

默认

描述

disableCertificateVerification

false

启用 TLS 时，是否验证服务器证书

password

空 (null)

用于用户/密码身份验证的密码

threadPoolSize

1

内部线程池的大小

token

空 (null)

用于令牌身份验证的令牌

trustStore

空 (null)

启用 TLS 时，证书存储的路径

trustStorePassword

空 (null)

启用 TLS 时，证书存储的密码

tlsRootCerts

空 (null)

TLS 的 PEM 编码根证书路径 - 使用此项可作为 trustStore 的替代方案

clientCertificate

空 (null)

当 Flight SQL 服务器需要客户端验证时，PEM 编码的客户端 mTLS 证书路径。

clientKey

空 (null)

当 Flight SQL 服务器需要客户端验证时，PEM 编码的客户端 mTLS 密钥路径。

useEncryption

true

是否使用 TLS（默认值为加密连接）

user

空 (null)

用于用户/密码身份验证的用户名

useSystemTrustStore

true

启用 TLS 时，是否使用系统证书存储

retainCookies

true

在从不同端点检索数据流时，后续内部连接是否使用初始连接的 Cookie。

retainAuth

true

在从不同端点检索数据流时，后续内部连接是否使用从初始连接获取的持票人令牌 (Bearer Tokens)。

请注意，如果 URI 值包含 !, @, $ 等字符，则必须进行 URI 编码。

驱动程序未处理的任何 URI 参数都将作为 gRPC 头传递给 Flight SQL 服务。例如，以下 URI

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

这将以不经过身份验证或加密的方式，连接到运行在 localhost 端口 12345 上的 Flight SQL 服务。每个请求还将包含一个 database=mydb 的 gRPC 头。

使用 JDBC Driver Manager 连接时，也可以通过 Properties 对象提供连接参数。使用 Properties 对象提供时，值不应进行 URI 编码。

URI 指定的参数优先于 Properties 对象提供的参数。在调用 DriverManager#getConnection() 的用户/密码重载方法时，URI 上提供的用户名和密码优先于函数调用中的用户名和密码参数。

OAuth 2.0 身份验证

该驱动程序支持 OAuth 2.0 身份验证，用于从授权服务器获取访问令牌。目前支持两种 OAuth 流程

  • 客户端凭据 (Client Credentials) - 用于不需要用户交互的服务对服务身份验证。应用程序使用其自身的凭据（客户端 ID 和客户端密钥）进行身份验证。

  • 令牌交换 (Token Exchange) (RFC 8693) - 用于将一个令牌交换为另一个令牌，通常用于联合身份验证、委派或模拟场景。

OAuth 连接属性

以下属性用于配置 OAuth 身份验证。这些属性应在连接时通过 Properties 对象提供，因为它们可能包含难以在 URI 中编码的特殊字符。

常用 OAuth 属性

参数

类型

必需

默认

描述

oauth.flow

String

是（启用 OAuth 时）

空 (null)

OAuth 授权类型。支持的值：client_credentials, token_exchange

oauth.tokenUri

String

是

空 (null)

OAuth 2.0 令牌端点 URL（例如 https://auth.example.com/oauth/token）

oauth.clientId

String

条件性

空 (null)

OAuth 2.0 客户端 ID。client_credentials 流程必需，token_exchange 流程可选

oauth.clientSecret

String

条件性

空 (null)

OAuth 2.0 客户端密钥。client_credentials 流程必需，token_exchange 流程可选

oauth.scope

String

否

空 (null)

以空格分隔的要请求的 OAuth 作用域列表

oauth.resource

String

否

空 (null)

令牌请求的资源指示符 (RFC 8707)

令牌交换属性

这些属性特定于 token_exchange 流程

参数

类型

必需

默认

描述

oauth.exchange.subjectToken

String

是

空 (null)

要交换的主体令牌（例如，来自身份提供者的 JWT）

oauth.exchange.subjectTokenType

String

是

空 (null)

主体令牌的令牌类型 URI。常见值：urn:ietf:params:oauth:token-type:access_token, urn:ietf:params:oauth:token-type:jwt

oauth.exchange.actorToken

String

否

空 (null)

用于委派/模拟场景的参与者令牌

oauth.exchange.actorTokenType

String

否

空 (null)

参与者令牌的令牌类型 URI

oauth.exchange.aud

String

否

空 (null)

交换后令牌的目标受众

oauth.exchange.requestedTokenType

String

否

空 (null)

交换后令牌的所需令牌类型