Cube Databricks JDBC 驱动深度解析从变更日志看认证、导出桶与 SQL 下推的演进【免费下载链接】cube Cube Core is open-source semantic layer for AI, BI and embedded analytics项目地址: https://gitcode.com/gh_mirrors/cu/cube本指南以cubejs-backend/databricks-jdbc-driver包变更日志当前版本 1.7.42为主线系统梳理 Cube Core 接入 Databricks 数据源所依赖的 JDBC 驱动的技术能力与演进脉络。你将掌握该驱动的连接与认证模型Token / OAuth M2M / Azure AD / OIDC 工作负载身份、export bucket 只读卸载机制、免唤醒连接检查以及面向 Databricks 方言的 SQL 下推与 HLL 近似去重实现并了解如何在当前仓库中验证这些行为。包定位Cube 与 Databricks 之间的 JDBC 桥cubejs-databricks-jdbc-driver是 Cube 语义层针对 Databricks Lakehouse 的官方数据库驱动。它在 README 中明确说明自身构建于 Databricks 开源的 JDBC 驱动。从源码结构看驱动包由五个核心文件组成src/DatabricksDriver.ts驱动主体继承自通用JDBCDriver负责连接配置、认证、元数据查询与 export bucket 卸载src/DatabricksQuery.ts查询方言实现定义 Databricks/Spark SQL 的函数模板、过滤与时间聚合规则src/helpers.tsJDBC URL 解析与参数校验src/installer.tsJDBC jar 的解析、下载与缓存src/post-install.tsnpm 安装后的自动下载入口。package.json 显示该包要求 Node.js20.0.0核心依赖为cubejs-backend/base-driver、cubejs-backend/jdbc-driver、cubejs-backend/schema-compiler与cubejs-backend/shared均为 1.7.42 同版本并使用uuid^11.1.1。JDBC 驱动内核从 Simba 到 OSS 驱动与 3.4.2 固定版本变更日志中有多条切换/升级 OSS Databricks JDBC 驱动的记录这构成了驱动内核演进的清晰脉络1.3.02025-04-11Switch to the latest OSS Databricks JDBC driver全面转向 Databricks 官方开源驱动取代遗留的 Simba 驱动1.2.282025-04-01同一方向的早期切换提交1.6.662026-07-03Upgrade driver to 1.0.11修复 out of sequence response: expected N but got N-1 这类响应错序问题1.7.412026-09-18Upgrade OSS JDBC driver to 3.4.2是当前仓库锁定的最新版本。上述版本号在源码中得到直接印证installer.ts 中定义DRIVER_VERSION 3.4.2与 jar 文件名databricks-jdbc-3.4.2.jar运行时通过resolveJDBCDriver()按以下顺序解析 jar当前工作目录下的databricks-jdbc-3.4.2.jar包内download目录中的同名文件都没有时从 Maven 中央仓库repo1.maven.org下载并缓存到download目录失败则提示手动放置。驱动类在 DatabricksDriver.ts 中通过drivername: com.databricks.client.jdbc.Driver指定 Java 驱动类并在getCustomClassPath()中调用resolveJDBCDriver()把 jar 加入 classpath。README 的 Testing 一节特别提示单元测试需要本机安装 JavaJRE 11.0 及以上因为连接依赖 JDBC jar 通过 JVM 执行。此外3.4.1 起 OSS 驱动默认开启地理空间支持EnableGeoSpatialSupport1这会把 GEOMETRY/GEOGRAPHY 列以 Java 对象而非 EWKT 字符串返回。驱动因此做了两件事见 DatabricksDriver.ts在连接属性中固定EnableGeoSpatialSupport: 0同时在 helpers.ts 的validateAndRemoveGeoSpatialSupportFromJdbcUrl中若用户 JDBC URL 显式传入EnableGeoSpatialSupport1则直接抛错而非静默忽略。对应测试位于 test/DatabricksDriver.test.ts覆盖大小写变体、重复参数等多种写法。连接与认证模型演进Token、OAuth M2M 与 Azure AD认证是变更日志中更新最密集的领域之一共经历四轮演进阶段一个人访问 TokenPAT构造器通过conf.token || CUBEJS_DB_DATABRICKS_TOKEN或 JDBC URL 中的PWD取得令牌以UIDPWDAuthMech: 3的形式传给驱动见 DatabricksDriver.ts。出于安全考量1.7.x 起驱动会主动告警两类弃用项showDeprecationsJDBC URL 中的PWD参数已弃用建议迁移到CUBEJS_DB_DATABRICKS_TOKEN环境变量jdbc:spark://协议已弃用构造函数会自动将其改写为jdbc:databricks://并建议迁移CUBEJS_DB_DATABRICKS_URL。阶段二M2M OAuth1.3.202025-06-06变更日志记录Support M2M OAuth Authentication。源码中当配置了oauthClientIdoauthClientSecret对应CUBEJS_DB_DATABRICKS_OAUTH_CLIENT_ID/SECRET时认证属性切换为OAuth2ClientIDOAuth2SecretAuthMech: 11Auth_Flow: 1注释指出 Magic Number 含义见 Databricks OSS JDBC 文档。若只提供 ID 或 Secret 之一会直接抛错三者皆无则报 No credentials provided。OAuth 场景下的令牌获取逻辑值得注意fetchAccessToken()并不依赖 JDBC 驱动而是用node-fetch直接向https://{host}/oidc/v1/token发起client_credentials授权请求scope 为all-apis换取 access token并在过期前 60 秒预刷新getValidAccessToken。阶段三Azure AD Client Secret1.1.172025-01-27变更日志记录Enable Azure AD authentication via Client Secret。配置项为azureTenantId/azureClientId/azureClientSecret对应环境变量CUBEJS_DB_EXPORT_BUCKET_AZURE_TENANT_ID/..._CLIENT_ID/..._CLIENT_SECRET主要用于 export bucket 的访问控制详见下文导出桶一节。阶段四OIDC / 工作负载身份1.6.622026-06-23变更日志记录support OIDC/workload identity for export buckets。源码中getCsvFiles()对三类云存储做了凭据缺省即回退到身份链的处理Azure未配置静态 key/secret 时传undefined让 Azure SDK 走DefaultAzureCredential从AZURE_FEDERATED_TOKEN_FILE解析联合身份令牌S3仅当 key 与 secret 同时配置才显式传静态凭据否则交由 AWS SDK 默认凭据链如AWS_WEB_IDENTITY_TOKEN_FILE注释明确说明传空字符串会导致AuthorizationHeaderMalformedGCS未配置gcsCredentials时回退到GOOGLE_APPLICATION_CREDENTIALS含 workload-identity-federation 的external_account配置。对应测试 test/DatabricksDriver.test.ts 用 mock 捕获了 S3 客户端构造参数断言空 OIDC 凭据不会被转发。免唤醒连接检查不启动 SQL Warehouse 的 testConnection1.3.10变更日志 1.3.102025-05-01记录Implement connection checking without waking up SQL warehouse。此前连接测试会发起真实 JDBC 查询从而把处于停止状态的 Databricks SQL Warehouse 唤醒产生不必要的成本与延迟。源码实现中testConnection()完全绕开 JDBC改用 Databricks REST API先按认证类型取得BearertokenOAuth 场景走getValidAccessToken然后 GEThttps://{host}/api/2.0/sql/warehouses/{warehouseId}见 DatabricksDriver.ts。warehouseId通过 helpers.ts 的parseDatabricksJdbcUrl从 JDBC URL 的httpPath中正则提取形如/sql/1.0/warehouses/{id}缺失httpPath会直接报错。检查逻辑根据响应状态判断DELETING/DELETED状态视为仓库正在删除health.status FAILED视为健康检查失败并输出 summary/detailsDEGRADED状态不判定失败注释解释它不意味着集群完全不可用。这一设计使 Cube 在定时刷新、连接池健康检查等场景中无需唤醒数据仓库即可快速判断连通性。导出桶与只读模式面向 Cube Store 的高吞吐卸载read-only 模式0.35.59 与 1.6.15变更日志 0.35.592024-07-13首次引入read-only mode1.6.152026-02-23进一步支持export bucket in read-only mode。源码中readOnly配置项的默认值并非 false而是config.readOnly !config.exportBucket见 DatabricksDriver.ts只要未配置导出桶驱动自动进入只读模式readOnly()返回 true禁止写入类操作——这避免了 Cube 在仅做查询分析时对 Databricks 侧产生任何写负载。导出桶类型与路径支持1.3.0、1.2.26、0.35.41驱动支持三类导出桶SUPPORTED_BUCKET_TYPES [s3, gcs, azure]S3 于 1.2.26 起支持桶内路径GCS 支持由 1.3.0 的Add export bucket support for Google Cloud Storage引入。对应环境变量如下用途环境变量桶类型CUBEJS_DB_EXPORT_BUCKET_TYPEs3/gcs/azure桶地址CUBEJS_DB_EXPORT_BUCKET如s3://bucket、wasbs://containeraccount.blob.core.windows.netDBFS 挂载目录CUBEJS_DB_EXPORT_BUCKET_MOUNT_DIR轮询间隔CUBEJS_DB_POLL_MAX_INTERVAL秒源码内乘以 1000 转毫秒CSV 转义符CUBEJS_DB_EXPORT_BUCKET_CSV_ESCAPE_SYMBOLS3CUBEJS_DB_EXPORT_BUCKET_AWS_KEY/SECRET/REGIONAzureCUBEJS_DB_EXPORT_BUCKET_AZURE_KEY/TENANT_ID/CLIENT_ID/CLIENT_SECRETGCSCUBEJS_DB_EXPORT_GCSCREDENTIALS卸载流程INSERT OVERWRITE 签名 URLunload()流程见 DatabricksDriver.ts分两步先用INSERT OVERWRITE DIRECTORY ... USING CSV OPTIONS (escape )将查询结果或整表写入桶unloadWithSql先DESCRIBE QUERY取列类型再建外部表unloadWithTable走DESCRIBE取表结构再由getCsvFiles()按桶类型生成带签名的 CSV 文件 URL 列表返回给 Cube Store。返回值含exportBucketCsvEscapeSymbol、csvFile与csvNoHeader: true。1.6.162026-02-26的Dont use temporary tables for export bucket优化了写入路径避免创建临时表带来的额外开销同版本还回滚了 1.6.15 之外的一次相关提交最终保留了只读模式下支持导出的能力。1.5.8 还为此类导出引入numeric类型 precision/scale 的保真支持。HLL 与导出桶协同0.35.41、0.35.44变更日志 0.35.41 记录Support HLL feature with export bucket。源码中generateTableColumnsForExport()针对hll_datasketches类型列使用base64(column)包装后导出CSV 数据源不支持 BINARY 类型相关实现与注释见 DatabricksDriver.ts。0.35.44 则修复了Rolling window count_distinct_approx (HLL)组合场景。面向 Databricks 方言的 SQL 生成与下推演进DatabricksQuery.ts 是整个方言层的核心变更日志中的大量 cubesql push down 条目在此都有对应实现变更日志条目源码实现1.7.26Support DATE_ADD SQL pushdowntemplates.functions.DATE_ADD ({{ args[0] }} INTERVAL {{ interval }} {{ date_part }})注释解释采用非引号多单元形式以兼容亚日间隔按毫秒报告的细节0.36.7Support DATE_PART SQL push downtemplates.functions.DATEPART DATE_PART({{ args_concat }})1.7.4Translate PostgreSQL format tokens in TO_CHARTO_CHAR模板用 19 层嵌套REPLACE把 PG 的HH24/MM/SS/YYYY/Month...令牌翻译为 Spark 的HH/mm/ss/yyyy/MMMM...并用H24、DOY占位防止HH→hh与DD规则误伤0.36.9Fix TRUNC SQL push downTRUNC模板按正负号分别展开为FLOOR/CEIL1.7.1Push down UTCTIMESTAMP (CURRENT_TIMESTAMP)UTCTIMESTAMP TO_UTC_TIMESTAMP(CURRENT_TIMESTAMP(), CURRENT_TIMEZONE())0.35.49GREATEST/LEASTLEAST/GREATEST函数模板1.7.11/1.7.9Keep PostgreSQL integer division semanticsint_division ({{ left }} div {{ right }})用 Sparkdiv的截断向零语义对齐 PG0.35.67push down cast type templatescastToString等类型模板0.34.57WHERE SQL push down与 schema-compiler 配合的 WHERE 下推能力1.7.13Correct SQL parameter escapingescapeDialect()返回spark选择 Spark 风格转义0.35.33Fix Databricks identifier quotesescapeColumnName与quoteIdentifier均使用反引号包裹标识符时间与粒度方向同样有迹可循1.1.8 的Support for intervals and CURRENT_DATE对应subtractInterval/addInterval基于parseSqlInterval拼装INTERVAL n unit与CURRENTDATE CURRENT_DATE模板0.36.0 的custom granularity support对应supportGeneratedSeriesForCustomTd()与基于sequenceexplode的generated_time_series_select模板1.3.24 的 REST API 查询 order 段支持td with granularity1.3.50 的tesseract: Support time series queries in Databricks对应time_series_select的 VALUES 展开模板。近似去重与聚合方面countDistinctApprox生成approx_count_distinct(...)0.35.44 的修复对象0.35.32 引入的 HLL 支持在hllInit/hllMerge/hllCardinality/hllCardinalityMerge中分别映射为hll_sketch_agg、hll_union_agg、hll_sketch_estimateDatabricks 的 datasketches 函数族。0.35.79 的correct string casting对应castToString使用CAST(... as STRING)。工程化与依赖演进变更日志还记录了若干工程侧的变化多数可在 package.json 中验证TypeScript 6.0.31.7.36/1.7.37devDependencies 中typescript: ~6.0.3为 Cube 7 做准备uuid 8.3.2 → 11.1.11.7.20dependencies 中uuid: ^11.1.1移除 inquirer 减小镜像体积0.35.55当前依赖列表中确无 inquirer默认并发1.2.4 相关的刷新并发调整getDefaultConcurrency()返回 101.6.34pre-aggregation-specific data source configuration构造器的dataSource/preAggregations参数贯穿所有getEnv调用允许预聚合使用独立的数据源配置1.6.7 日志 level 字段setLogger与告警机制基于 base-driver 的 logger 体系1.6.53Links in the data model数据模型链接能力由 schema-compiler 承载。本地验证与测试如果你想在仓库内验证上述行为可参考 README 的 Testing 一节yarn yarn test测试基于 Jest配置见 jest.config.js前提是本机安装 JavaJDBC jar 通过 JVM 工作。核心测试文件 test/DatabricksDriver.test.ts 覆盖Azure 导出桶的签名 URL 生成shared key 与 client secret 两种凭据路径EnableGeoSpatialSupport1的拒绝逻辑与0的剥离逻辑S3 客户端构造参数中空 OIDC 凭据不被转发CUB-3000 回归环境变量驱动的配置解析URL、token、export bucket 系列。注意这些单元测试通过 mock 隔离云 SDK 与 JDBC 连接并未真实连接 Databricks 集群真实联调需要你自行准备 SQL Warehouse、token/服务主体与导出桶凭据。小结从 0.35 到 1.7cubejs-databricks-jdbc-driver的演进主线可以概括为四条内核跟随 OSS JDBC 驱动持续升级最终固定 3.4.2、认证从 PAT 走向 OAuth M2M / Azure AD / OIDC 工作负载身份、查询执行从写回数据库转向 export bucket Cube Store 只读卸载、SQL 下推面持续扩大时间函数、类型转换、聚合近似值。阅读 CHANGELOG 时配合 src/DatabricksDriver.ts 与 src/DatabricksQuery.ts 逐一对照可以最直观地理解每条变更背后的实现细节。【免费下载链接】cube Cube Core is open-source semantic layer for AI, BI and embedded analytics项目地址: https://gitcode.com/gh_mirrors/cu/cube创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考