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 驅動程式不支援此處的所有選項。請參閱 issue #745。

身份驗證¶

驅動程式預設不執行任何身份驗證。驅動程式實作了一些可選的身份驗證方案

相互 TLS (mTLS)：請參閱下方的「用戶端選項」。
一種模仿 Arrow Flight SQL JDBC 驅動程式的 HTTP 風格方案。

在 AdbcDatabase 上設定選項 username 和 password。或者，設定選項 adbc.flight.sql.authorization_header 以取得完整控制權。

用戶端透過從用戶端向伺服器傳送 authorization 來提供憑證。然後，伺服器在第一個請求上以 authorization 標頭回應。此標頭的值將在所有未來請求上作為 authorization 標頭傳回。

大量資料擷取¶

Flight SQL 沒有專用的 API 用於將 Arrow 資料大量擷取到給定的表格中。因此，驅動程式目前未實作大量資料擷取。

用戶端選項¶

用於建立 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

從伺服器接受的最大訊息大小。驅動程式預設為 16 MiB，因為 Flight 服務傾向於傳回較大的回應酬載。應為正整數位元組數。

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” metadata 標頭，並從用戶端傳回 “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

警告

標頭名稱必須全部小寫。

分散式結果集¶

驅動程式將以未指定的順序 (請注意，Flight SQL 本身未定義這些分割區的順序) 擷取伺服器傳回的所有分割區 (FlightEndpoints)。如果端點沒有位置，則將使用原始伺服器連線擷取資料。否則，驅動程式將依序嘗試每個給定的位置，直到請求成功。如果連線或請求失敗，它將嘗試下一個位置。

驅動程式目前不會快取或集區這些次要連線。它也不會重試連線或請求。

所有分割區都平行擷取。每個分割區排隊有限數量的批次。資料以分割區的順序傳回給用戶端。

某些行為可以在 AdbcStatement 上設定

adbc.rpc.result_queue_size

每個分割區要排隊的批次數。預設值為 5。

Python: adbc_driver_flightsql.StatementOptions.QUEUE_SIZE

增量執行¶

透過設定 ADBC_STATEMENT_OPTION_INCREMENTAL，您可以使用此驅動程式進行非阻塞執行。這僅更改 AdbcStatementExecutePartitions() 的行為。啟用後，每次伺服器有新的分割區 (以 Flight SQL 術語來說，當有新的 FlightEndpoints 時)，ExecutePartitions 都會傳回，而不是阻塞直到查詢完成。

某些行為可以在 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 沒有的位置資訊。）