ClickHouse 目的地

ClickHouse 是一个用于分析的数据库。Supabase Pipelines 会将 Postgres 表复制到 ClickHouse，可以是当前状态的表，也可以是仅追加的历史变更表。

将数据复制到 ClickHouse：

🌐 To replicate data to ClickHouse:

1. 选择一个表引擎 并查看 源表要求。
2. 在 ClickHouse 中准备一个数据库、用户和 HTTPS 端点。
3. 在仪表板中配置 ClickHouse 目标。
4. 在 ClickHouse 中查询复制数据。

源表要求 #

🌐 Source table requirements

源表的要求取决于选择的表引擎以及 Postgres 发布中的操作。ReplacingMergeTree 需要源主键。MergeTree 可以复制只插入的表而不需要主键。如果一个表有主键，发布中应包含它的所有键列。

🌐 The source table requirements depend on the selected table engine and the operations in the Postgres publication. ReplacingMergeTree requires a source primary key. MergeTree can replicate insert-only tables without one. If a table has a primary key, include all its key columns in the publication.

查看你的源表的副本身份和数组要求。

🌐 Check the replica-identity and array requirements for your source tables.

选择一个表引擎 #

🌐 Choose a table engine

表引擎决定 ClickHouse 如何存储和查询复制的更改。为整个目标选择一个引擎：

🌐 The table engine determines how ClickHouse stores and queries replicated changes. Choose one engine for the entire destination:

在创建流水线之前选择引擎。之后更改 表引擎 不会转换现有的目标表。如果写入的表引擎与配置的不一致，写入会失败。恢复之前的设置即可继续写入这些表。

🌐 Choose the engine before creating the pipeline. Changing Table engine later does not convert existing destination tables. Writes fail if their engine differs from the configured one. Restore the previous setting to resume writing to those tables.

使用 ReplacingMergeTree 时，修改源主键的值会从当前状态视图中移除旧键，并将该行写入其新键下。更改构成主键的列是一个单独的［模式更改］(#schema-change-support)。

🌐 With ReplacingMergeTree, changing a source primary-key value removes the old key from the current-state view and writes the row under its new key. Changing which columns make up the primary key is a separate schema change.

准备 ClickHouse 资源 #

🌐 Prepare ClickHouse resources

托管管道运行在 AWS eu-central-1（法兰克福）。创建你的 ClickHouse 服务时，选择一个附近的区域以减少复制延迟。然后在创建目标之前，在 ClickHouse 中准备好这些资源：

🌐 Managed Pipelines run in AWS eu-central-1 (Frankfurt). When creating your ClickHouse service, choose a nearby region to reduce replication latency. Then prepare these resources in ClickHouse before creating the destination:

1. 为复制表创建一个空数据库。在 ClickHouse Cloud 中，打开你的服务的 SQL 控制台 并运行 create database if not exists pipelines;，如果你想用其他名字，可以替换 pipelines。Pipelines 会创建和管理这些表，并为 ReplacingMergeTree 创建当前状态的视图。不要自己去创建或修改这些对象。
2. 为 Pipelines 创建一个专用的数据库用户，并授予其访问该数据库的权限。在 ClickHouse Cloud 中，可以在 SQL 控制台 创建此用户；组织的 用户和角色 页面管理控制台成员。数据库用户必须能够：
   • 查询 system.databases、system.tables 和 system.columns
   • 创建、修改、截断和删除表
   • 使用 ReplacingMergeTree 时创建和删除视图
   • 向托管表中插入行
3. 复制你 ClickHouse 服务器的公共 HTTPS 端点。在 ClickHouse Cloud 中，点击连接并选择HTTPS来找到它。如果你的端点需要端口，也一并包含。管道无法连接 HTTP 端点或私有及内部主机名。

对于 ReplacingMergeTree，ClickHouse 服务器必须运行 23.5 或更高版本。MergeTree 没有这个最低版本要求。

🌐 For ReplacingMergeTree, the ClickHouse server must run version 23.5 or later. MergeTree does not have this minimum-version requirement.

将 ClickHouse 配置为目标 #

🌐 Configure ClickHouse as a destination

按照 设置管道。当系统提示选择目标时，选择 ClickHouse 并输入以下设置：

🌐 Follow Set up Pipelines. When prompted to choose a destination, select ClickHouse and enter the following settings:

点击 Start pipeline 验证目标。查看费用估算，然后点击 Create and start pipeline。

🌐 Click Start pipeline to validate the destination. Review the cost estimate, then click Create and start pipeline.

查询复制的数据 #

🌐 Query replicated data

表名是如何映射的 #

🌐 How table names are mapped

Pipeline 会将每个 Postgres 的 schema 和表对映射到一个 ClickHouse 表。已有的下划线会被加倍，schema 和表名之间用一个下划线连接：

🌐 Pipelines maps each Postgres schema and table pair to one ClickHouse table. Existing underscores are doubled, and the schema and table names are joined with one underscore:

在复制到 ClickHouse 时，Postgres 的 schema 和表名不能以 _ 开头或结尾，也不能包含 " 或 ;。

🌐 Postgres schema and table names cannot start or end with _ or contain " or ; when replicating to ClickHouse.

ReplacingMergeTree#

当你需要每个源行的最新版本时，请使用生成的 __current 视图。ReplacingMergeTree 是默认引擎。管道：

🌐 Use the generated __current view when you need the latest version of each source row. ReplacingMergeTree is the default engine. Pipelines:

• 使用源主键作为 ClickHouse 的排序和去重键
• 添加一个 _etl_version UInt128 排序列
• 添加一个 _etl_deleted UInt8 墓碑列
• 创建一个 <table>__current 视图，用 FINAL 运行基础表并删除已删除的行

_etl_version 和 _etl_deleted 这些名称是保留的，不能用作源列名。

🌐 The _etl_version and _etl_deleted names are reserved and can't be used by source columns.

查询生成的视图以了解当前状态：

🌐 Query the generated view for the current state:

1
select *
2
from pipelines."public_orders__current";

ClickHouse 的后台合并会随着时间的推移合并旧的行版本。合并之前，基础表可能包含同一源行的多个版本。生成的视图使用 FINAL 返回当前版本，并排除已删除的行。

🌐 ClickHouse background merges combine older row versions over time. Before a merge, the base table can contain multiple versions of the same source row. The generated view uses FINAL to return the current version and excludes deleted rows.

管道不会运行 OPTIMIZE ... FINAL CLEANUP。ClickHouse 运算符仍然需要负责其存储保留策略所需的任何物理墓碑清理。

🌐 Pipelines does not run OPTIMIZE ... FINAL CLEANUP. ClickHouse operators remain responsible for any physical tombstone cleanup required by their storage-retention policy.

MergeTree#

当你需要插入、更新和删除的历史记录时，查询基础表。MergeTree 将每个复制的更改存储为仅追加事件。管道会添加：

🌐 Query the base table when you need the history of inserts, updates, and deletes. MergeTree stores each replicated change as an append-only event. Pipelines adds:

• cdc_operation，含有INSERT、UPDATE或DELETE
• cdc_lsn，包含该变更的 Postgres 提交 LSN
• cdc_tx_ordinal，包含该事务中变动的位置

cdc_operation、cdc_lsn 和 cdc_tx_ordinal 这些名字是保留的，不能用作源列名。

🌐 The cdc_operation, cdc_lsn, and cdc_tx_ordinal names are reserved and can't be used by source columns.

插入和更新会附加完整的新行。主键值更新也会为旧键附加 DELETE。当源使用 REPLICA IDENTITY FULL 时，删除会附加旧行。对于主键身份，删除只包含键值；其他字段使用 NULL 作为可空标量或占位符，比如零、空字符串和空数组。这些占位符不是被删除行的原始值。

🌐 Inserts and updates append the complete new row. A primary-key value update also appends a DELETE for the old key. Deletes append the old row when the source uses REPLICA IDENTITY FULL. With primary-key identity, a delete contains the key values; other fields use NULL for nullable scalars or placeholders such as zero, empty strings, and empty arrays. Those placeholders are not the deleted row's original values.

按 cdc_lsn 然后 cdc_tx_ordinal 排序源更改。旧键删除和新键更新来自同一个主键值的变化，共享两个值，所以这对不是唯一的目标行 ID。

🌐 Order source changes by cdc_lsn and then cdc_tx_ordinal. The old-key delete and new-key update from one primary-key value change share both values, so this pair is not a unique destination-row ID.

截断和表重启 #

🌐 Truncates and table restarts

一个源 TRUNCATE 会截断任一引擎的 ClickHouse 表，然后持续的复制会继续。它不会启动新的初始同步。

🌐 A source TRUNCATE truncates the ClickHouse table for either engine, then ongoing replication continues. It does not start a new initial sync.

重新启动表的复制会删除并重新创建表，对于 ReplacingMergeTree，还会重建生成的视图。表的重启会清除已累积的目标数据，并且只有当表被选中用于初始同步时，才会复制现有的源行。

🌐 Restarting replication for a table drops and recreates its table and, for ReplacingMergeTree, its generated view. A table restart erases the accumulated destination data and copies existing source rows only if the table is selected for initial sync.

副本身份和数组 #

🌐 Replica identity and arrays

REPLICA IDENTITY NOTHING 无法支持更新或删除。

对于可以忽略未改变的外部 TOAST 值更新的表，使用 REPLICA IDENTITY FULL。它让 Pipelines 可以重建完整的新行。更改副本标识只影响新的 WAL；不兼容的保留更新仍然可能需要重启表。

🌐 Use REPLICA IDENTITY FULL for tables whose updates can omit unchanged out-of-line TOAST values. It lets Pipelines reconstruct the complete new row. Changing replica identity affects only new WAL; incompatible retained updates can still require a table restart.

数组元素可以是 NULL，但顶层数组值不能。替换顶层 NULL 值并强制执行 NOT NULL，或者确保生产者总是提供一个数组。空数组是支持的。

🌐 Array elements can be NULL, but a top-level array value cannot. Replace top-level NULL values and enforce NOT NULL, or ensure producers always supply an array. Empty arrays are supported.

类型映射 #

🌐 Type mapping

管道会用这些映射创建 ClickHouse 列：

🌐 Pipelines creates ClickHouse columns with these mappings:

可空标量列被封装在 Nullable(...) 中。字符、文本、numeric、money、JSON、time、interval、二进制、位字符串、枚举以及不支持的自定义值会被序列化到 String 列，而不是作为原生 ClickHouse 类型存储。

🌐 Nullable scalar columns are wrapped in Nullable(...). Character, text, numeric, money, JSON, time, interval, binary, bit-string, enum, and unsupported custom values are serialized into String columns rather than stored as native ClickHouse types.

支持模式更改 #

🌐 Schema change support

管道支持：

🌐 Pipelines supports:

• 添加列
• 重命名或删除列；嵌套子列在重命名时必须保持在同一父列下
• 从现有的标量列中删除 NOT NULL
• 添加、修改或移除支持的列默认值
• 在已跟踪的表上添加或删除已发布的列，但需遵守相同的限制

使用 ReplacingMergeTree 时，重命名或删除主键列，或者更改主键的列或它们的顺序都会被拒绝。

🌐 With ReplacingMergeTree, renaming or dropping a primary-key column or changing the key's columns or their order is rejected.

当 ClickHouse 需要历史行的值而源默认值无法安全表示时，新标量列会被设置为可为空。添加 NOT NULL 会保持现有目标列为可为空。无法翻译的默认值会被跳过；Postgres 仍然会通过复制提供源值。

🌐 New scalar columns are made nullable when ClickHouse needs a value for historical rows and the source default cannot be represented safely. Adding NOT NULL keeps an existing destination column nullable. Defaults that cannot be translated are skipped; Postgres still supplies the source values through replication.

之前被排除的标量列在没有默认值的情况下被添加，导致历史行显示为 NULL。删除已发布的列会删除它的目的值；再次添加它不会恢复这些值。要包含之前被排除的数组列，需要选择表进行初始同步并重新启动其复制。

🌐 A previously excluded scalar column is added without a default, leaving historical rows NULL. Removing a published column drops its destination values; adding it again does not restore them. To include a previously excluded array column, select the table for initial sync and restart its replication.

有关类型更改、不支持的更改以及中断的模式更改，请参阅共享的 模式更改行为和恢复。

🌐 For type changes, unsupported changes, and interrupted schema changes, see the shared schema-change behavior and recovery.

故障排除 #

🌐 Troubleshooting

使用 pipeline 监控 检查错误，并在 联系支持 时包含 pipeline ID。

🌐 Use pipeline monitoring to inspect errors and include the pipeline ID when contacting support.

额外资源 #

🌐 Additional resources

• ClickHouse 文档
• ReplacingMergeTree
• 监控流水线状态