故障排查与最佳实践

错误消息：

Test grants failed, cause: user is missing the required grants on *.*: ALTER, CREATE DATABASE, CREATE TABLE, INSERT, SELECT

**原因：**Fivetran 用户没有所需的权限。该连接器需要在 *.* (所有数据库和表) 上拥有 ALTER、CREATE DATABASE、CREATE TABLE、INSERT 和 SELECT 授权。

解决方案：

直接向 Fivetran 用户授予所需权限：

GRANT CURRENT GRANTS ON *.* TO fivetran_user;

错误消息：

error while waiting for all mutations to be completed: ... initial cause: ...

**原因：**已提交 ALTER TABLE ... UPDATE 或 ALTER TABLE ... DELETE 变更，但连接器在等待该变更在所有副本上完成时超时。错误中的“initial cause”部分通常会包含原始的 ClickHouse 错误 (常见为代码 341，即“Unfinished”) 。

这通常发生在以下情况下：

• ClickHouse Cloud 集群负载过重。
• 在变更执行期间，一个或多个节点发生故障。

解决方案：

1. 检查变更进度：运行以下查询，检查是否存在待处理的 mutation：

   SELECT database, table, mutation_id, command, create_time, is_done
   FROM system.mutations
   WHERE NOT is_done
   ORDER BY create_time DESC;

2. 检查集群健康状态：确保所有节点都处于健康状态。
3. 等待并重试：集群恢复健康后，变更最终会完成。Fivetran 会自动重试同步。

错误信息：

如果列不匹配是由 source 中的 schema 变更引起的，可能会出现不同的错误。例如：

columns count in ClickHouse table (8) does not match the input file (6). Expected columns: id, name, ..., got: id, name, ...

或者：

column user_email was not found in the table definition. Table columns: ...; input file columns: ...

原因： ClickHouse 目标端表中的列与正在同步的数据中的列不一致。出现这种情况的原因可能是：

• 手动在 ClickHouse 表中添加或删除了列。
• 来源端的 schema 变更未正确同步过来。

解决方案：

1. 切勿手动修改由 Fivetran 管理的表。 请参见最佳实践。
2. 将列改回原来的类型：如果你知道该列应是什么类型，请参考type transformation mapping，将该列改回预期类型。
3. 重新同步该表：在 Fivetran 仪表板中，为受影响的表触发一次历史重新同步。
4. 删除并重新创建：作为最后的手段，删除目标端表，并让 Fivetran 在下一次同步时重新创建它。

错误信息：

code: 168, message: AST is too big. Maximum: 50000

或

code: 62, message: Max query size exceeded

原因： 大批量的 UPDATE 或 DELETE 批次会生成抽象语法树非常复杂的 SQL 语句。这在宽表或启用历史模式时很常见。

解决方案：

在高级配置文件中调低 mutation_batch_size 和 hard_delete_batch_size。两者的默认值均为 1500，可接受的取值范围为 200 到 1500。

错误信息：

code: 241, message: (total) memory limit exceeded: would use 14.01 GiB

原因： INSERT 操作所需内存超过可用内存。通常发生在大规模初始同步、宽表场景或并发批次操作期间。

解决方案：

1. 减小 write_batch_size：对于大表，尝试将其调低到 50,000。
2. 降低数据库负载：检查 ClickHouse Cloud 服务的负载情况，确认是否过载。
3. 扩容 ClickHouse Cloud 服务 以提供更多内存。

错误消息：

ClickHouse connection error: unexpected EOF

或者在 Fivetran 日志中出现 FAILURE_WITH_TASK，且没有堆栈跟踪信息。

原因：

• IP 访问列表未配置为允许 Fivetran 流量。
• Fivetran 与 ClickHouse Cloud 之间存在暂时性的网络问题。
• 损坏或无效的源数据导致目标端连接器崩溃。

解决方案：

1. 检查 IP 访问列表：在 ClickHouse Cloud 中，前往 Settings > Security，添加 Fivetran IP addresses，或允许来自任意位置的访问。
2. 重试：较新的连接器版本会自动重试 EOF 错误。零星出现的错误 (每天 1–2 次) 很可能只是暂时性问题。
3. 如果问题仍然存在：向 ClickHouse 提交支持工单，并提供错误发生的时间范围。同时请 Fivetran 支持团队协助调查源数据质量问题。

错误信息：

cause: can't map type UInt64 to Fivetran types

原因： 该 连接器 会将 LONG 映射为 Int64，不会映射为 UInt64。当在由 Fivetran 管理的表中手动修改列类型时，就会出现此错误。

解决方案：

1. 不要在 Fivetran 管理的表中手动修改列类型。
2. 如需恢复：将该列改回预期的类型 (例如 Int64) ，或者删除该表并重新同步。
3. 对于自定义类型：可在由 Fivetran 管理的表上创建 materialized view。

错误信息：

Failed to alter table ... cause: no primary keys for table

原因： 每个 ClickHouse 表都必须指定 ORDER BY。当源端没有主键时，Fivetran 会自动添加 _fivetran_id。如果源端定义了 PK，但数据中并不包含该 PK，就可能在某些边缘情况下触发此错误。

解决方案：

1. 联系 Fivetran 支持团队，排查源管道。
2. 检查源 schema：确保数据中包含主键列。

错误信息：

user is missing the required grants on *.*: ALTER, CREATE DATABASE, CREATE TABLE, INSERT, SELECT

原因： 该连接器使用以下语句检查授权：

SELECT access_type, database, table, column FROM system.grants WHERE user_name = 'my_user'

这只会返回直接授权。通过 ClickHouse 角色分配的权限会显示为 user_name = NULL 和 role_name = 'my_role'，因此此检查无法识别这些权限。

解决方案：

直接向 Fivetran 用户授予权限：

GRANT CURRENT GRANTS ON *.* TO fivetran_user;

在摄取负载较高时，建议使用 ClickHouse Cloud 的计算-计算分离，为 Fivetran 写入工作负载创建专用服务。这样可将摄取与分析查询隔离开来，避免资源争用。

例如，可采用以下架构：

• 服务 A (写入端) ：Fivetran 目标端 + 其他摄取工具 (ClickPipes、Kafka 连接器)
• 服务 B (读取端) ：BI 工具、仪表盘、临时查询

ClickHouse 对 Fivetran 目标端表使用 SharedReplacingMergeTree，它是 ClickHouse Cloud 中 ReplacingMergeTree 表引擎 的一个版本。具有相同主键的重复行属于正常现象——去重会在后台合并过程中异步进行。读取时，你需要注意避免返回重复行，因为有些行可能尚未完成去重。

使用 FINAL 关键字是避免重复行的最简单方法，因为它会在读取时强制合并所有尚未去重的行：

SELECT * FROM schema.table FINAL WHERE ...

有一些方法可以优化这个 FINAL 操作——例如，通过 WHERE 条件对键列进行过滤。更多详情，请参阅 ReplacingMergeTree 指南中的 FINAL performance 部分。

如果这些优化还不够，你还有其他方法可以在不使用 FINAL 的情况下正确处理重复项：

• 如果你想查询一个持续递增的数值列，可以使用 max(the_column)。
• 如果你需要为某个特定键获取某些列的最新值，可以使用 argMax(the_column, _fivetran_id)。

Fivetran 会将源表的主键复制为 ClickHouse 的 ORDER BY 子句。当源表没有主键时，_fivetran_id (一个 UUID) 会成为排序键。由于 ClickHouse 会基于 ORDER BY 列构建其稀疏主索引，这可能会导致查询性能较差。

如果其他优化手段仍无法满足需求，建议采取以下做法：

1. 将 Fivetran 表视为原始暂存表。 不要直接对其进行分析查询。
2. 如果查询性能仍然不够理想，可使用可刷新materialized view创建该表的副本，并根据你的查询模式优化其 ORDER BY。与增量materialized view不同，可刷新materialized view会按计划重新运行完整查询，因此能够正确处理 Fivetran 在同步期间发出的 UPDATE 和 DELETE 操作：

   CREATE MATERIALIZED VIEW schema.table_optimized
   REFRESH EVERY 1 HOUR
   ENGINE = ReplacingMergeTree()
   ORDER BY (user_id, event_date)
   AS SELECT * FROM schema.table_raw FINAL;

避免对由 Fivetran 管理的表手动执行 DDL 更改 (例如 ALTER TABLE ... MODIFY COLUMN) 。连接器 依赖其创建的 schema。手动更改可能会导致type mapping 错误以及 schema 不匹配问题。

使用 materialized views 进行自定义转换。

排查故障时：

• 检查 ClickHouse system.query_log，查看服务端是否存在问题。
• 如属客户端问题，请向 Fivetran 寻求帮助。

如果是 连接器 的缺陷，请创建 GitHub issue或联系 ClickHouse 支持团队。

使用以下查询来诊断 ClickHouse 侧的同步失败问题。

SELECT event_time, query, exception_code, exception
FROM system.query_log
WHERE client_name LIKE 'fivetran-destination%'
  AND exception_code > 0
ORDER BY event_time DESC
LIMIT 50;

SELECT event_time, query_kind, query, exception_code, exception
FROM system.query_log
WHERE user = '{fivetran_user}'
ORDER BY event_time DESC
LIMIT 100;