尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

Cube Materialize 数据库驱动(MaterializeDriver)技术指南

Cube Materialize 数据库驱动(MaterializeDriver)技术指南 后端数据分析数据可视化数据库【免费下载链接】cube Cube Core is open-source semantic layer for AI, BI and embedded analytics项目地址https://gitcode.com/gh_mirrors/cu/cube点击查看免费下载Cube Materialize Database Drivercubejs-backend/materialize-driver是 Cube 开源语义层Cube Core中连接 Materialize 流式数据仓库的数据库驱动。它以 Cube 的 PostgreSQL 驱动为基础用纯 JavaScript 实现让 Cube 可以针对 Materialize 的物化源materialized sources、物化视图materialized views与普通表统一构建语义层并实时查询。阅读本文后你将掌握该驱动在 Cube 数据连接体系中的定位、依赖关系与支持边界如何配置CUBEJS_DB_TYPEmaterialize及其配套环境变量接入 Materialize驱动底层的关键实现类型系统、SSL、时区、Schema 探测、游标流式读取以及如何通过测试与源码验证这些行为。说明本驱动为社区支持community supported由 Joaquin Colacci 贡献、Materialize 团队当前维护可在 Apache 2.0 许可下使用但应自担风险。驱动是什么基于 PostgreSQL 协议的精简 Materialize 适配Materialize 是面向增量计算的数据仓库SQL 接口与 PostgreSQL 兼容。该驱动没有重新实现一套数据库协议而是直接继承 Cube 的 PostgreSQL 驱动PostgresDriver在其上覆盖 Materialize 特有的行为。这一点在源码中有明确证据src/MaterializeDriver.ts 中export class MaterializeDriver extends PostgresDriver { ... }index.js 的注释直接写明 “Fork from Postgres cube.js driver”package.json 声明依赖cubejs-backend/postgres-driver、cubejs-backend/base-driver、cubejs-backend/shared和semver。因此Materialize 的连接参数host、port、user、password、database 等与 PostgreSQL 驱动一致复用 pg 客户端协议。生产环境里 Cube 与 Materialize 之间的连接池同样继承自 PostgreSQL 驱动实现并在其上追加了 Materialize 相关的连接初始化逻辑。安装与版本要求安装在 Cube 项目中安装本驱动与 Cube 核心版本保持一致npm install cubejs-backend/materialize-driver1.7.42 # 或使用 yarn yarn add cubejs-backend/materialize-driver1.7.42当前仓库中该包的版本为1.7.42见 package.json要求Node.js 20.0.0见 package.jsonengines字段许可协议为Apache-2.0LICENSE。引入方式包同时支持 CommonJS 与 ESM 两种引入方式package.jsonexports字段// CommonJS const { MaterializeDriver } require(cubejs-backend/materialize-driver); // ESM import MaterializeDriver, { MaterializeDriver as Named } from cubejs-backend/materialize-driver;index.ts 以默认导出MaterializeDriver同时export *暴露命名导出。构建与测试驱动是 TypeScript 编写的npm run build会执行tsc生成dist目录package.json。运行集成测试npm run integration # 等价于 npm run integration:materialize集成测试test/MaterializeDriver.test.ts依赖 DockerMaterializeDBRunner.startContainer会拉起materialize/materialized容器默认端口 6875镜像版本可通过环境变量TEST_MZSQL_VERSION或options.version覆盖默认v0.88.0见 packages/cubejs-testing-shared/src/db-container-runners/materialize.ts。快速开始Cube 连接 Materialize连接配置在 Cube 的.env中声明以下变量即可启用 Materialize 数据源CUBEJS_DB_TYPEmaterialize CUBEJS_DB_HOSTlocalhost CUBEJS_DB_PORT6875 CUBEJS_DB_NAMEmaterialize CUBEJS_DB_USERmaterialize CUBEJS_DB_PASSmaterialize CUBEJS_DB_SSLfalse # 见下文“SSL 默认开启”一节 CUBEJS_DB_MATERIALIZE_CLUSTERquickstart其中环境变量说明默认值CUBEJS_DB_TYPE数据源类型设为materialize—CUBEJS_DB_HOST/CUBEJS_DB_PORTMaterialize 实例地址默认端口 6875localhost/6875CUBEJS_DB_NAME/CUBEJS_DB_USER/CUBEJS_DB_PASS数据库名、用户名与密码—CUBEJS_DB_SSL是否启用 TLSfalse关闭true要求服务端证书校验默认开启见下文CUBEJS_DB_MATERIALIZE_CLUSTER连接使用的 Materialize cluster执行SET CLUSTER TO ...不设置则不切换CUBEJS_DB_MATERIALIZE_...驱动专属扩展参数—编程方式创建驱动除环境变量外也可以直接实例化驱动与测试用法一致见 test/MaterializeDriver.test.tsconst { MaterializeDriver } require(cubejs-backend/materialize-driver); const driver new MaterializeDriver({ host: localhost, port: 6875, user: materialize, password: materialize, database: materialize, cluster: quickstart, // 可选指定 cluster ssl: false, // 本驱动 SSL 默认开启本地测试建议显式关闭 maxPoolSize: 8, // 可选连接池大小 executionTimeout: 600, // 可选查询超时秒 }); await driver.query(SELECT 1, []);构造函数支持的选项在 src/MaterializeDriver.ts 中构造函数接收PostgresDriverConfiguration并扩展了以下字段dataSource?: string—— 数据源名称maxPoolSize?: number—— Cube 与数据库之间连接池的最大连接数testConnectionTimeout?: number—— 连接验证超时默认 10000 mscluster?: string—— 可选连接建立后切换到的 Materialize clusterssl?: boolean | { rejectUnauthorized: boolean }—— TLS 配置默认开启application_name?: string—— 连接的应用名默认cubejs-materialize-driver用于在 Materialize 侧识别连接来源。SSL 与连接初始化默认启用 TLS这是 Materialize 驱动与普通 PostgreSQL 驱动最明显的差异之一。构造逻辑src/MaterializeDriver.ts如下const sslEnv process.env.CUBEJS_DB_SSL; if (sslEnv false) { options.ssl false; } else if (sslEnv true) { options.ssl { rejectUnauthorized: true }; } else if (options.ssl undefined) { options.ssl true; }要点未显式设置时ssl默认为true即默认要求 TLS 加密连接CUBEJS_DB_SSLfalse会显式关闭CUBEJS_DB_SSLtrue时校验服务端证书rejectUnauthorized: trueapplication_name默认填cubejs-materialize-driver。每次连接建立prepareConnection见 src/MaterializeDriver.ts时还会执行SET TIME ZONE storeTimezone 或 UTC; -- 若设置了 CUBEJS_DB_MATERIALIZE_CLUSTER SET CLUSTER TO cluster;时区统一到storeTimezone默认 UTC保证查询语义一致cluster 切换使所有查询落在指定计算集群上。源码注释还标明Materialize 对statement_timeout的支持仍在推进对应 Materialize 上游 issue #10390因此驱动不做该设置。Schema 探测只索引“可查询”的对象Cube 需要从information_schema中发现表结构。Materialize 中并非所有对象都能被 Cube 查询——只有**物化源materialized sources、物化视图materialized views和表tables**才可作为查询对象。驱动通过informationSchemaQueryWithFiltersrc/MaterializeDriver.ts按版本分派过滤逻辑Materialize v0.27.0-alpha只包含mz_catalog.mz_sources中已物化的源、mz_catalog.mz_views中已物化的视图以及mz_catalog.mz_tables中的表Materialize v0.27.0-alpha直接取mz_sources、mz_tables、mz_materialized_views物化视图此时为独立目录对象。版本号通过getMaterializeVersion()src/MaterializeDriver.ts执行SELECT mz_version() as version;获取并截取空格前的版本片段例如v0.24.3-alpha.5 (65778f520)→v0.24.3-alpha.5。测试 test/MaterializeDriver.test.ts 验证了这一行为同时创建表A、普通视图V、物化视图MV后调用tablesSchema()结果中a、mv存在而普通视图v不存在——普通视图不会被纳入 Cube 的语义层。另外驱动重写了loadUserDefinedTypes()为空实现src/MaterializeDriver.tsMaterialize 对typcategory字段的支持仍在推进上游 issue #2157因此跳过用户自定义类型的加载。Schema 创建与数据上传创建 SchemacreateSchemaIfNotExistssrc/MaterializeDriver.ts先执行SHOW SCHEMAS WHERE name schema判断不存在时再执行CREATE SCHEMA IF NOT EXISTSpublic async createSchemaIfNotExists(schemaName: string): Promisevoid { const schemas await this.query(SHOW SCHEMAS WHERE name ${schemaName}, []); if (schemas.length 0) { await this.query(CREATE SCHEMA IF NOT EXISTS ${schemaName}, []); } }上传表uploadTableWithIndexessrc/MaterializeDriver.ts直接委托给BaseDriver.prototype.uploadTableWithIndexes并传入空索引列表与空参数——Materialize 不需要也不支持传统数据库那样的二级索引构建。测试中通过driver.uploadTable(test.streaming_test, columns, rows)上传样例数据见 test/MaterializeDriver.test.ts。默认并发度驱动将默认并发度设为2getDefaultConcurrency()src/MaterializeDriver.ts。该值影响 Cube 对同一数据源的并发查询/写入调度可在需要时结合maxPoolSize调整。流式读取基于游标Cursor的分批拉取Materialize 是流式引擎本驱动专门实现了基于游标的流式查询stream()src/MaterializeDriver.ts流程如下从连接池获取连接this.pool.acquire()执行prepareConnection设置时区与 clusterBEGIN;开启事务DECLARE mz_cursor CURSOR FOR query声明游标FETCH 0 FROM mz_cursor;获取字段元数据fields创建Readable.from(asyncFetcher(...))数据流并返回{ rowStream, types, release }。asyncFetchersrc/MaterializeDriver.ts每次FETCH 1000行WITH (TIMEOUT...)直到返回空行为止FETCH 1000 mz_cursor WITH (TIMEOUTexecutionTimeout*1000默认 600000 milliseconds);每次抓取 1000 行超时默认 600000 ms10 分钟可由executionTimeout秒调整消费完毕后调用release()执行COMMIT;并释放连接releaseStreamsrc/MaterializeDriver.ts若中途抛错会先释放连接再抛出异常catch分支。测试 test/MaterializeDriver.test.ts 验证了正常流读取、类型元数据以及查询不存在对象时的报错unknown catalog item ...异常路径也会正确释放连接。类型映射与结果集行为由于继承自 PostgreSQL 驱动结果集类型映射与 pg 保持一致。测试 test/MaterializeDriver.test.ts 展示了关键行为输入类型返回结果说明DATE 2020-01-012020-01-01T00:00:00.000按 UTC 格式化TIMESTAMP 2020-01-01 00:00:002020-01-01T00:00:00.000无时区TIMESTAMPTZ 2020-01-01 00:00:00022019-12-31T22:00:00.000已转换为 UTCDECIMAL(10,2) 1.01字符串数值以字符串返回避免精度丢失即timestamptz统一按 UTC 返回decimal以字符串形式返回配合storeTimezoneUTC的会话设置保证跨时区一致性。集群Cluster使用Materialize 的计算由 cluster 承载。驱动支持两种指定方式环境变量CUBEJS_DB_MATERIALIZE_CLUSTER连接时自动执行SET CLUSTER TO ...构造函数参数cluster测试中使用cluster: quickstart见 test/MaterializeDriver.test.ts。测试 test/MaterializeDriver.test.ts 通过SHOW CLUSTER;断言当前集群为quickstart验证连接初始化确实切换到了指定 cluster。支持状态与维护边界根据 README.md该驱动由 Joaquin Colacci 贡献目前由 Materialize 团队维护属于社区支持community supported应自担风险使用Cube Dev 团队没有进一步开发计划包括 bug 修复除非影响 Cube 其他部分正在为这个包寻找维护者。这意味着新特性需求建议直接向 Materialize 或 Cube 社区反馈生产使用前应结合自身场景充分验证。小结cubejs-backend/materialize-driver用最少量的代码单个 MaterializeDriver.ts 文件将 Cube 与 Materialize 无缝衔接默认启用 TLS、自动切换时区与 cluster、按版本过滤出可查询的物化对象、基于游标的大结果集流式读取并保持与 PostgreSQL 驱动一致的类型映射。对使用 Materialize 作为流式数据仓库的团队来说只需配置CUBEJS_DB_TYPEmaterialize并设置连接信息即可在 Cube 语义层中把物化视图当作常规数据源进行建模与查询。赞分享后端数据分析数据可视化数据库【免费下载链接】cube Cube Core is open-source semantic layer for AI, BI and embedded analytics项目地址https://gitcode.com/gh_mirrors/cu/cube点击查看免费下载相关推荐Cube Materialize 数据库驱动全解从 v0.29.53 到 v1.7.42 的演进脉络与源码实现Cube Materialize 数据库驱动全解从 v0.29.53 到 v1.7.42 的演进脉络与源码实现 本文以 Cube 开源仓库中 cubejs后端数据分析数据可视化数据库Awesome DotNet数据库驱动多数据库支持技术详解Awesome DotNet数据库驱动多数据库支持技术详解 引言现代应用的数据层挑战 在当今的软件开发环境中应用程序往往需要与多种数据库系统进行交互。无论文档知识库Cube 项目 Athena 数据库驱动cubejs-backend/athena-driver完全指南架构、配置与实战Cube 项目 Athena 数据库驱动cubejs backend/athena driver完全指南架构、配置与实战 导读 本文基于 Cube 开源后端数据分析数据可视化数据库上一篇用Flutter打造微信级即时通讯应用wechat_flutter完整实践指南下一篇终极Vim键盘导航指南用Vim Vixen彻底改变你的Firefox浏览体验 创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表