数据库后端【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址https://gitcode.com/gh_mirrors/co/convex-backend点击查看免费下载Convex 作为开源的反应式数据库reactive database其官方仓库 convex-backend 中提供了fivetran_sourcecrate一个面向 Fivetran 的 source connector允许开发者把 Convex 部署中的全部数据增量复制到任意 Fivetran 支持的数仓warehouse中。本指南基于 crates/fivetran_source/docs/overview.md 与 crates/fivetran_source/docs/setup-guide.md 编写并结合 crates/fivetran_source 的源码讲解其底层同步机制、类型转换规则与配置方式。读完本文你将掌握如何创建 Fivetran 连接、理解 Convex 类型到 Fivetran 类型的映射表、处理嵌套文档的落库方式并了解连接器基于data syncAPI 的增量同步原理。1. 连接器是什么fivetran_source是一个运行在 Fivetran 基础设施上的 gRPC 服务端实现 Fivetran Partner SDK 的SourceConnector接口。它通过 Convex 暴露的 HTTP API如POST /api/v1/data/sync读取部署数据再以 Fivetran 定义的 gRPC 协议把数据流式推送给 Fivetran 平台最终落到你的目标数据仓库中。crate 的 READMEcrates/fivetran_source/README.md明确说明This crate contains a source connector allowing developers using Convex to replicate the data they store in Convex to other databases.该连接器由 Convex 团队构建属于 Fivetran 的Partner-Built连接器对 Convex 的疑问需咨询 Convex 官方支持团队。2. 功能概览初始快照 CDC 增量同步连接建立后先抓取 Convex 部署的完整一致快照初始同步完成后通过 Change Data CaptureCDC以更新的一致视图增量同步变更。可配置同步频率后续增量同步的频率可在 Fivetran 侧配置。断点续传每次同步都从上次停止的位置恢复被中断的同步不会从头重来参见 crates/fivetran_source/docs/overview.md 的 Sync overview 一节。组件/表/字段级选择可在 Fivetran dashboard 上排除不需要同步的 Convex 组件、表和字段。Schema 自动映射将 Convex 的表与列结构自动复制到目标库遵循 Fivetran 的标准数据库更新策略。3. 前置条件连接 Convex 部署到 Fivetran 前你需要准备crates/fivetran_source/docs/setup-guide.md一个 ConvexProfessional 计划的账号。一个 Convex deployment部署实例。该部署的Deployment URL例如https://jaded-raven-991.convex.cloud。一个deploy key且只需授予deployment:data:view权限——这是连接器唯一需要的权限用于读取表的文档与 schema。可在 Production Deployment Settings 页面生成。注意deployment:data:view是连接器的最小权限要求无需授予任何写权限。4. 配置步骤4.1 获取部署凭据打开 Convex dashboard 进入你的部署。进入 Production Deployment Settings 页面。记录 Deployment URL。生成一个 deploy key并只开启deployment:data:view权限。记录该 deploy key与 Deployment URL 一起用于 Fivetran 配置。4.2 完成 Fivetran 配置在 connection setup form 中输入Destination schema prefix。该前缀会应用到每个复制的 schema且连接创建后不可更改。输入Deployment URL。输入Deploy Key。点击Save TestFivetran 会测试并验证与 Convex 部署的连接测试通过后即可开始同步。4.3 Setup testsFivetran 会执行以下测试校验部署凭据包括 deploy key 是否具备deployment:data:view权限。确认你使用的是 Convex Professional 计划。5. 同步机制从data syncAPI 说起连接器的数据同步核心是 Convex 的 data sync APIPOST /api/v1/data/sync一个分页的单一数据流同时覆盖部署数据的初始拷贝与后续变更crates/fivetran_source/README.md。在 crates/fivetran_source/src/sync.rs 中data_sync是一个异步流生成器其主循环为调用source.data_sync(cursor, selection)拉取一页数据。先处理page.truncates表需要清空重建的情况生成TRUNCATE操作。再遍历page.valuesdeleted为真时生成DELETE否则生成UPSERT记录并通过to_fivetran_row把 Convex 文档转换成 Fivetran 行。从page.pagination.next_cursor取出不透明游标随CHECKPOINT一起交给 Fivetran 持久化——a page and the cursor that follows it must be persisted atomically页与后续游标必须原子持久化。当page.status为DataSyncStatus::UpToDate时视为已追平最新数据结束本次同步等待 Fivetran 调度下一次同步。关键点游标与页面数据一起原子提交是断点续传的保证。即使同步被中断Fivetran 侧也已持久化了上一页的游标下次同步直接从此恢复。此外data_sync_cursor_from_deltas接口用于把旧版document_deltas游标迁移成 data sync 游标让迁移前创建的连接无缝续传无需全量重同步见 crates/fivetran_source/src/sync.rs 中resolve_cursor的分支处理与 crates/fivetran_source/CHANGELOG.md 3.0.0 的说明。6. Schema 信息与类型映射Fivetran 会按照标准的数据库更新策略尽量把你 Convex 部署中的数据库与列复制到目标库。连接器通过get_table_column_names接口获取每个组件下每张表的列名生成 Fivetran schema见 crates/fivetran_source/src/schema.rs 的generate_fivetran_schema。6.1 类型转换与映射表连接器提取数据时会把 Convex 数据类型匹配为 Fivetran 支持的类型crates/fivetran_source/docs/overview.mdConvex TypeFivetran TypeFivetran SupportedIdSTRINGTrueNullNULLTrueInt64LONGTrueFloat64DOUBLETrueBooleanBOOLEANTrueStringSTRINGTrueBytesBINARYTrueArrayJSONTrueObjectJSONTrue该映射在源码中有直接对应实现crates/fivetran_source/src/convert.rs 的to_fivetran_value通过match把ConvexValue各变体转换为 Fivetran 的ValueTypeConvexValue::Null→FivetranValue::NullConvexValue::Int64→FivetranValue::LongConvexValue::Float64→FivetranValue::DoubleConvexValue::Boolean→FivetranValue::BoolConvexValue::String→FivetranValue::StringConvexValue::Bytes→FivetranValue::BinaryConvexValue::Array/Object→FivetranValue::Json序列化为 ConvexCleanJSON 格式字符串需要特别说明的两点_creationTime系统字段在 Convex 内部以 Float64 存储但连接器会特殊处理转换成UTC_DATETIMEcrates/fivetran_source/src/convert.rs 的to_fivetran_field分支。Object/Array 内的嵌套类型使用 Convex 的导出 JSON 格式序列化。此外除_id、_creationTime外的其他_开头系统字段会被跳过源码to_fivetran_field的过滤逻辑。6.2 嵌套数据如何处理Convex 文档以 JSON 表示。当第一层字段是简单类型时连接器会映射为独立列当是 Array 或 Object 这类复杂嵌套类型时会映射为 JSON 类型且不做解包——不会把嵌套 JSON 自动拆成目标库的独立表而是原样保留方便你使用 JSON 处理函数crates/fivetran_source/docs/overview.md 的 Nested data 一节。例如下面的 Convex 文档{street : Main St. city : New York country : US phone : (555) 123-5555 zip code : 12345 people : [John, Jane, Adam] car : {make : Honda, year : 2014, type : AWD} }被加载到目标库时会转换成如下表结构people数组与car对象原样保留为 JSON_idstreetcitycountryphonezip codepeoplecar1Main St.New YorkUS(555) 123-555512345[John, Jane, Adam]{make : Honda, year : 2014, type : AWD}6.3 Fivetran 生成的系统列Fivetran 会向目标库的每张表追加以下列帮助你在目的地了解数据状态与同步进度crates/fivetran_source/docs/overview.md_fivetran_syncedUTC TIMESTAMPFivetran 上次成功同步该行的时间加到每张表。_fivetran_deletedBOOLEAN该行是否在源端被删除。7. 排除源数据组件/表/字段级选择如果不想同步全部数据可以在 Fivetran dashboard 的 Convex 连接详情页取消勾选需要省略的对象crates/fivetran_source/docs/overview.md 的 Excluding source data 一节。底层实现见 crates/fivetran_source/src/conversions/selection.rsFivetran 的 selection 结构会被转换为 Convex 流式导出模块的Selection类型支持组件component、表table、列column三级选择并支持新出现对象默认包含/排除的默认策略。选择规则有两点需要特别留意包含/排除组件或表是追溯生效的新纳入的表会在下次同步时从 Convex 部署回填排除的表会从目标库删除无需历史重同步。修改列的包含与否只影响之后同步的行已存在于目标库的行不会被重写如需对旧数据应用列变更需手动触发历史重同步见 crates/fivetran_source/docs/overview.md 的 important 提示。8. 本地构建、运行与测试连接器8.1 安装与构建fivetran_source是 convex-backend 仓库中的一个 cratecrates/fivetran_source/Cargo.toml。安装 Rust 工具链后即可构建git clone https://github.com/get-convex/convex-backend.git cd convex-backend cargo build --release -p fivetran_source构建产物位于convex-backend/target/release/fivetran_source。8.2 启动连接器直接运行二进制即可启动 gRPC 服务crates/fivetran_source/README.md$ ./fivetran_source Starting the connector on [::]:50051默认监听 50051 端口可用--port参数修改$ ./fivetran_source --port 1337 Starting the connector on [::]:1337该行为在 crates/fivetran_source/src/main.rs 中实现通过clap解析--port默认值 50051绑定到0.0.0.0并以SourceConnectorServer暴露 gRPC 服务支持 gzip 压缩。README 中的本地测试方案使用just run-local-backend启动本地 Convex 后端配合 Fivetran 官方 source connector tester 驱动连接器完成 setup tests、schema 拉取与数据流式写入本地 DuckDB warehouse。9. 常见注意事项连接器版本与后端兼容3.0.0 起使用/api/v1/data/sync替代旧版list_snapshot与document_deltas要求 Convex 后端提供该接口过旧的自托管部署需先升级见 crates/fivetran_source/CHANGELOG.md。旧连接升级3.0.0 之前的连接会自动迁移并保留已有数据无需历史重同步而 2.0.0 引入 components 支持时是破坏性变更旧连接需执行一次全量历史重同步Fivetran 连接页 Setup 标签下 Resync all historical data且组件命名空间会从{{prefix}}_{{table}}变为{{prefix}}_app_{{table}}/{{prefix}}_{{component path}}_{{table}}见 crates/fivetran_source/src/connector.rs 中deserialize_state_json的版本校验逻辑。组件命名冲突根组件root component的表会落入名为app的默认 Fivetran schema如果你的 Convex 部署恰好存在名为app的组件连接器会在 schema 请求时报错提示重命名crates/fivetran_source/src/connector.rs 的_schema校验。错误呈现方式同步过程中的错误会以 FivetranTask操作的形式上报在 dashboard 上向用户展示具体错误消息而非笼统的同步失败crates/fivetran_source/src/connector.rs 的task_response。赞分享数据库后端【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址https://gitcode.com/gh_mirrors/co/convex-backend点击查看免费下载相关推荐Convex Fivetran Destination Connector 指南构建 gRPC 数据复制管道与 schema 映射实战Convex Fivetran Destination Connector 指南构建 gRPC 数据复制管道与 schema 映射实战 Fivetran De数据库后端Convex Fivetran Source Connector 实战指南基于数据同步 API 将 Convex 数据复制到任意数据库Convex Fivetran Source Connector 实战指南基于数据同步 API 将 Convex 数据复制到任意数据库 导读 convex b数据库后端Convex 后端 Fivetran Source Connector 版本演进解析从增量快照到数据同步 APIConvex 后端 Fivetran Source Connector 版本演进解析从增量快照到数据同步 API 导读 本文以 crates/fivetran数据库后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考