共用方式為

支援的連線屬性

本文說明 Databricks JDBC 驅動程式第 3 版和更新版本所支援的連線屬性。

驗證和代理屬性

Databricks JDBC 驅動程式支援下列驗證和 Proxy 屬性。 屬性不區分大小寫。

財產 預設值 說明
AsyncExecPollInterval 200 每個異步查詢執行狀態輪詢之間的時間，以毫秒為單位。 異步是指用來對 Spark 執行查詢的 RPC 呼叫是異步的。 這並不表示支援 JDBC 異步作業。
Auth_Flow 0 驅動程式連線的 OAuth2 驗證流程。 當 AuthMech 是 11時，這個屬性是必需的。
Auth_JWT_Alg RS256 私鑰 JWT 驗證的演算法。 支持的演算法包括：RSA：RS256、RS384、RS512、PS256、PS384、PS512 和 EC：ES256、ES384、ES512
Auth_JWT_Key_File null JWT 驗證私鑰檔案的路徑（PEM 格式）。
Auth_JWT_Key_Passphrase null 解密加密私鑰的通行碼。
Auth_KID null JWT 驗證所需的金鑰標識碼 （KID）。 使用私鑰 JWT 時，這是必要的。
Auth_RefreshToken null 用於獲取新存取令牌的 OAuth2 重新整理令牌。
Auth_Scope all-apis OAuth2 流程的驗證範圍。
AuthMech 為必填項目 驗證機制，其中 3 指定機制是 Azure Databricks 個人存取令牌，11 指定機制為 OAuth 2.0 令牌。 每個機制都需要其他屬性。 請參閱 驗證驅動程式。
AzureTenantId null Azure 特定身份驗證所用的 Azure 租戶 ID。
CFProxyAuth 0 如果設定為 1，驅動程式會使用 proxy 驗證使用者和密碼，由 CFProxyUID 和 CFProxyPwd表示。
CFProxyHost null 字串，表示當 UseCFProxy 也設定為 1時要使用的 Proxy 主機名稱。
CFProxyPort null 整數，表示當 UseCFProxy 也設定為 1時要使用的 Proxy 埠數目。
CFProxyPwd null 字串，表示當 CFProxyAuth 和 UseCFProxy 也設定為 1時，要用於 Proxy 驗證的密碼。
CFProxyUID null 字串，表示當 CFProxyAuth 和 UseCFProxy 也設定為 1時，要用於 Proxy 驗證的用戶名稱。
ConnCatalog 或 catalog SPARK 要使用的預設目錄名稱。
ConnSchema 或 schema default 要使用的預設架構名稱。 您可以藉由將 URL 中的 <schema> 取代為要使用的架構名稱，或將 ConnSchema 屬性設定為要使用的架構名稱來指定。
EnableOIDCDiscovery 1 如果設定為 1，則會使用 OpenID Connect 探索 URL。
EnableTokenCache 1 如果設為 1，則會啟用 OAuth 權杖的快取，以改善效能。
GoogleCredentialsFile null Google 服務帳戶驗證 JSON 金鑰檔案的路徑。
GoogleServiceAccount null 使用Google服務帳戶啟用驗證。
OAuth2ClientId null 用於驗證的 OAuth2 用戶端 ID。 依預設， databricks-sql-jdbc 用於 AWS、GCP 和 Azure。 進階 OAuth 組態需要自訂用戶端 ID。
OAuth2ConnAuthAuthorizeEndpoint null OAuth2 流程中使用的授權端點 URL。
OAuth2ConnAuthTokenEndpoint null OAuth2 流程的令牌端點網址
OAuth2RedirectUrlPort 8020 瀏覽器型驗證流程的 OAuth2 重定向 URL 端口。
OIDCDiscoveryEndpoint null 用於擷取 OIDC 組態的 OpenID Connect 發現 URL。
ProxyAuth 0 如果設定為 1，驅動程式會使用 proxy 驗證使用者和密碼，由 ProxyUID 和 ProxyPwd表示。
ProxyHost null 字串，表示當 UseProxy 也設定為 1時要使用的 Proxy 主機名稱。
ProxyPort null 整數，表示當 UseProxy 也設定為 1時要使用的 Proxy 埠數目。
ProxyPwd null 字串，表示當 ProxyAuth 和 UseProxy 也設定為 1時，要用於 Proxy 驗證的密碼。
ProxyUID null 字串，表示當 ProxyAuth 和 UseProxy 也設定為 1時，要用於 Proxy 驗證的用戶名稱。
TokenCachePassPhrase null 用於 OAuth U2M 權杖快取加密的通行短語。
UseCFProxy 0 如果設定為 1，則驅動程式會在提供時使用雲端擷取 Proxy 設定，否則請使用一般 Proxy。
UseJWTAssertion false 針對受限制客戶端密碼驗證的 M2M 使用案例啟用私鑰 JWT 驗證。
UseProxy 0 如果設定為 1，驅動程式會使用提供的 Proxy 設定（例如：ProxyAuth、ProxyHost、ProxyPort、ProxyPwd和 ProxyUID）。
UseSystemProxy 0 如果設定為 1，驅動程式會使用已在系統層級設定的 Proxy 設定。 如果在連線 URL 中設定任何其他 Proxy 屬性，這些額外的 Proxy 屬性會覆寫已在系統層級設定的屬性。

SSL 信任存放區組態屬性

Databricks JDBC 驅動程式支援下列 SSL 信任存放區組態屬性。 屬性不區分大小寫。

財產 預設值 說明
AcceptUndeterminedRevocation 0 如果設為 1，則在啟用憑證撤銷檢查時接受具有未決定撤銷狀態的憑證。
AllowSelfSignedCerts 0 如果設定為 1，驅動程式會允許連線到具有自我簽署 SSL 憑證的伺服器。
CheckCertificateRevocation 0 如果設定為 1，驅動程式會檢查 SSL 憑證是否已撤銷。
SSL 1 連接器是否通過啟用 SSL 的套接字與 Spark 伺服器進行通訊。
SSLKeyStore null 用於用戶端憑證鑑別的 SSL 金鑰儲存庫檔案的路徑。 依預設，會執行僅限伺服器的 TLS 鑑別，因此不需要用戶端憑證。
SSLKeyStorePwd null SSL 金鑰存放區檔案的密碼。
SSLKeyStoreType JKS SSL 金鑰存放區的類型。 有效值為 JKS、 PKCS12、 JCEKS和 DKSPKCS11。
SSLTrustStore null SSL 憑證驗證的信任存放區檔案路徑。
SSLTrustStorePassword null 信任存放區檔案的密碼（如果受到密碼保護的話）。
SSLTrustStoreType JKS 信任存放區的類型，例如 JKS 或 PKCS12。 如果未指定，驅動程式會預設為 JKS 信任存放區。 有效的類型為 JKS、 PKCS12與 BCFKS。
UseSystemTrustStore 0 如果設定為 1，驅動程式會使用系統的預設信任存放區進行 SSL 憑證驗證。

信任存放區類型

JDBC 驅動程式支援下列 SSL 模式和信任存放區類型。

自我簽署憑證模式

若要使用自我簽署憑證模式，請設定連線屬性 AllowSelfSignedCerts=1。 此模式會使用接受任何憑證的全信任套接字處理站。

自訂信任存放區

若要使用自定義信任存放區，請在連線屬性中 SSLTrustStore 指定自定義信任存放區檔案。 此信任存放區會直接從指定的路徑載入，並使用憑證進行 SSL 憑證驗證。 它可以是 JKS、PKCS12 或其他支援的格式。

您必須指定下列其他連線屬性：

  • SSLTrustStore：信任存放區檔案的路徑
  • SSLTrustStorePassword：信任存放區的密碼（如有需要）
  • SSLTrustStoreType：信任存放區類型（選擇性，如果未指定，預設為 JKS）

Java 系統屬性信任存放區

若要使用系統屬性信任存放區，請設定 UseSystemTrustStore=1 並確定您未指定自定義信任存放區。 請改用 Java 系統屬性 javax.net.ssl.trustStore來指定信任存放區。 此屬性是使用 -D 旗標在 JVM 層級設定，例如：

java -Djavax.net.ssl.trustStore=/path/to/truststore.jks -Djavax.net.ssl.trustStorePassword=changeit ...

JDBC 驅動程式會先檢查 Java 系統屬性 javax.net.ssl.trustStore。 如果已設定，它會使用此信任存放區檔案，而不是 JDK 的預設值。 如果未設定任何系統屬性，請使用 JDK 的預設信任存放區 （cacerts），此存放區位於 $JAVA_HOME/lib/security/cacerts 或類似的路徑。

JDK 預設信任存放區 （cacerts）

JDK 隨附名為 cacerts 的內建信任存放區，其中包含來自知名證書頒發機構單位的憑證，可驗證這些 CA 所簽發的憑證。 此信任存放區通常位於 $JAVA_HOME/lib/security/cacerts 默認密碼 「changeit」 或 「changeme」。

若要使用 JDK 預設信任存放區，請設定 UseSystemTrustStore=1 並確定您未指定自定義信任存放區或 Java 系統屬性信任存放區。 如果也使用 Java 系統屬性 javax.net.ssl.trustStore指定信任存放區，則會忽略它，這可確保驅動程式只會使用預設 JDK 信任存放區的憑證。

信任存放區的優先順序排列

驅動程式會使用下列優先順序來判斷要使用的信任存放區：

  1. 連接屬性中指定的 SSLTrustStore 自定義信任存放區
  2. Java 系統屬性 javax.net.ssl.trustStore 中指定的信任存放區（在 UseSystemTrustStore=1 時）
  3. JDK 的預設信任存放區 （cacerts）

安全性建議

若要保護您的連線安全，Databricks 建議下列各項：

  • 針對生產環境：

    • 請勿使用自我簽署憑證模式 （AllowSelfSignedCerts=1）。
    • 使用官方 CA 簽署的憑證。
    • 除非您需要自訂信任存放區，否則請使用 UseSystemTrustStore=1 。

  • 自訂信任存放區：

    • 當連線到不在預設信任存放區中的憑證伺服器時，請使用。
    • 請確定信任存放區包含完整的憑證鏈結。
    • 使用適當的權限保護信任存儲檔案。

重試策略屬性

Databricks JDBC 驅動程式 （OSS） 支援下列重試策略屬性。 屬性不區分大小寫。

財產 預設值 說明
RateLimitRetry 1 如果設定為 1，則會在速率限制錯誤時啟用重試。
RateLimitRetryTimeout 120 速率限制重試逾時 （以秒為單位）。
TemporarilyUnavailableRetry 1 如果設定為 1，則會在暫時無法使用的錯誤上啟用重試。
TemporarilyUnavailableRetryTimeout 900 暫時無法使用錯誤的重試逾時，以秒為單位。
VolumeOperationRetryableHttpCode 408,429,500,502,503,504 用於 Unity Catalog 卷攝取的重試 HTTP 代碼的逗號分隔列表。
VolumeOperationRetryTimeout 15 Unity Catalog 磁碟區擷取 HTTP 要求的重試超時時間（以分鐘為單位）。

效能和連線管理屬性

Databricks JDBC 驅動程式 （OSS） 支援下列效能和連線管理屬性。 屬性不區分大小寫。

財產 預設值 說明
CloudFetchThreadPoolSize 16 雲端提取作業的執行緒集區大小。
DefaultStringColumnLength 255 用於中繼資料報告的 STRING 字串欄位中可包含的字元數上限。
HttpConnectionPoolSize 100 HTTP 連線集區大小上限。
IdleHttpConnectionExpiry 60 閒置的 HTTP 連線到期時間 （以秒為單位）。
RowsFetchedPerBlock 2000000 查詢每次可傳回的資料列數目上限。 這僅適用於內嵌結果。
SocketTimeout 900 網路操作的通訊端逾時設定（以秒為單位）。

SQL 設定屬性

Databricks JDBC 驅動程式支援下列 SQL 組態屬性。 這些也會在 組態參數中說明。 屬性不區分大小寫。

財產 預設值 說明
ansi_mode TRUE 是否要針對特定函式和轉換規則啟用嚴格的 ANSI SQL 行為。
enable_photon TRUE 是否要啟用 Photon 向量化查詢引擎。
legacy_time_parser_policy EXCEPTION 用來剖析和格式化日期和時間戳的方法。 有效值為 EXCEPTION、LEGACY和 CORRECTED。
max_file_partition_bytes 128m 從檔案型來源讀取時，單一分割區所能打包的最大位元組數目。 此設定可以是任何正整數，並選擇性地包含量值，例如 b（位元組）、k 或 kb（1024 個字節）。
query_tags "" （空字串） 以逗號分隔的索引鍵值標籤清單，可附加至 SQL 查詢，以便在 中 system.query.history進行追蹤和分析。
read_only_external_metastore false 控制外部中繼存放區是否設定為唯讀狀態。
statement_timeout 172800 設定介於 0 到 172800 秒之間的 SQL 語法逾時。
timezone UTC 設定當地時區。 格式 area/city的區域標識符，例如美國/Los_Angeles或區域位移格式為 （+|-）HH、（+|-）HH：mm 或 （+|-）HH：mm：mm：ss，例如 -08、+01：00 或 -13：33：33。 此外，UTC 支援作為 +00:00 的別名
use_cached_result true Databricks SQL 是否會在可能的情況下快取並重複使用結果。

記錄屬性

Databricks JDBC 驅動程式支援下列記錄屬性。 屬性不區分大小寫。

財產 預設值 說明
LogFileCount 10 允許的記錄檔數目上限
LogFileSize 10 以 MB 指定的允許記錄檔大小上限
LogLevel OFF 記錄層級，其值為 0 到 6：
  • 0：停用所有記錄。
  • 1：在 FATAL 層級啟用日誌記錄，這會記錄導致連接器中止的非常嚴重錯誤事件。
  • 2：啟用 ERROR 等級的日誌記錄，以記錄可能仍允許連線器繼續運行的錯誤事件。
  • 3：啟用 WARNING 等級的日誌記錄，這會記錄在未採取行動時可能導致錯誤的事件。
  • 4：在 INFO 層級上啟用記錄，以記錄描述連接器進度的一般資訊。
  • 5：在 DEBUG 層級上啟用記錄，這會記錄對連接器進行偵錯時很有用的詳細資訊。
  • 6：在 TRACE 層級上啟用記錄，以記錄所有連接器活動。

使用這個屬性來啟用或停用連接器中的記錄，並指定記錄檔中包含的詳細數據量。
LogPath 若要判斷記錄的預設路徑，驅動程式會以下列優先順序使用這些系統屬性所設定的值：
  • user.dir
  • java.io.tmpdir
  • 目前目錄，換句話說，.
 啟用記錄時，連接器儲存記錄檔的資料夾的完整路徑（作為字串）。 若要確定連線 URL 與所有 JDBC 應用程式相容，請在檔案路徑中輸入另一個反斜杠來逸出反斜杠 （\）。
如果 LogPath 值無效，連接器會將記錄的資訊傳送至標準輸出數據流 （System.out）。

啟用和設定記錄

JDBC 驅動程式支援 適用於 Java 的簡單記錄外觀 （SLF4J） 和 java.util.logging （JUL） 架構。 驅動程式預設會使用 JUL 記錄架構。

若要啟用及設定 JDBC 驅動程式的登入記錄：

  1. 開啟您想要使用的記錄架構：

    • 針對 SLF4J 日誌記錄，請設定系統屬性 -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER，並在 classpath 中提供與 SLF4J 2.0.13 版及更新版本相容的 SLF4J 綁定實作和對應的配置檔案。
    • 針對 JUL 記錄，請將系統屬性設定為 -Dcom.databricks.jdbc.loggerImpl=JDKLOGGER。 這是預設值。

  2. 將連接字串上的 LogLevel 屬性設定為要包含在記錄檔中所需的資訊層級。

  3. 將連接字串上的 LogPath 屬性設定為您要儲存記錄檔之資料夾的完整路徑。

    例如，下列連線 URL 會啟用記錄層級 6，並將記錄檔儲存至 C：temp 資料夾：

    jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp

  4. 重新啟動您的 JDBC 應用程式，然後重新連線到伺服器以套用設定。

其他功能屬性

下列屬性會啟用 Databricks JDBC 驅動程式中的功能。 屬性不區分大小寫。

財產 預設值 說明
EnableArrow 1 如果設為 0，則會停用結果的箭頭序列化，這也會停用 Cloud Fetch 行為，因為 Cloud Fetch 需要箭頭格式。
EnableComplexDatatypeSupport 0 如果設定為 1，則會啟用以原生 Java 物件取代字串的複雜數據類型 （ARRAYs、STRUCT、MAP） 支援。
EnableDirectResults 1 如果設定為 1，則會啟用直接結果，以改善查詢效能。
EnableGeoSpatialSupport 0 若設為 1，則可支援地理空間資料型態（GEOMETRY 和 GEOGRAPHY）作為結構化 Java 物件。 需要 EnableComplexDatatypeSupport=1 和 EnableArrow=1 （Arrow 預設已啟用）。 停用時，地理空間欄位會以 EWKT 格式的 STRING 格式回傳。 參見 ST地理空間函數。
EnableSqlScripting 1 或 true 啟用複合語句區塊（BEGIN...END）和儲存過程調用的 SQL 腳本支援。 可在驅動版本 1.0.10 及以上，並支援 Databricks 執行環境 16.3 及以上版本。
儲存程序需要 Databricks 執行時 17.0 及以上版本及驅動程式版本 3.0.1 及以上。 使用 Statement 或 PreparedStatement 呼叫程序。 不支援 CallableStatement。 關於語法和範例，請參見 SQL 腳本。
EnableMetricViewMetadata 0 若設為 1，則可強化度量檢視的元資料操作。 請參閱 使用 Databricks JDBC 驅動程式處理度量視圖元資料。
EnableTelemetry 0 如果設定為 1，則會啟用遙測。 請參閱 遙測。
EnableVolumeOperations 1或 true 客戶端信息屬性，以在流上啟用音量操作。 請參閱 使用 Databricks JDBC 驅動程式管理磁碟區中的檔案。 根據預設，此屬性也會啟用 REMOVE 磁碟區上的操作。
重要： 您必須將此設定為用戶端資訊屬性。 僅在連線 URL 中提供，無法啟用串流的磁碟區操作。
MaxBatchSize 500 批次作業和資料處理的批次大小上限。
QueryResultCompressionType 1 有效值為 0 （表示無壓縮） 和 1 （表示 LZ4 壓縮）。 驅動程式會自動將內嵌結果覆寫為 0（無壓縮），無論設定為何。
UserAgentEntry browser 要包含在 HTTP 要求中的 User-Agent 項目。 此值的格式如下：[ProductName]/[ProductVersion] [Comment]
UseThriftClient 1 JDBC 驅動程式是否應該使用 Thrift 用戶端或 語句執行 API。
VolumeOperationAllowedLocalPaths `` 逗號分隔的允許本機路徑清單，用於下載和上傳 Unity Catalog 磁碟區擷取檔案。 路徑也包含子目錄。 如果未指定，則會回復至 的值 StagingAllowedLocalPaths，然後回復至未指定任何限制的空字串。 請參閱 使用磁碟區管理檔案。
要： 如果設定位於多租用戶環境 （例如 BI 工具或開發人員服務） 中，且使用者控制完整的 JDBC URL，則服務應將此內容設定為沙箱位置或不存在的路徑。 這可以防止使用者寫入任意檔案並干擾服務的內部部署。

遙測數據收集

遙測技術使Databricks能夠簡化除錯過程，並通過收集資訊來及時提供故障排除。

  • 客戶端環境詳細信息（驅動程式版本、運行時間、操作系統詳細信息）
  • JDBC 連線配置（不包括任何 PII 數據）
  • 操作延遲測量
  • 執行結果格式（內聯 JSON、Arrow 等）
  • 操作類型（執行查詢、元數據查詢、卷操作）
  • 錯誤分類資料
  • 重試次數

備註

Databricks 維持嚴格的隱私標準，確保不會收集查詢內容、結果或任何個人識別資訊（PII）。

  • Last updated on