设置管道

Supabase Pipelines 是一个托管的 CDC 产品，用于将数据从 Supabase Postgres 移动到支持的目标系统。它使用 Postgres 逻辑复制 和开源的 Supabase ETL 引擎。你可以在仪表板上选择目标，Supabase 会运行管道，将数据库的变更发送到该目标。

🌐 Supabase Pipelines is a managed CDC product for moving data from Supabase Postgres to supported destination systems. It uses Postgres logical replication with the open-source Supabase ETL engine. You choose a destination in the Dashboard, and Supabase runs the pipeline that sends database changes to that destination.

管道有两个复制阶段：

🌐 Pipelines has two replication phases:

• 初始同步：对已发布表中的现有行进行一次性复制。
• 持续复制 (CDC)：持续捕捉并应用后续的插入、更新、删除和清空操作。

托管管道运行在 AWS eu-central-1（法兰克福）。选择一个尽量靠近法兰克福的目标区域，以减少网络延迟和复制延迟。

🌐 Managed Pipelines run in AWS eu-central-1 (Frankfurt). Choose a destination region as close as possible to Frankfurt to reduce network latency and replication lag.

价格 #

🌐 Pricing

$0.053 每个配置的流水线每小时收费。 $0.60 在初始同步期间，每处理一GB数据收费。 $3.00 在持续复制期间，每处理一GB数据收费。

已处理数据 是指通过管道成功处理并被目标系统接受的 Postgres 行数据。它是从 Postgres 为复制而发出的逻辑行数据来衡量的，而不是物理表存储或特定目标的编码。

有关费用如何计算的详细说明，请参阅管理管道使用情况。

🌐 For a detailed breakdown of how charges are calculated, refer to Manage Pipeline usage.

有关计费示例和优化指导，请参见 管理管道使用情况。

🌐 For billing examples and optimization guidance, see Manage Pipelines usage.

设置概览 #

🌐 Setup overview

管道需要两个主要组件：一个 Postgres 发布（定义要复制的内容）和一个 目标（数据发送到哪里）。Supabase 运行托管管道，从发布中读取并写入到目标。按照这些步骤设置你的复制管道。

🌐 Pipelines requires two main components: a Postgres publication (defines what to replicate) and a destination (where data is sent). Supabase runs the managed pipeline that reads from the publication and writes to the destination. Follow these steps to set up your replication pipeline.

步骤 1：创建一个 Postgres 发布 #

🌐 Step 1: Create a Postgres publication

Postgres 的发布定义了哪些表和变更类型会从你的数据库中被复制。当你配置目标时，可以在仪表板中创建一个基本发布，或者在需要列列表、行过滤、全模式发布或其他高级选项时使用 SQL。

🌐 A Postgres publication defines which tables and change types will be replicated from your database. You can create a basic publication in the Dashboard while configuring the destination, or use SQL when you need column lists, row filters, schema-wide publications, or other advanced options.

• 仪表板：继续到步骤 2。在步骤 3 中，打开发布选择器，点击新建发布，输入名称，并至少选择一个表。
• SQL：现在使用下面的一个示例创建发布，然后在配置目标时选择它。

用 SQL 创建发布物 #

🌐 Creating a publication with SQL

下面的 SQL 示例假设你的数据库中有 users 和 orders 表。

🌐 The following SQL examples assume you have users and orders tables in your database.

特定表格的发布 [#publication-for-specific-tables]

🌐 Publication for specific tables

1
-- Create publication for both tables
2
create publication pub_users_orders
3
for table users, orders;

这份发布物会跟踪 users 和 orders 表的所有更改（插入、更新、删除、清空）。

🌐 This publication tracks all changes (INSERT, UPDATE, DELETE, TRUNCATE) for both the users and orders tables.

发布模式中的所有表格 [#publication-for-all-tables-in-a-schema]

🌐 Publication for all tables in a schema

1
-- Create a publication for all tables in the public schema
2
create publication pub_all_public for tables in schema public;

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

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

所有表格的发布 [#publication-for-all-tables]

🌐 Publication for all tables

1
-- Create a publication for all tables
2
create publication pub_all_tables for all tables;

这会跟踪你数据库中所有表的变化。

🌐 This tracks changes for all tables in your database.

高级发布选项 #

🌐 Advanced publication options

选择特定列 [#selecting-specific-columns]

🌐 Selecting specific columns

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

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

1
-- Replicate only specific columns from the users table
2
create publication pub_users_subset
3
for table users (id, email, created_at);

这只复制了 users 表中的 id、email 和 created_at 列。

🌐 This only replicates the id, email, and created_at columns from the users table.

用谓词过滤行 [#filtering-rows-with-a-predicate]

🌐 Filtering rows with a predicate

你可以使用 WHERE 子句来筛选要复制的行：

🌐 You can filter which rows to replicate using a WHERE clause:

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

分区表 [#partitioned-tables]

🌐 Partitioned tables

Pipelines 遵循 Postgres 对分区表的发布语义。publish_via_partition_root 发布设置控制分区的更改是作为分区根发出，还是作为叶分区发出。

🌐 Pipelines follows Postgres publication semantics for partitioned tables. The publish_via_partition_root publication setting controls whether changes from partitions are emitted as the partition root or as the leaf partitions.

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

🌐 For example, if orders is partitioned by month:

1
-- Replicate the whole partition hierarchy as the parent table.
2
create publication pub_orders_root
3
for table orders
4
with (publish_via_partition_root = true);
5
6
-- Replicate each leaf partition as its own table.
7
create publication pub_orders_leaves
8
for table orders
9
with (publish_via_partition_root = false);

当你希望分析查询从具有父表架构的单个目标表读取时，使用 publish_via_partition_root = true。当每个分区应保持为单独的目标表时，使用 false。

🌐 Use publish_via_partition_root = true when you want analytics queries to read from a single destination table that has the parent table's schema. Use false when each partition should remain a separate destination table.

通过仪表板复制流程创建的发布使用 publish_via_partition_root = true。如果你通过 SQL 手动创建或修改发布，请明确设置此选项，以确保目标形态符合你的预期。

🌐 Publications created from the Dashboard replication flow use publish_via_partition_root = true. If you create or alter a publication manually with SQL, set this option explicitly so the destination shape matches what you expect.

在 Postgres 15 及更新版本中，分区发布上的行过滤器会在初始同步和持续复制过程中都生效。Pipelines 使用附加到有效发布表条目的行过滤器：当是 publish_via_partition_root = true 时，是发布的分区根；当是 publish_via_partition_root = false 时，是发布的叶子关系。

🌐 On Postgres 15 and newer, row filters on partition publications apply during both the initial sync and ongoing replication. Pipelines uses the row filter attached to the effective publication table entry: the published partition root when publish_via_partition_root = true, and the published leaf relation when publish_via_partition_root = false.

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

🌐 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 BigQuery.

在仪表板查看发布内容 #

🌐 Viewing publications in the Dashboard

通过 SQL 创建发布后，你可以在控制面板中查看它：

🌐 After creating a publication via SQL, you can view it in the Dashboard:

1. 在仪表板中导航到 数据库 > 发布物 部分
2. 你会看到你所有的发布物都列出了表格

步骤 2：启用管道 #

🌐 Step 2: Enable Pipelines

在创建托管复制管道之前，先为你的项目启用管道功能：

🌐 Before creating a managed replication pipeline, enable Pipelines for your project:

1. 导航到仪表板的 数据库 > 复制 部分
2. 点击 添加目标 显示复制侧边面板
3. 选择一个 Pipelines 目标，比如 BigQuery
4. 点击 启用管道

步骤 3：设置目标 #

🌐 Step 3: Configure a destination

一旦启用了 Pipelines 并且你有了一个 Postgres 发布，接下来就配置一个目标。目标是存放你复制数据的地方，而 pipeline 则是活跃的 Postgres 复制过程，它会持续地将数据库中的更改流式传输到那个目标。

🌐 Once Pipelines is enabled and you have a Postgres publication, configure a destination. The destination is where your replicated data will be stored, while the pipeline is the active Postgres replication process that continuously streams changes from your database to that destination.

选择并设置你的目的地 #

🌐 Choose and configure your destination

按照以下步骤配置你的目标。每个目标都有自己的设置要求和行为。BigQuery 当前可用。你可以申请提前访问 ClickHouse、Snowflake 和 DuckLake。

🌐 Follow these steps to configure your destination. Each destination has its own setup requirements and behavior. BigQuery is currently available. You can request early access to ClickHouse, Snowflake, and DuckLake.

1. 导航到仪表板的 数据库 > 复制 部分

2. 如果目标侧边栏还没打开，点击添加目标

3. 选择目的地类型

4. 配置目标详情：

   • 目的地名称：用于识别此目的地的名称
   • 发布：选择一个现有的发布，或点击 新建发布，通过选择名称和至少一个表来创建一个新的发布
   • 区域：托管管道在固定的 AWS eu-central-1（法兰克福） 区域运行，无法更改。在你的目标提供商中，选择一个附近的数据集、仓库或存储桶区域。

5. 配置目标特定的设置。查看目标指南以获取所需的凭证、权限和限制：

   • BigQuery

6. 可选择展开高级设置来调整流水线行为：

   Setting	Default	Allowed values	Description
   Batch wait time	10000 milliseconds	Whole milliseconds, 0 or greater	Maximum time after the first buffered initial-sync row or ongoing change before the pipeline flushes a partially filled batch. Internal size and memory limits can flush it earlier. Lower values can reduce batching delay; higher values can improve destination write efficiency.
   Table sync workers	4 workers	Whole number greater than 0	Maximum number of tables synced in parallel during the initial sync. Each active table sync temporarily uses one additional replication slot, up to N + 1 slots including the pipeline's main slot.
   Copy connections per table	4 connections	Whole number greater than 0	Maximum source database connections used to copy one table in parallel. With multiple table sync workers, source connection usage can scale with both settings. More connections can speed up large tables until the source database, network, or destination becomes the bottleneck.
   Invalidated slot behavior	Error	Error or Recreate	What happens when the main replication slot can no longer continue from retained WAL. Error blocks startup for manual recovery. Recreate resets table sync state, rebuilds the slot on the next start, and runs the initial sync again for every replicated table.

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

   小心使用无效槽行为。如果选择了重新创建，并且管道在 Postgres 使主复制槽失效后启动，管道会重置已保存的表同步状态，创建一个新槽，并通过新的初始同步替换每个目标表。这个破坏性的重启是为了保持一致性，因为旧槽无法再提供管道遗漏的所有变更，而且在新的初始同步过程中处理的数据会再次计费。

7. 点击 创建并启动管道 开始复制

管道会从你的数据库开始初始同步到目标位置。

🌐 The pipeline begins the initial sync from your database to your destination.

步骤4：监控你的流程 #

🌐 Step 4: Monitor your pipeline

在你创建并启动管道后，它的目标会出现在目标列表中。你可以在仪表板上监控管道的状态和性能。

🌐 After you create and start the pipeline, its destination appears in the destinations list. You can monitor the pipeline's status and performance from the Dashboard.

有关包括管道状态、指标和日志在内的全面监控说明，请参见监控管道状态。

🌐 For comprehensive monitoring instructions including pipeline states, metrics, and logs, see Monitor pipeline status.

管理你的流程 #

🌐 Managing your pipeline

你可以通过目的地列表中的操作菜单来管理你的流水线。

🌐 You can manage your pipeline from the destinations list using the actions menu.

可用操作：

🌐 Available actions:

• 启动管道：开始已停止管道的复制
• 有更新：当有更新可用时，查看并应用最新的托管管道版本
• 停止流水线：请求优雅停止。在处理中的工作完成前，流水线最多可以保持 停止中 状态五分钟。新的更改会排队到 WAL，停止时配置的流水线小时计费仍会继续。
• 重启管道：停止并重新启动管道（发布更改后需要）
• 编辑目标：修改目标设置，比如凭证或高级选项
• 删除目标：移除目标并永久停止复制

禁用管道 #

🌐 Disabling Pipelines

要关闭项目的 Pipelines，首先删除所有 Pipelines 目标。删除所有目标后，打开复制页面上的三点操作菜单，然后点击禁用 Pipelines。

🌐 To turn off Pipelines for a project, delete all Pipelines destinations first. After all destinations are removed, open the three-dot actions menu on the Replication page and click Disable Pipelines.

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

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

添加或删除表格 #

🌐 Adding or removing tables

如果你在复制管道已经运行后需要修改哪些表被复制，请按照以下步骤操作：

🌐 If you need to modify which tables are replicated after your replication pipeline is already running, follow these steps:

向复制中添加表 #

🌐 Adding tables to replication

1. 使用 SQL 将表格添加到你的发布物中：

   1
   -- Add a single table to an existing publication
   2
   alter publication pub_users_orders add table products;
   3
   4
   -- Or add multiple tables at once
   5
   alter publication pub_users_orders add table products, categories;

2. 使用操作菜单重新启动复制管道（请参见管理你的管道），以使更改生效。

从复制中移除表 #

🌐 Removing tables from replication

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

   1
   -- Remove a single table from a publication
   2
   alter publication pub_users_orders drop table orders;
   3
   4
   -- Or remove multiple tables at once
   5
   alter publication pub_users_orders drop table orders, products;

2. 使用操作菜单重新启动复制管道（请参见管理你的管道），以使更改生效。

支持模式更改 #

🌐 Schema change support

模式更改支持取决于目标。BigQuery 目前是唯一支持测试版模式更改的目标。请参阅 BigQuery 模式更改支持 了解支持和不支持的更改。

🌐 Schema change support depends on the destination. BigQuery is currently the only destination with beta schema change support. See BigQuery schema change support for supported and unsupported changes.

它是怎么运作的 #

🌐 How it works

一旦配置好，复制管道会：

🌐 Once configured, a replication pipeline:

1. 捕获来自你的 Postgres 数据库的变化，使用 Postgres 发布和逻辑复制
2. 通过受管管道发送更改
3. 将数据加载到你的目的地

管道会自动优化变更传送到目的地的方式。它会将已发布的源列和数值映射到目的地兼容的名称和类型，但不提供用户自定义的转换。

🌐 Pipelines automatically optimizes how changes are delivered to the destination. It maps published source columns and values to destination-compatible names and types, but doesn't provide user-defined transformations.

故障排除 #

🌐 Troubleshooting

如果你在设置过程中遇到问题：

🌐 If you encounter issues during setup:

• 发布未显示：确保你通过 SQL 创建了 Postgres 发布，并刷新仪表板
• 表格未在发布中显示：请确认你的表格符合所选目标的要求。BigQuery 需要源主键，并且发布中必须包含其列。
• 管道启动失败：在状态视图中查看错误信息以获取具体细节
• 没有正在复制的数据：请确认你的 Postgres 发布包含正确的表和事件类型

如需更多故障排除帮助，请参阅 Pipelines 常见问题。

🌐 For more troubleshooting help, see the Pipelines FAQ.

限制 #

🌐 Limitations

管道有以下限制：

🌐 Pipelines has the following limitations:

• 主键：要求因目标而异。Postgres 可以发布没有主键的表的插入，但 BigQuery Pipelines 总是需要源主键，并且要求发布包含其列。
• 自定义数据类型：自定义值会以字符串形式复制。请确保你的目标可以正确解析这些字符串值。
• 生成列：生成列会被跳过。如果你在目标中需要这些值，可以用触发器将派生值存储到普通列中。
• 复制身份：要求因目标而异。更新和删除操作需要足够的行身份信息以安全应用。详见 BigQuery 源表要求 支持的模式。
• 模式更改：目前处于测试阶段，仅限 BigQuery 使用
• 不支持用户自定义转换：Pipelines 会执行目标兼容的类型和名称映射，但不会运行自定义转换
• 至少一次处理：管道重试的目的地写入失败尝试不计数。在极少数情况下，管道可能会将已确认的批次计入，但在其复制检查点持久化之前崩溃或被中断。恢复后可能会再次处理并计数该批次。BigQuery 使用基于主键的 CDC 来汇聚当前表状态。详情请参见 数据可以被处理多次吗？。

针对特定目标的限制，比如 BigQuery 的行大小限制，会在每个目标指南中说明。

🌐 Destination-specific limitations, such as BigQuery's row size limits, are documented in each destination guide.

下一步 #

🌐 Next steps

• 设置 BigQuery
• 监控流水线状态
• 查看管道常见问题