Fivetran 官方 Connector SDK 本地链路

角色与安装

参考官方 Connector SDK 2.12.1、本地 tester 2.26.0908.001。验证路径为 MatrixOne/MySQL 源 → SDK 操作 → 本地 tester/DuckDB 目标;不是 Fivetran 托管服务认证,也不是 Fivetran 官方 MatrixOne destination。用户本轮选择了 SDK 本地链路。

安装 fivetran-connector-sdk pymysql,完成共用连接,在专用目录保存 mo_common.py。只在独立测试目录启用下面的故障注入;SDK 的本地 files/state 和 warehouse 都应保留。

Connector 与精确载荷

保存为 connector.py。主键 id 与金额、二进制、标签一起编码为明确的 STRING payload;id 在 SDK LONG 的有符号范围内。金额使用字符串、二进制使用 hex。此精确封装不代表默认推断能无损处理任意大数。

此最小示例依赖固定的两行样例,无并发源变更。首次运行在第二行 upsert 后、checkpoint 前故意失败;标记文件只让它发生一次。下一进程从上一个 checkpoint 重放,用同一业务键 upsert。

import json
from pathlib import Path
from fivetran_connector_sdk import Connector, Operations as op
from mo_common import connect

def schema(configuration):
    return [{"table":"matrixone_rows","primary_key":["id"],
             "columns":{"id":"LONG","payload":"STRING"}}]

def update(configuration, state):
    last = int(state.get("last_id", -1))
    with connect() as d:
        with d.cursor() as c:
            c.execute("SELECT id,CAST(amount AS CHAR),HEX(payload),label,rev FROM lake_demo "
                      "WHERE id IN (2,9007199254740993) AND id>%s ORDER BY id", (last,))
            rows = c.fetchall()
    for index, row in enumerate(rows):
        payload = json.dumps({"amount_text":row[1],"payload_hex":row[2],
                              "label":row[3],"rev":row[4]},ensure_ascii=False,separators=(",",":"))
        op.upsert(table="matrixone_rows",data={"id":row[0],"payload":payload})
        marker = Path("injected-once")
        if configuration.get("inject_once") == "true" and index == 1 and not marker.exists():
            marker.write_text("uncheckpointed upsert")
            raise RuntimeError("Deliberate failure before checkpoint")
        op.checkpoint(state={"last_id":row[0]})

connector = Connector(update=update,schema=schema)
{"inject_once":"true"}

新进程恢复与操作签名

把上面的 JSON 保存为 configuration.json,分别运行以下两次 CLI(第二次是新进程)。检查本地 files/state.json、tester 输出与 warehouse:重放后业务键不应重复,payload 完整,最后 last_id 为9007199254740993。首次预期失败,不要把首次退出码忽略后直接宣称通过。

fivetran debug --configuration configuration.json
# Expected injected failure; start a new process for resume:
fivetran debug --configuration configuration.json

更新/删除 API 不能沿用 upsert 的参数名。下面是可用于增量事件的操作片段,不要无条件插到上述重放循环中:

op.update(table="matrixone_rows",modified={"id":2,"payload":"updated"})
op.delete(table="matrixone_rows",keys={"id":2})
op.checkpoint(state={"event_seq":10})

删除、模式和恢复边界

本样例 id 游标只是静态读取教学,不能捕捉旧行 UPDATE/DELETE,不能用于有并发提交/迟到记录的生产增量同步。生产应使用经验证的 CDC 或事务 outbox,游标基于事件序列并有完整提交/保留语义;删除携带主键,更新携带版本,checkpoint 对应已处理的事件水位。

新增源列后同步 SDK schema/精确 envelope,再核对旧 state 恢复是否兼容。SDK debug 的全局操作流在同进程反复 debug 曾产生复用问题,本教程用新 CLI 进程。只有本地恢复与幂等效果验证,不声称 SaaS、跨目标数据库原子提交或生产吞吐。