管道常见问题

支持哪些目的地？ #

🌐 What destinations are supported?

Pipelines 目前支持 BigQuery 作为托管目标。有关配置详情，请参阅 BigQuery 目标指南。

🌐 Pipelines currently supports BigQuery as the managed destination. See the BigQuery destination guide for configuration details.

你可以申请提前访问 ClickHouse、Snowflake 和 DuckLake。支持的目标可以是 Supabase 管理的系统，也可以是随着支持扩展的第三方系统。

🌐 You can request early access to ClickHouse, Snowflake, and DuckLake. Supported destinations can be Supabase-managed or third-party systems as support expands.

目的地的区域会影响性能吗？ #

🌐 Does the destination's region affect performance?

是的。你的源数据库、数据管道和目标之间距离越远，复制时的网络延迟就越大，这会增加复制延迟并降低吞吐量。

🌐 Yes. The further apart your source database, the pipeline, and your destination are, the more network latency is added to replication, which increases replication lag and reduces throughput.

托管的管道运行在 AWS eu-central-1（法兰克福）。为了获得最佳性能，请将你的源项目和目标尽可能靠近法兰克福。当配置像 BigQuery 这样的目标提供商时，选择它可用的最近区域。

🌐 Managed Pipelines run in AWS eu-central-1 (Frankfurt). For the best performance, place both your source project and destination as close to Frankfurt as possible. When configuring a destination provider such as BigQuery, choose its closest available region.

如果你只能优化一方面，优先将你的目标位置靠近管道所在的区域。复制的数据会不断传输到目标位置，所以这一段的延迟对整体复制延时的影响比管道和源之间的延迟更大。

🌐 If you can only optimize one side, prioritize placing your destination close to the pipeline's region. Replicated data continuously streams out to the destination, so latency on that leg has a bigger impact on overall replication lag than latency between the pipeline and the source.

哪些计划支持Pipelines？ #

🌐 Which plans support Pipelines?

流水线需要 Pro、团队或企业计划。在公开测试阶段，访问权限会逐步开放，所以即使有符合条件的计划，也不保证每个组织都已启用流水线。如果不可用，可以在 数据库 > 复制 页面申请访问，或联系你的客户经理。

🌐 Pipelines requires a Pro, Team, or Enterprise plan. During public alpha, access is being rolled out gradually, so an eligible plan does not guarantee that Pipelines is enabled for every organization yet. If it is not available, request access from the Database > Replication page or contact your account manager.

Analytics Buckets 的复制发生了什么事？ #

🌐 What happened to Analytics Buckets replication?

我们目前正在开发一个新的 Supabase Warehouse 产品，旨在解决之前 Analytics Buckets 的局限性。我们的目标是打造一个我们可以放心支持的解决方案，而不是继续支持一种无法满足我们希望为用户提供的质量和灵活性的方式。

🌐 We are currently working on a new Supabase Warehouse product designed to address the limitations of the previous Analytics Buckets. Our goal is to build a solution we can confidently stand behind, rather than continuing to support an approach that does not meet the quality and flexibility we want for our users.

因此，通过管道复制到分析桶已不再受支持。目前，BigQuery 是唯一受支持的托管目标，我们也在积极努力扩大功能。

🌐 As a result, replication into Analytics Buckets via Pipelines is no longer supported. Right now, BigQuery is the only supported managed destination, and we are actively working on expanding capabilities.

Pipelines 在数据库里安装什么？ #

🌐 What does Pipelines install in the database?

当你启用 Pipelines 时，Supabase 会安装一些数据库对象，用来跟踪复制状态并支持模式更改：

🌐 When you enable Pipelines, Supabase installs database objects that help track replication state and support schema changes:

• 一个在每个 ALTER TABLE 语句上运行的事件触发器。Supabase 使用它来支持模式更改处理。
• etl 架构中的一组表。这些表用于跟踪你管道的复制状态。

复制状态表更新得不太频繁，尤其是在初始同步完成之后。

🌐 The replication state tables are not updated very often, especially after the initial sync is complete.

支持哪些模式更改？ #

🌐 What schema changes are supported?

模式更改支持目前处于测试阶段，并且仅限于 BigQuery 目标。

🌐 Schema change support is currently in beta and limited to the BigQuery destination.

支持的模式更改：

🌐 Supported schema changes:

• 添加一个标量顶层列（在 BigQuery 中创建为 NULLABLE）
• 删除一列
• 重命名列
• 删除 NOT NULL 约束
• 设置或取消支持的列默认元数据

最初创建 BigQuery 表时，会保留每个标量的、非数组的 Postgres 列是否允许 NULL。数组使用 BigQuery 的 REPEATED 模式。对于后续更改，DROP NOT NULL 会将 BigQuery 的 REQUIRED 列放宽为 NULLABLE，而 SET NOT NULL 会保持现有的 BigQuery 列可空，并记录一个警告。新添加的标量顶层列在 BigQuery 中总是可空的。支持的默认值会作为目标元数据单独应用，而不会填充现有的目标行。Pipelines 目前不支持更改列的数据类型。详情请参阅 BigQuery schema change support。

🌐 Initial BigQuery table creation preserves whether each scalar, non-array Postgres column allows NULL. Arrays use BigQuery's REPEATED mode. For later changes, DROP NOT NULL relaxes a BigQuery REQUIRED column to NULLABLE, while SET NOT NULL leaves an existing BigQuery column nullable and logs a warning. Newly added scalar, top-level columns are always nullable in BigQuery. Supported defaults are applied separately as destination metadata and do not populate existing destination rows. Pipelines does not currently support changing column data types. See BigQuery schema change support for details.

禁用管道会发生什么？ #

🌐 What happens when you disable Pipelines?

禁用管道会移除安装在源数据库中的数据库对象，包括 etl 架构中的复制状态表和 DDL 事件触发器。

🌐 Disabling Pipelines removes the database objects that were installed in your source database, including the replication state tables in the etl schema and the DDL event trigger.

要从项目中移除管道，首先删除所有管道目标。删除所有目标后，“禁用”操作才会可用。有关仪表板步骤，请参见 禁用管道。

🌐 To remove Pipelines from a project, delete all Pipelines destinations first. After all destinations are deleted, the disable action becomes available. For the Dashboard steps, see Disabling Pipelines.

禁用管道会停止 Supabase 对项目的复制管理，但不会删除已经写入目标的表或数据。

🌐 Disabling Pipelines stops Supabase from managing replication for the project. It does not delete tables or data that were already written to your destination.

为什么这张表没有被复制？ #

🌐 Why is a table not being replicated?

常见原因：

🌐 Common reasons:

• 缺少主键：BigQuery要求每个源表都有主键，并要求发布时包含其列。这是BigQuery管道的要求，而不是发布Postgres插入的一般要求。
• 未在发布中：确保该表包含在你的 Postgres 发布中
• 生成列：在复制过程中会跳过生成列

检查你的发布设置，并确认你的表格符合要求。

🌐 Check your publication settings and verify your table meets the requirements.

自定义数据类型会作为字符串复制。确认你的目标可以正确解析这些字符串值。

🌐 Custom data types replicate as strings. Check that your destination can interpret those string values correctly.

为什么分区表会被作为独立的表来复制？ #

🌐 Why are partitioned tables replicated as separate tables?

Postgres 通过发布的 publish_via_partition_root 设置来控制这一点。如果设置是 false，或者你用 SQL 手动创建发布但没有设置它，Postgres 会发布来自叶子分区的更改。然后管道会为这些叶子分区创建目标表。如果是 publish_via_partition_root = true，Postgres 会以分区根的方式发布更改，因此分区层次结构会被视为已发布的分区根。

🌐 Postgres controls this with the publication's publish_via_partition_root setting. If the setting is false, or if you created the publication manually with SQL and did not set it, Postgres publishes changes from the leaf partitions. Pipelines then creates destination tables for those leaf partitions. If publish_via_partition_root = true, Postgres publishes changes as the partition root, so the partition hierarchy is treated as the published partition root.

从仪表板复制流程创建的发布使用 publish_via_partition_root = true。

🌐 Publications created from the Dashboard replication flow use publish_via_partition_root = true.

查看 分区表 了解示例和完整行为。

🌐 See Partitioned tables for examples and the full behavior.

副本身份如何影响更新和删除？ #

🌐 How does replica identity affect updates and deletes?

如果插入操作能复制，但更新或删除失败，源表可能没有通过 Postgres 逻辑复制发送足够的旧行身份信息。

🌐 If inserts replicate but updates or deletes fail, the source table might not be sending enough old-row identity through Postgres logical replication.

发送到 BigQuery 的每个表都必须有主键，每个主键列都必须包含在发布中。对于更新和删除操作，使用主键副本标识或 REPLICA IDENTITY FULL。对于 text、jsonb、bytea 或其他 Postgres 可以离线存储的较大值的表，也推荐使用完整副本标识。

🌐 Every table sent to BigQuery must have a primary key, and every primary-key column must be included in the publication. For updates and deletes, use the primary key replica identity or REPLICA IDENTITY FULL. Full replica identity is also recommended for tables with large text, jsonb, bytea, or other values that Postgres can store out of line.

1
alter table public.your_table replica identity full;

完整复制身份会增加 WAL 的体积，并且只影响新的 WAL 记录。在生成更多更改之前，请先修复该设置。如果失败的更新已保存在 WAL 中，重启可能会再次失败；请重新创建管道或重启受影响表的初始同步。具体详情请参阅 BigQuery 源表要求。

🌐 Full replica identity increases WAL volume and only affects new WAL records. Fix the setting before generating more changes. If the failing update is already retained in WAL, restarting may fail again; recreate the pipeline or restart the affected table's initial sync. See BigQuery source table requirements for details.

为什么在添加或删除表格后，发布物的更改没有反映出来？ #

🌐 Why aren't publication changes reflected after adding or removing tables?

在修改你的 Postgres 发布后，你必须重启复制管道才能使更改生效。参考添加或删除表获取操作说明。

🌐 After modifying your Postgres publication, you must restart the replication pipeline for changes to take effect. See Adding or removing tables for instructions.

为什么管道处于失败状态？ #

🌐 Why is a pipeline in failed state?

当管道在启动或持续复制过程中遇到不可重试的管道级错误时，它会进入 失败 状态。管道不会静默跳过错误，而是会停止。要恢复：

🌐 A pipeline enters Failed when it encounters a non-retryable pipeline-level error during startup or ongoing replication. The pipeline stops instead of silently skipping the failure. To recover:

1. 将鼠标悬停在失败状态上查看错误信息
2. 点击 查看管道 获取详细信息
3. 修复根本问题（例如，模式不匹配、目标连接问题）
4. 重启管道

详情请参见 处理错误。

🌐 See Handling errors for more details.

为什么管道停了？ #

🌐 Why was the pipeline stopped?

当你选择 停止流水线、项目变为非活动状态，或操作需要其重启时，流水线会被停止。不可重试的配置、模式或数据错误会将流水线置为 失败 状态。临时连接和目标错误则会在可能时自动重试。

🌐 A pipeline is stopped when you select Stop pipeline, when its project becomes inactive, or while an operation requires it to restart. A non-retryable configuration, schema, or data error can instead put the pipeline in Failed state. Transient connection and destination errors retry automatically when possible.

恢复:

🌐 To recover:

1. 检查一下管道是已停止、正在停止还是失败
2. 如果失败了，查看错误详情和复制日志
3. 解决根本问题，比如目标连接、模式不匹配、权限或速率限制
4. 从 数据库 > 复制 启动或重启管道

如果重启后同样的错误仍然出现，管道可能会再次停止。查看 监控管道状态 获取故障排除步骤。

🌐 If the same error continues after restart, the pipeline may stop again. Review Monitor pipeline status for troubleshooting steps.

为什么复制延迟在增加？ #

🌐 Why is replication lag increasing?

当 Postgres 生成 WAL 比管道确认已处理它的速度快时，延迟就会增加。常见原因包括目标端慢或速率受限、管道问题、源数据库活动繁忙、长事务、管道和源数据库之间的网络延迟，或管道已停止/断开连接。

🌐 Lag increases when Postgres produces WAL faster than the pipeline can confirm it has processed. Common causes include a slow or rate-limited destination, a pipeline issue, heavy source database activity, long transactions, network latency between the pipeline and source database, or a stopped/disconnected pipeline.

打开 数据库 > 复制，点击 查看管道，并检查 等待同步、剩余 WAL 保留、上次签到、已连接 和 插槽状态。完整的调查和响应流程请参见 处理复制延迟。

🌐 Open Database > Replication, click View pipeline, and check Waiting to sync, WAL retention remaining, Last check-in, Connected, and Slot status. See Dealing with replication lag for the full investigation and response flow.

Lost#

🌐 What does a Lost slot status mean?

Lost 意味着 Postgres 已经删除了管道复制槽需要的 WAL 文件。管道无法从该槽继续。

你可以重新创建这个流水线，或者打开流水线的高级设置，把失效槽位行为设置为重新创建，然后再次启动流水线。流水线会重置保存的表同步状态，创建一个新的复制槽，并通过新的初始同步替换每个目标表。为了保持一致性，这种破坏性重启是必须的，因为旧的槽位无法提供流水线遗漏的所有变更，而且在新初始同步期间处理的数据会再次计费。

🌐 You can recreate the pipeline, or open the pipeline's Advanced settings, set Invalidated slot behavior to Recreate, and start the pipeline again. The pipeline resets its saved table-sync state, creates a new replication slot, and replaces each destination table through a new initial sync. This destructive restart is required for consistency because the old slot can no longer provide every change the pipeline missed, and the data processed during the new initial sync is billed again.

查看 插槽状态 了解所有插槽状态及下一步操作。

🌐 See Slot statuses for all slot states and what to do next.

为什么表格会处于错误状态？ #

🌐 Why is a table in error state?

在初始同步期间会出现表错误。要恢复，请点击 查看管道，找到受影响的表，然后点击它的重启操作。这会从头重新启动该表的初始同步，删除它现有的目标数据，并再次计费成功处理的行数据。

🌐 Table errors occur during the initial sync. To recover, click View pipeline, find the affected table, and click its restart action. This restarts that table's initial sync from the beginning, deletes its existing destination data, and bills the successfully processed row data again.

如何确认复制是否正常工作 #

🌐 How to verify replication is working

查看仪表板的 数据库 > 复制 部分：

🌐 Check the Database > Replication section of the Dashboard:

1. 确认你的流水线显示为运行中状态
2. 点击 查看管道 查看表状态
3. 确保所有表格显示 实时 状态（正在主动复制）
4. 监控复制延迟指标

查看 监控管道状态 获取全面的监控说明。

🌐 See Monitor pipeline status for comprehensive monitoring instructions.

如何停止复制 #

🌐 How to stop replication

你可以通过目标列表中的操作菜单来管理你的管道。有关可用操作的详细信息，请参见管理你的管道。

🌐 You can manage your pipeline using the actions menu in the destinations list. See Managing your pipeline for details on available actions.

如果一个项目变得不活跃，会发生什么？ #

🌐 What happens if a project becomes inactive?

如果你的项目变得不活跃，Pipelines 会停止任何正在运行的流水线，并且在项目重新启动后不会自动恢复它们。

🌐 If your project becomes inactive, Pipelines stops any running pipelines and does not automatically resume them after the project is restarted.

在重新启动项目后，请从仪表板的 数据库 > 复制 部分手动重新启动每个复制管道。

🌐 After restarting the project, restart each replication pipeline manually from the Database > Replication section of the Dashboard.

降级到免费方案之后会发生什么？ #

🌐 What happens after a downgrade to the free plan?

当一个项目降级到免费计划时，为该项目使用 Pipelines 创建的所有复制管道都会被删除。

🌐 When a project is downgraded to the Free Plan, all replication pipelines created with Pipelines for that project are deleted.

如果目标处的表被删除会发生什么？ #

🌐 What happens if a table is deleted at the destination?

不要删除或修改由 Pipelines 管理的表或视图。对于 BigQuery，删除受管理的对象可能会停止复制，并且可能需要重新进行一次收费的初始同步。Pipelines 不保证会自动修复或完全重新同步被手动删除的目标对象。

🌐 Don't delete or modify tables or views managed by Pipelines. For BigQuery, deleting a managed object can stop replication and may require a new, billable initial sync. Pipelines does not guarantee that it will automatically repair or fully resynchronize a destination object that was removed manually.

要从你的目的地永久删除表，你有两个选择：

选项 1：永久结束复制

1. 删除目标以永久结束复制和流水线小时计费。仅停止流水线并不会结束流水线小时计费。
2. 删除你目的地的表格
3. 在表格仍在发布中时不要重新启动管道

选项2：先从发布物中移除

1. 用 ALTER PUBLICATION ... DROP TABLE 从你的 Postgres 发布中移除表
2. 重启你的复制管道以应用更改（目标表会保留，但不会接收新的更改）
3. 删除你目的地的表格

数据可以被处理不止一次吗？ #

🌐 Can data be processed more than once?

是的。Pipelines 使用至少一次处理。Pipelines 重试的失败目标写入尝试不计入。只有在目标确认成功处理后，数据才会被计入。

🌐 Yes. Pipelines uses at-least-once processing. Failed destination write attempts that Pipelines retries are not counted. Data is counted only after the destination acknowledges successful processing.

在极少数情况下，Pipelines 可能会统计一个已确认的批次，但在其复制检查点持久化之前崩溃或被中断。恢复过程可能会再次处理并统计相同的数据。

🌐 In rare cases, Pipelines can count an acknowledged batch but crash or be interrupted before its replication checkpoint is persisted. Recovery can then process and count the same data again.

BigQuery 使用复制的源主键和 CDC 排序元数据来汇总当前的表状态。Pipelines 并不提供可查询的每次交付尝试的历史记录，也不能保证事件处理的准确一次。

🌐 BigQuery uses the replicated source primary key and CDC ordering metadata to converge on the current table state. Pipelines does not provide a history of each delivery attempt that you can query or guarantee exactly-once event processing.

在哪里可以找到复制日志 #

🌐 Where to find replication logs

导航到仪表板的 日志 > 复制 部分查看所有管道日志。日志包含诊断信息。如果你遇到问题，请将错误详情联系支持团队。

🌐 Navigate to the Logs > Replication section of the Dashboard to see all pipeline logs. Logs contain diagnostic information. If you're experiencing issues, contact support with your error details.

如何获得帮助 #

🌐 How to get help

如果你需要帮助：

🌐 If you need assistance:

1. 查看 设置管道 和 监控管道状态
2. 查看这个常见问题解答了解常见问题
3. 把你的错误详情和日志发给客服