设置管道

Supabase Pipelines 会将 Postgres 数据复制到你在仪表板中配置的目标。Supabase 使用开源的 Supabase ETL 运行这个管道。

🌐 Supabase Pipelines replicates Postgres data to a destination you configure in the Dashboard. Supabase runs the pipeline using the open-source Supabase ETL.

初始同步 会复制所选表中的现有行。持续复制 使用变更数据捕获（CDC）来应用后续的插入、更新、删除和清空操作。

创建一个管道，然后根据需要参考设置、管理或高级发布选项。

在你开始之前 #

🌐 Before you start

查看计划和访问要求以及支持的目的地。

🌐 Check the plan and access requirements and check supported destinations.

区域 #

🌐 Region

托管管道在 AWS eu-central-1（法兰克福）运行，独立于你的源和目标区域。该区域是固定的。选择附近的目标资源可以减少延迟和复制延迟。

🌐 Managed Pipelines run in AWS eu-central-1 (Frankfurt), independently of your source and destination regions. This region is fixed. Choose nearby destination resources to reduce latency and replication lag.

价格 #

🌐 Pricing

Pipelines 会根据配置的流水线小时数、初始同步数据和持续复制数据收费。目标提供商的费用是单独计算的。请参见 费率、估算和计费示例。

🌐 Pipelines charges for configured pipeline hours, initial sync data, and ongoing replication data. Destination-provider charges are separate. See rates, estimates, and billing examples.

设置概览 #

🌐 Setup overview

准备好你的目的地，然后在仪表板中启用并配置流水线。Postgres 发布会选择要复制的数据；你可以在设置时创建一个。

🌐 Prepare your destination, then enable and configure Pipelines in the Dashboard. A Postgres publication selects the data to replicate; you can create one during setup.

步骤 1：准备你的目的地 #

🌐 Step 1: Prepare your destination [#step-1-create-a-postgres-publication]

按照你的目标指南准备其资源和凭证，并检查其源表要求：

🌐 Follow your destination guide to prepare its resources and credentials, and check its source table requirements:

• BigQuery
• ClickHouse
• 鸭湖
• 雪花

步骤 2：启用管道 #

🌐 Step 2: Enable Pipelines

1. 导航到仪表板的 数据库 > 流水线 部分
2. 点击 添加管道 显示复制侧面板
3. 选择一个对你的组织可用的目的地
4. 如果还没有启用管道，请点击 启用管道，查看对话框，然后确认 启用管道。

步骤 3：设置目标 #

🌐 Step 3: Configure a destination

1. 输入一个名称并选择一个发布。可以使用已有的发布，或点击新建发布，为其命名，并至少选择一个表。对于全模式复制或高级选项，用 SQL 创建发布。
2. 在初始同步下，保持所有表以复制现有行，或者如果你只需要某些表的未来变更，可选择要复制的表。
3. 输入在步骤1中准备的凭据和目标特定设置。
4. 可以选择展开高级设置来更改批处理、初始同步并发或时隙恢复。
5. 点击 创建并启动管道。修复所有 必填 问题。对于 警告，查看风险，点击 仍然创建并启动管道，并确认你要继续。
6. 查看预估的初始同步费用和持续费用，然后确认创建。

这个管道会复制所选表的现有行，并开始对每个已发布的表进行持续复制。

🌐 The pipeline copies the selected tables' existing rows and begins ongoing replication for every published table.

步骤4：监控你的流程 #

🌐 Step 4: Monitor your pipeline

打开管道，检查表是否进展到 Live，并且复制延迟是否赶上。查看 管道状态、指标和日志 来评估进展并诊断问题。

🌐 Open the pipeline and check that tables progress to Live and replication lag catches up. See pipeline states, metrics, and logs to assess progress and diagnose problems.

管道设置 #

🌐 Pipeline settings

在调整高级设置之前，先查看初始同步选项和创建检查。

🌐 Review initial sync choices and creation checks before tuning advanced settings.

选择要复制的表 #

🌐 Choosing which tables to copy

初始同步 控制哪些发布表会复制它们已有的行。持续复制则包括来自每个已发布表的新更改。

选择更改会影响未完成的初始同步。要再次复制已完成的表，请在此处包含它，应用设置，然后重新启动其复制。

🌐 Selection changes affect unfinished initial syncs. To copy a completed table again, include it here, apply the settings, and restart its replication.

跳过初始同步不会保留或附加到之前加载的目标数据。即使跳过初始同步，表重启也会清除目标数据。

🌐 Skipping initial sync does not preserve or attach to previously loaded destination data. A table restart erases destination data even when initial sync is skipped.

创建检查 #

🌐 Creation checks

仪表板会检查源的访问权限、逻辑复制设置和容量、发布内容、目标连接以及目标表的要求。发布内容必须至少包含一张表，并且不能包含内部的 etl 模式。FOR ALL TABLES 会被拒绝。

🌐 The Dashboard checks source access, logical replication settings and capacity, the publication, destination connectivity, and destination table requirements. Publications must contain at least one table and exclude the internal etl schema. FOR ALL TABLES is rejected.

一个警告可以建议增加 max_slot_wal_keep_size，以便 Postgres 在初始同步期间保留更改。更高的保留会占用更多的源存储；在应用该建议之前请检查可用磁盘空间。请参阅 WAL 配置 和 监控。

🌐 A warning can recommend increasing max_slot_wal_keep_size so Postgres retains changes during initial sync. Higher retention uses more source storage; check available disk before applying the recommendation. See WAL configuration and monitoring.

高级设置 #

🌐 Advanced settings

除非你需要调整延迟、初始同步速度或恢复行为，否则保持这些设置默认即可。

🌐 Leave these settings at their defaults unless you need to tune latency, initial sync speed, or recovery behavior.

较低的批处理等待时间可以减少批处理延迟；较高的数值可以提高写入效率。有关并发权衡，请参见 初始同步和表同步槽。

🌐 Lower batch wait times reduce batching delay; higher values can improve write efficiency. For concurrency tradeoffs, see Initial sync and table-sync slots.

重新创建槽会替换每个目标表，包括最初同步时被排除的表。启用前请查看 lost-slot recovery。

管理你的流程 #

🌐 Managing your pipeline

在管道行上使用三点操作菜单：

🌐 Use the three-dot actions menu on a pipeline row:

• 启动管道：开始已停止管道的复制
• 有更新：当有更新可用时，查看并应用最新的托管管道版本
• 停止管道：完成正在进行的工作然后停止。关闭可能需要几分钟。WAL 会累积，停止时管道小时计费仍然继续。
• 重启管道：使用保存的设置和复制进度重启。在添加或删除发布表后需要执行此操作。在初始同步期间重启前，请先查看下面的恢复行为。
• 编辑管道：修改凭据、初始同步选择或高级选项等设置。对于正在运行的管道，点击 应用并重启管道；对于已停止的管道，点击 应用并启动管道。
• 删除管道：删除管道并停止复制。已复制的数据仍然保留在目标位置。

在仪表板查看发布内容 #

🌐 Viewing publications in the Dashboard

在 数据库 > 发布物 查看发布物及其表格。

🌐 View publications and their tables in Database > Publications.

添加或删除表格 #

🌐 Adding or removing tables

这些例子使用了 SQL 示例 中的 pub_users_orders 发布物。请替换它和表名为你自己的；表必须已经存在。

🌐 These examples use the pub_users_orders publication from the SQL example. Replace it and the table names with your own; tables must already exist.

向复制中添加表 #

🌐 Adding tables to replication

1. 使用 SQL 将现有源表添加到你的显式表列表发布中：

   1
   alter publication pub_users_orders
   2
   add table products, categories;

2. 查看已添加表的初始同步选择，然后从数据管道的操作菜单中选择重新启动管道。

从复制中移除表 #

🌐 Removing tables from replication

1. 使用 SQL 从你的 Postgres 发布中移除表：

   1
   alter publication pub_users_orders
   2
   drop table orders, products;

2. 从管道的操作菜单中选择重新启动管道。

重启后，Pipelines 会移除这些表的复制状态。源表和目标表，包括已经复制的数据，都不会改变。其他使用仍包含这些表的发布的管道不会受到影响。如果多个管道使用了被修改的发布，需要重启每一个管道。

🌐 After the restart, Pipelines removes its replication state for those tables. Source tables and destination tables, including data already replicated, remain unchanged. Other pipelines using publications that still include the tables are unaffected. If multiple pipelines use the changed publication, restart each one.

重启后，你可以自己删除目标表。不要修改或删除仍由管道管理的表；这样做可能会停止复制，并需要重启表。

🌐 You can delete the destination tables yourself after the restart. Don't modify or delete tables still managed by Pipelines; doing so can stop replication and require a table restart.

管道重启和恢复 #

🌐 Pipeline restarts and recovery

管道重启不会请求每个表的全新副本。已经完成初始同步的表会从保存的进度继续。被中断的初始同步可以重新从头开始：管道会删除部分目标数据，并根据初始同步的选择重新复制表。当另一个表的重启暂时停止管道时，这种情况也可能发生在未完成的表上。

🌐 A pipeline restart does not request a fresh copy of every table. Tables that completed initial sync resume from saved progress. An interrupted initial sync can start again from scratch: Pipelines deletes the partial destination data and copies the table again according to the Initial sync selection. This can also happen to an unfinished table when another table's restart temporarily stops the pipeline.

如果主复制槽丢失并且启用了 Recreate slot，启动时会重建所有复制的表。查看 lost-slot recovery 了解其数据丢失和计费影响。要有意重建特定表，请使用 Restarting tables。

🌐 If the main replication slot is lost and Recreate slot is enabled, startup rebuilds all replicated tables. Review lost-slot recovery for its data-loss and billing effects. To deliberately rebuild specific tables, use Restarting tables.

禁用管道 #

🌐 Disabling Pipelines

先删除所有管道。然后在管道页面打开三点操作菜单，点击禁用管道。

🌐 Delete all pipelines first. Then open the three-dot actions menu on the Pipelines page and click Disable Pipelines.

有关清理详情，请参阅 禁用管道会发生什么？。

🌐 For cleanup details, see What happens when you disable Pipelines?.

用 SQL 创建发布物 #

🌐 Creating a publication with SQL

以下 SQL 示例假设你的数据库中有 users 和 orders 表，并且包含所引用的列。涉及整个模式的发布、列列表和行过滤需要 Postgres 15 或更高版本。选择一个发布范围；示例是可选的替代方案。

🌐 The following SQL examples assume you have users and orders tables with the referenced columns in your database. Schema-wide publications, column lists, and row filters require Postgres 15 or later. Choose one publication scope; the examples are alternatives.

特定表格的发布 #

🌐 Publication for specific tables

1
create publication pub_users_orders
2
for table users, orders;

本发布物包括对 users 和 orders 的插入、更新、删除和截断。

🌐 This publication includes inserts, updates, deletes, and truncates for users and orders.

发布模式中的所有表格 #

🌐 Publication for all tables in a schema

1
create publication pub_all_public
2
for tables in schema public;

这会跟踪 public 架构中所有现有和未来表的更改。

🌐 This tracks changes for all existing and future tables in the public schema.

要包含多个应用模式，请传入用逗号分隔的列表。例如，如果你的表在 public 和 analytics 中：

🌐 To include multiple application schemas, pass a comma-separated list. For example, if your tables are in public and analytics:

1
create publication pub_application_schemas
2
for tables in schema public, analytics;

两个模式必须已经存在。这包括它们的现有和未来的表，但不包括内部的 etl 模式。添加新表后重启数据管道，这样系统才能发现它们。有关语法和要求，请参见 Postgres schema publications。

🌐 Both schemas must already exist. This includes their existing and future tables without including the internal etl schema. Restart the pipeline after adding new tables so it discovers them. See Postgres schema publications for syntax and requirements.

所有表格的发布 #

🌐 Publication for all tables

Pipelines 拒绝 FOR ALL TABLES，因为它包含了 内部的 etl 表。复制它们可能会干扰复制状态。对于应用模式请使用 FOR TABLES IN SCHEMA，或者明确列出表。替换任何现有的 FOR ALL TABLES 发布；Postgres 不能就地缩小它。

🌐 Pipelines rejects FOR ALL TABLES because it includes the internal etl tables. Replicating them can interfere with replication state. Use FOR TABLES IN SCHEMA for application schemas or list tables explicitly. Replace any existing FOR ALL TABLES publication; Postgres cannot narrow it in place.

高级发布选项 #

🌐 Advanced publication options

使用这些选项来控制发布哪些数据，以及分区表在目标位置的显示方式。

🌐 Use these options to control which data is published and how partitioned tables appear at the destination.

选择特定列 #

🌐 Selecting specific columns

你可以只复制表中的一部分列：

🌐 You can replicate only a subset of columns from a table:

1
create publication pub_users_subset
2
for table users (id, email, created_at);

对于更新和删除操作，列列表必须包含所有副本标识列。使用 REPLICA IDENTITY FULL 时，这意味着所有列，所以你不能只发布其中一部分。同时也要检查一下目标端的源表要求。

🌐 For updates and deletes, the column list must include all replica-identity columns. With REPLICA IDENTITY FULL, that means all columns, so you cannot publish a subset. Also check your destination's source table requirements.

用谓词过滤行 #

🌐 Filtering rows with a predicate

你可以使用 WHERE 子句过滤要复制的行。这些示例在初次同步时复制匹配的现有行，然后只复制匹配的插入行：

🌐 You can filter which rows to replicate using a WHERE clause. These examples copy matching existing rows during initial sync and then replicate matching inserts only:

1
-- Only replicate active users
2
create publication pub_active_users
3
for table users
4
where (status = 'active')
5
with (publish = 'insert');
6
7
-- Only replicate recent orders
8
create publication pub_recent_orders
9
for table orders
10
where (created_at > '2024-01-01')
11
with (publish = 'insert');

要同时发布更新和删除，行过滤器中使用的每一列都必须被表的副本标识覆盖。例如，REPLICA IDENTITY FULL 覆盖所有列，但会产生更多的 WAL。在启用这些操作之前，先查看 Postgres 行过滤器限制 和目标表的源表要求。

🌐 To also publish updates and deletes, every column used in the row filter must be covered by the table's replica identity. For example, REPLICA IDENTITY FULL covers all columns, at the cost of more WAL. Review Postgres row-filter restrictions and your destination's source table requirements before enabling those operations.

Postgres 会在发送更改之前评估过滤条件。只有当表达式是 true 时，行才匹配；false 和 NULL 不匹配。对于更新，它会检查旧行和新行：

🌐 Postgres evaluates the filter before sending changes. A row matches only when the expression is true; false and NULL do not match. For an update, it checks both the old and new row:

当发布更新时，这适用。行过滤器不会限制 TRUNCATE：已发布的截断会影响整个目标表。在更改现有管道的过滤器之前，请查看 其他发布更改。

🌐 This applies when updates are published. Row filters do not limit TRUNCATE: a published truncate affects the whole destination table. See Other publication changes before changing a filter on an existing pipeline.

分区表 #

🌐 Partitioned tables

publish_via_partition_root 控制分区更改是作为一个父表到来，还是作为单独的叶子表到来：

整个模式的发布对分区表遵循相同的规则；普通表则保持独立。

🌐 Schema-wide publications follow the same rule for partitioned tables; regular tables remain separate.

例如，如果 orders 按月份进行分区：

🌐 For example, if orders is partitioned by month:

1
-- Publish all partitions as the parent table.
2
create publication pub_orders_root
3
for table orders
4
with (publish_via_partition_root = true);
5
6
-- Publish each leaf as a separate table.
7
create publication pub_orders_leaves
8
for table orders
9
with (publish_via_partition_root = false);

通过仪表板复制流程创建的发布默认使用 publish_via_partition_root = true。清除将发布分区作为父表以使用 false。如果你通过 SQL 手动创建或修改发布，请明确设置此选项，以便目标形态符合你的预期。

🌐 Publications created from the Dashboard replication flow default to publish_via_partition_root = true. Clear Publish partitions as the parent table to use false. If you create or alter a publication manually with SQL, set this option explicitly so the destination shape matches what you expect.

在 Postgres 15 及更高版本中，行过滤器会在初始同步和持续复制期间生效：

🌐 On Postgres 15 and later, row filters apply during both initial sync and ongoing replication:

• 使用 publish_via_partition_root = true 时，即使叶子节点有自己的筛选器或列列表，也会应用已发布的父节点的筛选器和列列表。
• 使用 false 时，每个叶子节点的过滤器和列列表都会生效。在叶子节点上定义行过滤器；在这种模式下，Postgres 会拒绝在分区父节点上使用它们。

查看 Postgres 分区行过滤器 了解示例。

🌐 See Postgres partition row filters for examples.

发布设置控制哪个 Postgres 关系成为目标表。它不会把源表的物理分区配置、分区键或分区范围复制到目标表。

🌐 The publication setting controls which Postgres relation becomes a destination table. It does not copy the source table's physical partitioning configuration, partition key, or partition bounds to the destination.

在开始复制之前选择模式：

🌐 Choose the mode before starting replication:

• 使用 true，新创建或附加的分区中的新变化会直接流向已经被跟踪的父分区，无需重启。附加分区不会复制其中已经存在的行。
• 使用 false，新的分区表有自己的表身份。重启管道以发现它；只有在选择进行初始同步时，其现有行才会被复制。

要更改模式，先停止管道，修改选项，查看新表的 初始同步，然后重新启动。管道会移除未跟踪表的状态，并发现新表，只有在选择了初始同步时才会复制现有行。旧的目标表仍然存在；它们的数据不会自动合并或拆分。

🌐 To change modes, stop the pipeline, change the option, review Initial sync for the new table identities, then restart. Pipelines removes state for untracked tables and discovers new ones, copying existing rows only if selected for initial sync. Old destination tables remain; their data is not merged or split automatically.

其他发布变更 #

🌐 Other publication changes

发布更改并不都需要重启流水线：

🌐 Publication changes do not all require a pipeline restart:

更改行过滤器只会影响未来的更改：它既不复制新加入的历史行，也不会删除不再匹配的行。流水线重启不会重建历史。要重建，请初始同步时包含受影响的表并[重启其复制]（/docs/guides/database/replication/pipelines-monitoring#restarting-tables）。

🌐 Changing a row filter affects future changes only: it neither copies newly included historical rows nor removes rows that no longer match. A pipeline restart does not rebuild history. To rebuild it, include affected tables in initial sync and restart their replication.

在更改过滤器之前，请等待初始同步完成；更改过滤器不会更新已经在进行中的副本。

🌐 Wait for initial sync to finish before changing its filter; changing a filter does not update a copy already in progress.

ALTER PUBLICATION ... SET TABLE 替换表格列表。更改列列表或筛选器时，请包含所有想保留的表格；未包含的表格将被移除。

支持模式更改 #

🌐 Schema change support

随着复制的进行，管道会将支持的更改应用到复制的列上。它不会镜像每一个 Postgres DDL 操作。在修改被复制的表之前，请先查看针对 BigQuery、ClickHouse、DuckLake 或 Snowflake 的支持更改和目标行为。

🌐 Pipelines applies supported changes to replicated columns as replication progresses. It does not mirror every Postgres DDL operation. Check the supported changes and destination behavior for BigQuery, ClickHouse, DuckLake, or Snowflake before altering replicated tables.

不支持的更改会有不同的结果：

🌐 Unsupported changes have different outcomes:

• 数据类型的更改会被跳过并显示警告，包括精度或标度的更改。目标端会保留现有的数据类型。兼容的值可能继续复制，但之后的写入或模式更改可能会失败。
• 不支持的默认值和收紧 NOT NULL 会被跳过，并显示警告。 复制可以继续使用不同的默认值或更宽松的目标列。每个目标指南都会说明这些差异；跳过默认值并不意味着会跳过 Postgres 在行变化中提供的值。
• 不兼容的模式更改会被拒绝并报错，比如更改 BigQuery 或 ClickHouse 的 ReplacingMergeTree 使用的主键定义。失败或中断的模式更改可能需要手动恢复。

在更改了一个复制表后，查看复制日志中的警告和错误。

🌐 Check replication logs for warnings and errors after changing a replicated table.

在类型更改后，或者当模式错误无法安全恢复时，解决任何源不兼容问题并重新启动受影响表的复制。这会重建它们的目标模式并删除现有的目标数据。选择表进行初始同步以再次复制它们当前的源行。仅重启管道不会重建表。不要手动修复托管目标对象。

🌐 After a type change, or when a schema error cannot resume safely, resolve any source incompatibility and restart replication for the affected tables. This rebuilds their destination schema and deletes their existing destination data. Select the tables for Initial sync to copy their current source rows again. Restarting the pipeline alone does not rebuild tables. Do not repair managed destination objects manually.

限制 #

🌐 Limitations

管道有以下限制：

🌐 Pipelines has the following limitations:

• 源表：主键、副本标识和发布列的要求取决于目标。在创建管道之前，请查阅其目标指南。
• 转换：管道会映射目标的名称和类型，但不会运行用户定义的转换。
• 自定义数据类型：自定义值会以字符串形式复制。请确保你的目标可以正确解析这些字符串值。
• 数组：目前只支持一维数组。非默认下界不会被保留。有关其他数组限制，请查看目标指南。
• 生成列：生成列会被跳过。如果你在目标中需要这些值，可以用触发器将派生值存储到普通列中。

每个目标指南中都会记录目标特定的限制，比如行大小和类型映射。

🌐 Destination-specific limitations, such as row size and type mappings, are documented in each destination guide.