鸭子湖目的地

将 Postgres 表复制到 DuckLake 以进行当前状态的湖仓查询。先 准备资源，然后 配置目标，最后 查询复制的数据。

🌐 Replicate Postgres tables to DuckLake for current-state lakehouse queries. Prepare resources, configure the destination, then query replicated data.

源表要求 #

🌐 Source table requirements

仅插入表不需要主键或副本标识。更新和删除需要已发布的 Postgres 行标识。请参见 支持的副本标识。

🌐 Insert-only tables don't require a primary key or replica identity. Updates and deletes require a published Postgres row identity. See supported replica identities.

准备 DuckLake 资源 #

🌐 Prepare DuckLake resources [#understand-the-ducklake-components]

DuckLake 会把元数据存储在 Postgres 目录里，数据存储在对象存储里。Pipelines 提供了两种设置方式：

🌐 DuckLake stores metadata in a Postgres catalog and data in object storage. Pipelines offers two ways to set them up:

• 使用这个 Supabase 项目：Pipelines 使用这个项目的 Postgres 数据库作为目录，并使用同一项目中的 Storage 桶作为对象存储。它还会创建连接凭证。
• 输入连接详情：你提供目录 URL 和存储凭证。

要读取复制的数据，你也需要一个兼容的查询引擎。

🌐 To read the replicated data, you also need a compatible query engine.

你可以查询复制的表，但要把它们以及其底层的目录和对象存储状态当作只读的。在管道之外进行写操作可能会与复制和后台维护发生冲突。

🌐 You can query replicated tables, but treat them and their underlying catalog and object-storage state as read-only. Writes outside Pipelines can conflict with replication and background maintenance.

将 DuckLake 配置为目标 #

🌐 Configure DuckLake as a destination [#choose-a-configuration-mode]

按照设置管道操作。在添加管道中，选择DuckLake，输入管道名称，选择一个发布，并设置初始同步。然后选择如何配置目录和存储。

🌐 Follow Set up Pipelines. In Add pipeline, select DuckLake, enter a Pipeline name, choose a Publication, and set Initial sync. Then choose how to configure the catalog and storage.

使用这个 Supabase 项目 #

🌐 Use this Supabase project [#use-supabase]

使用当前 Supabase 项目的 Postgres 数据库作为目录，并在同一项目中使用 Storage 存储桶。Pipelines 会在你创建目标时生成连接凭证。

🌐 Use the current Supabase project's Postgres database for the catalog and a Storage bucket in the same project. Pipelines creates the connection credentials when you create the destination.

在你开始之前：

🌐 Before you begin:

• 为 DuckLake 数据选择一个文件桶。你可以从目标表单创建一个私有桶。
• 为这个 DuckLake 选择一个未使用的元数据模式名称。Pipelines 会创建这个模式及其表格。只使用字母、数字和下划线。如果项目已经使用默认的 ducklake 仓库模式，请输入一个不同的名称。

要配置目的地：

🌐 To configure the destination:

1. 在 配置方法 下选择 使用此 Supabase 项目。
2. 输入 元数据模式。
3. 选择存储桶。如果你还没有创建，请在存储桶列表底部选择新建存储桶。
4. 可选地在 高级设置 下调整 连接池大小。它允许 1 到 6 个并发 DuckDB 连接；默认是 4 个。
5. 点击 Start pipeline。查看任何验证警告，然后用 Create and start pipeline 确认预计费用。

在创建之前，预计会出现凭证提供警告：保存目标时会提供目录和存储凭证。在继续之前，请查看元数据模式和存储桶。

🌐 Credential-provisioning warnings are expected before creation: catalog and Storage credentials are provisioned when you save the destination. Review the metadata schema and bucket before proceeding.

输入连接详细信息 #

🌐 Enter connection details [#custom-parameters]

使用此模式连接现有的 Postgres 数据库和兼容 S3 的对象存储。你只需提供它们的连接详情和凭证。

🌐 Use this mode to connect an existing Postgres database and S3-compatible object storage. You provide their connection details and credentials.

准备以下资源：

🌐 Prepare the following resources:

1. 一个可以从托管管道访问的 Postgres 数据库。创建一个专用用户，拥有创建 DuckLake 元数据模式及其表的权限。
2. 一个兼容 S3 的存储桶和为这个 DuckLake 专用的前缀。
3. 可以列出、读取、写入和删除该前缀下对象的对象存储凭证。托管文件清理需要删除权限。

为每个目标选择一个未使用的元数据模式名称和新的数据前缀。Pipeline 会创建该模式及其表。提前在该模式下初始化 DuckLake 目录会触发验证警告；重复使用它的模式或前缀可能会混合来自不同 DuckLake 的元数据或文件。

🌐 Choose an unused metadata schema name and a new data prefix for each destination. Pipelines creates the schema and its tables. Initializing a DuckLake catalog in that schema beforehand triggers a validation warning; reusing its schema or prefix can mix metadata or files from different DuckLakes.

在 配置方法 下选择 输入连接详情，然后配置这些字段：

🌐 Select Enter connection details under Configuration method, then configure these fields:

• 目录 URL：你现有数据库的 postgres:// 或 postgresql:// URL，包括凭证。如果你的提供商要求 TLS，在数据库名称后添加 ?sslmode=require，如果 URL 已经有查询参数，则添加 &sslmode=require。保持提供商 URL 中的数据库名称，不需要是 ducklake_catalog。
• 数据路径：一个 s3://<bucket>/<prefix> URL
• S3访问密钥ID 和 S3秘密访问密钥：数据路径的凭证组合
• S3 端点：一个公开可访问的提供者端点，没有 http:// 或 https://
• S3 区域：存储提供商的区域
• S3 URL 风格：如果桶名在 URL 路径中，则为路径风格；如果桶名在主机名中，则为虚拟主机风格
• 使用 SSL：如果使用 HTTPS，选择 开启；如果提供商要求 HTTP，选择 关闭
• 元数据架构：DuckLake 元数据的独特 Postgres 架构，只使用字母、数字和下划线

可选择在高级设置中调整连接池大小。它允许 1 到 6 个并发 DuckDB 连接；默认值是 4。点击启动管道，查看验证结果，然后通过创建并启动管道确认预计费用。

🌐 Optionally adjust Pool size under Advanced settings. It allows 1 to 6 concurrent DuckDB connections; the default is 4. Click Start pipeline, review the validation results, then confirm the estimated cost with Create and start pipeline.

目录 URL 和存储凭据会作为秘密保存，创建后不会返回。在编辑目标时，如果想保留已存的值，可以把秘密字段留空；如果想替换，则输入新值。

🌐 The catalog URL and storage credentials are stored as secrets and aren't returned after creation. When editing the destination, leave a secret field empty to keep its stored value, or enter a new value to replace it.

复制是怎么运作的 #

🌐 How replication works

管道会创建当前状态表，根据初始同步选择复制行，然后应用已发布的更改和支持的架构更改。

🌐 Pipelines creates current-state tables, copies rows according to the initial sync selection, then applies published changes and supported schema changes.

源架构和表名会被保留，而列名中的 ASCII 大写字母会被转换为小写。DuckDB 在比较架构、表和列标识符时不区分 ASCII 大小写，所以不要发布仅大小写不同的名称。请使用不同的小写列名。源列名如果符合生成的 supabase_etl_ducklake_dropped_<ordinal>_<hash> 形式，将被保留用于架构更改恢复。

一个源 TRUNCATE 会截断 DuckLake 表。表重启 会删除并重新创建它。从发布中移除表 会保留其目标数据。

🌐 A source TRUNCATE truncates the DuckLake table. A table restart drops and recreates it. Removing a table from the publication leaves its destination data in place.

查询复制的数据 #

🌐 Query replicated data [#query-the-destination]

将 DuckDB 通过它的 ducklake 扩展，或其他兼容引擎，连接到同一个目录和存储路径。通过目录查询；直接读取原始 Parquet 文件可能会漏掉内嵌的更改、删除的文件以及当前快照。

🌐 Connect DuckDB with its ducklake extension, or another compatible engine, to the same catalog and storage path. Query through the catalog; reading raw Parquet files can miss inlined changes, delete files, and the current snapshot.

如果你使用这个 Supabase 项目，请为它的 Postgres 数据库和存储创建单独的只读凭据。为 Pipelines 生成的写入凭据不会被暴露。如果你输入连接详细信息，当你的目录和存储提供商支持时，使用单独的只读凭据。

🌐 If you use this Supabase project, create separate read credentials for its Postgres database and Storage. The writer credentials generated for Pipelines aren't exposed. If you enter connection details, use separate read-only credentials when your catalog and storage provider support them.

在使用像 my_ducklake 这样的别名附加目录后，源模式和表就可以作为合格的 DuckLake 表使用了：

🌐 After attaching the catalog under an alias such as my_ducklake, source schemas and tables are available as qualified DuckLake tables:

1
select *
2
from my_ducklake.public.orders;

查看 DuckDB 连接指南 了解当前的 ducklake 扩展和 ATTACH 语法。如果你的查询客户端在公开测试阶段无法读取 Supabase 支持的目录，联系支持。

🌐 See the DuckDB connection guide for the current ducklake extension and ATTACH syntax. If your query client can't read a Supabase-backed catalog during public alpha, contact support.

复制身份 #

🌐 Replica identity

副本身份更改只会影响新的 WAL。如果保留的更新或删除在管道重启后仍然失败，请重新启动受影响表的复制。

🌐 Replica-identity changes affect only new WAL. If retained updates or deletes still fail after a pipeline restart, restart replication for the affected table.

类型映射 #

🌐 Type mapping

管道会根据这些映射创建 DuckLake 列：

🌐 Pipelines creates DuckLake columns with these mappings:

DuckDB 的十进制支持精度从 1 到 38，小数位数介于 0 与精度之间。Postgres 中在此范围之外声明的 numeric 值、无限制的 numeric 以及带不支持修饰符的数值类型都会被存储为 varchar，以保留它们的序列化值。

🌐 DuckDB decimals support precision from 1 to 38 and a scale between 0 and the precision. Postgres numeric values declared outside that range, unconstrained numeric, and numeric types with unsupported modifiers are stored as varchar to preserve their serialized value.

数值数组使用 varchar[]，即使它们声明的精度和小数位数可以适配标量 DuckLake 小数。

🌐 Numeric arrays use varchar[], even when their declared precision and scale would fit a scalar DuckLake decimal.

支持模式更改 #

🌐 Schema change support

管道支持：

🌐 Pipelines supports:

• 添加、重命名或删除列
• 从现有列中删除 NOT NULL
• 添加、修改或移除支持的列默认值
• 在跟踪的表上添加或删除已发布的列

新列被创建为可为空，这样现有的目标行仍然有效。添加 NOT NULL 会让现有的目标列保持可为空。支持的默认值会存储在 DuckLake 元数据中；其他默认值会被跳过。Postgres 仍然通过复制提供源值。

🌐 New columns are created as nullable so existing destination rows remain valid. Adding NOT NULL keeps an existing destination column nullable. Supported defaults are stored in DuckLake metadata; other defaults are skipped. Postgres still supplies the source values through replication.

之前被排除的列现在被添加进来，但没有默认值，历史行仍是 NULL。移除已发布的列会删除其目标值；再次添加它并不会恢复这些值。

🌐 Previously excluded columns are added without a default, leaving historical rows NULL. Removing a published column drops its destination values; adding it again does not restore them.

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

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

故障排除 #

🌐 Troubleshooting

使用 管道监控 来检查错误。如有未解决的失败，请携带管道 ID 和错误详情 联系支持。

🌐 Use pipeline monitoring to inspect errors. For unresolved failures, contact support with the pipeline ID and error details.

额外资源 #

🌐 Additional resources

• DuckLake 文档
• DuckLake 架构
• 监控流水线状态