Flight SQL 驱动程序¶

适用于： C/C++、GLib/Ruby、Go、Java、Python、R

Flight SQL 驱动程序提供对任何实现 Arrow Flight SQL 兼容端点的数据库的访问。

安装¶

C/C++

对于 conda-forge 用户

mamba install libadbc-driver-flightsql

go get github.com/apache/arrow-adbc/go/adbc

Java

添加对 org.apache.arrow.adbc:adbc-driver-flight-sql 的依赖。

对于 Maven 用户

<dependency>
  <groupId>org.apache.arrow.adbc</groupId>
  <artifactId>adbc-driver-flight-sql</artifactId>
</dependency>

Python

# For conda-forge
mamba install adbc-driver-flightsql

# For pip
pip install adbc_driver_flightsql

# install.packages("pak")
pak::pak("apache/arrow-adbc/r/adbcflightsql")

使用¶

要连接到数据库，在构造 AdbcDatabase 时提供 “uri” 参数。

C++

#include "arrow-adbc/adbc.h"

// Ignoring error handling
struct AdbcDatabase database;
AdbcDatabaseNew(&database, nullptr);
AdbcDatabaseSetOption(&database, "driver", "adbc_driver_flightsql", nullptr);
AdbcDatabaseSetOption(&database, "uri", "grpc://127.0.0.1:8080", nullptr);
AdbcDatabaseInit(&database, nullptr);

Python

注意

有关详细示例，请参阅 Flight SQL 食谱。

from adbc_driver_flightsql import DatabaseOptions
from adbc_driver_flightsql.dbapi import connect

headers = {"foo": "bar"}

with connect(
    "grpc+tls://127.0.0.1:8080",
    db_kwargs={
        DatabaseOptions.AUTHORIZATION_HEADER.value: "Bearer <token>",
        DatabaseOptions.TLS_SKIP_VERIFY.value: "true",
        **{
            f"{DatabaseOptions.RPC_CALL_HEADER_PREFIX.value}{k}": v
            for k, v in headers.items()
        },
    }
) as conn:
    pass

import (
   "context"

   "github.com/apache/arrow-adbc/go/adbc"
   "github.com/apache/arrow-adbc/go/adbc/driver/flightsql"
)

var headers = map[string]string{"foo": "bar"}

func main() {
   options := map[string]string{
       adbc.OptionKeyURI: "grpc+tls://127.0.0.1:8080",
       flightsql.OptionSSLSkipVerify: adbc.OptionValueEnabled,
   }

   for k, v := range headers {
       options[flightsql.OptionRPCCallHeaderPrefix + k] = v
   }

   var drv flightsql.Driver
   db, err := drv.NewDatabase(options)
   if err != nil {
       // do something with the error
   }
   defer db.Close()

   cnxn, err := db.Open(context.Background())
   if err != nil {
       // handle the error
   }
   defer cnxn.Close()
}

支持的功能¶

Flight SQL 驱动程序通常支持 ADBC API 规范 1.0.0 中定义的功能，以及一些额外的自定义选项。

警告

Java 驱动程序不支持此处的所有选项。请参阅问题 #745。

身份验证¶

驱动程序默认情况下不执行身份验证。驱动程序实现了一些可选的身份验证方案

双向 TLS (mTLS)：请参阅下面的 “客户端选项”。
模拟 Arrow Flight SQL JDBC 驱动程序的 HTTP 样式方案。

在 AdbcDatabase 上设置选项 username 和 password。或者，设置选项 adbc.flight.sql.authorization_header 以获得完全控制。

客户端通过从客户端到服务器发送 authorization 提供凭据。然后服务器在第一个请求上以 authorization 标头进行响应。此标头的值将在所有后续请求上作为 authorization 标头发送回。

批量导入¶

Flight SQL 没有专门用于将 Arrow 数据批量导入到给定表的 API。因此，驱动程序目前没有实现批量导入。

客户端选项¶

用于创建 Flight RPC 客户端的选项可以自定义。

注意

这些选项中的大多数只是包装了 gRPC 选项。有关这些选项功能的更多详细信息，请参阅 gRPC 文档。

adbc.flight.sql.client_option.authority

覆盖 gRPC 的 :authority 伪标头。

Python: adbc_driver_flightsql.DatabaseOptions.AUTHORITY

adbc.flight.sql.client_option.mtls_cert_chain

用于 mTLS 的证书链。

Python: adbc_driver_flightsql.DatabaseOptions.MTLS_CERT_CHAIN

adbc.flight.sql.client_option.mtls_private_key

用于 mTLS 的私钥。

Python: adbc_driver_flightsql.DatabaseOptions.MTLS_PRIVATE_KEY

adbc.flight.sql.client_option.tls_override_hostname

覆盖用于验证服务器 TLS 证书的主机名。

Python: adbc_driver_flightsql.DatabaseOptions.TLS_OVERRIDE_HOSTNAME

adbc.flight.sql.client_option.tls_root_certs

覆盖用于验证服务器 TLS 证书的根证书。

Python: adbc_driver_flightsql.DatabaseOptions.TLS_ROOT_CERTS

adbc.flight.sql.client_option.tls_skip_verify

禁用服务器 TLS 证书的验证。值应为 true 或 false。

Python: adbc_driver_flightsql.DatabaseOptions.TLS_SKIP_VERIFY

adbc.flight.sql.client_option.with_block

警告

此选项已弃用，因为 gRPC 本身已弃用底层选项。

此选项没有效果，将在未来版本中删除。值应为 true 或 false。

adbc.flight.sql.client_option.with_max_msg_size

从服务器接受的最大消息大小。由于 Flight 服务倾向于返回更大的响应有效负载，因此驱动程序默认为 16 MiB。应为正整数字节数。

Python: adbc_driver_flightsql.DatabaseOptions.WITH_MAX_MSG_SIZE

adbc.flight.sql.authorization_header

直接指定要在所有请求上发送的 authorization 标头的值。

Python: adbc_driver_flightsql.DatabaseOptions.AUTHORIZATION_HEADER

adbc.flight.sql.rpc.with_cookie_middleware

启用或禁用处理和处理从服务器返回的 “set-cookie” 元数据标头并从客户端发送回 “Cookie” 标头的中间件。值应为 true 或 false。默认值为 false。

Python: adbc_driver_flightsql.DatabaseOptions.WITH_COOKIE_MIDDLEWARE

自定义调用标头¶

自定义 HTTP 标头可以通过适用于 AdbcDatabase、AdbcConnection 和 AdbcStatement 的选项附加到请求。

adbc.flight.sql.rpc.call_header.<HEADER NAME>: 使用给定值将标头 <HEADER NAME> 添加到传出请求。

Python: adbc_driver_flightsql.ConnectionOptions.RPC_CALL_HEADER_PREFIX

警告

标头名称必须为全小写。

分布式结果集¶

驱动程序将获取服务器返回的所有分区（FlightEndpoints），顺序不确定（请注意，Flight SQL 本身没有定义这些分区的排序）。如果端点没有位置，则将使用原始服务器连接获取数据。否则，驱动程序将按顺序尝试给定的每个位置，直到请求成功为止。如果连接或请求失败，它将尝试下一个位置。

驱动程序目前不缓存或池化这些辅助连接。它也不重试连接或请求。

所有分区都并行获取。每个分区都排队有限数量的批次。数据按分区的顺序返回给客户端。

可以在 AdbcStatement 上配置一些行为

adbc.rpc.result_queue_size

每个分区要排队的批次数。默认值为 5。

Python: adbc_driver_flightsql.StatementOptions.QUEUE_SIZE

增量执行¶

通过设置 ADBC_STATEMENT_OPTION_INCREMENTAL，您可以使用此驱动程序的非阻塞执行。这只会更改 AdbcStatementExecutePartitions() 的行为。启用后，ExecutePartitions 每次都会在服务器上有新分区（用 Flight SQL 术语来说，当有新的 FlightEndpoints 时）返回，而不是阻塞，直到查询完成为止。

可以在 AdbcStatement 上配置一些行为

adbc.flight.sql.statement.exec.last_flight_info

获取服务返回的最新 FlightInfo 的序列化字节。这是一个用于高级使用的低级选项。它在启用增量执行时最有用，用于在不等待 AdbcStatementExecutePartitions() 返回的情况下检查最新服务器响应。

Python: adbc_driver_flightsql.StatementOptions.LAST_FLIGHT_INFO

元数据¶

驱动程序目前不会在 AdbcConnectionGetObjects() 中填充列约束信息（外键、主键等）。此外，目录过滤器将被评估为简单的字符串匹配，而不是 LIKE 样式模式。

分区结果集¶

Flight SQL 驱动程序支持 ADBC 的分区结果集。当请求时，结果集的每个分区都包含一个序列化 FlightInfo，其中包含原始响应的 FlightEndpoints 之一。希望检查分区的客户端可以通过从 ADBC 分区反序列化包含的 FlightInfo 来做到这一点。（例如，希望将工作分布在多个工作器或机器上的客户端可能希望利用 ADBC 没有的位置信息。）