Skip to content
Database

BigQuery 目的地

Replicate Supabase Postgres tables to BigQuery.

BigQuery 是谷歌全托管的数据仓库。你可以将数据库表复制到 BigQuery 进行分析和报告。

准备 GCP 资源 #

🌐 Prepare GCP resources

在将 BigQuery 配置为目标之前，请在 Google Cloud Platform 中设置以下内容：

🌐 Before configuring BigQuery as a destination, set up the following in Google Cloud Platform:

  1. Google Cloud 平台 (GCP) 账号：如果你还没有账号，注册 GCP。在目标项目中，确保已启用 BigQuery API 和 BigQuery 存储 API。

  2. BigQuery 数据集：在你的 GCP 项目中创建一个 BigQuery 数据集

    • 在 GCP 打开 BigQuery 控制台
    • 选择你的项目
    • 点击 创建数据集
    • 提供一个数据集 ID，例如 supabase_replication
    • 有意识地选择数据集位置。Supabase Pipelines 运行在 AWS eu-central-1（法兰克福），所以选择离它最近的 BigQuery 可用位置，以减少网络延迟。一旦创建了数据集，就无法更改位置，而且 Pipelines 不会从你的 Supabase 项目中推断位置，也不会复制 Postgres 分区设置。

  3. GCP 服务账号密钥：创建一个具有适当权限的服务账号

    • 去 IAM 与管理员 > 服务账号
    • 点击 创建服务账号
    • 在目标数据集上授予 BigQuery 数据编辑者 权限
    • 在 GCP 项目上授予 BigQuery 作业用户 权限
    • 创建并下载 JSON 密钥文件

    把下载的 JSON 当作秘密。不要提交或分享它，如果它被泄露了，更换或撤销密钥 。

这些角色提供了 Pipelines 所需的权限，以检查和管理目标表，通过存储写入 API 写入数据，以及运行 BigQuery 作业。如果你使用自定义 IAM 角色，它必须提供：

🌐 These roles provide the permissions Pipelines needs to inspect and manage destination tables, write data through the Storage Write API, and run BigQuery jobs. If you use a custom IAM role, it must provide:

  • bigquery.datasets.get
  • bigquery.jobs.create
  • bigquery.tables.create
  • bigquery.tables.delete
  • bigquery.tables.get
  • bigquery.tables.getData
  • bigquery.tables.list
  • bigquery.tables.update
  • bigquery.tables.updateData

将 BigQuery 配置为目标 #

🌐 Configure BigQuery as a destination

  1. 导航到仪表板的 数据库 > 复制 部分
  2. 点击 添加目的地
  3. 选择 BigQuery 作为目标类型
  4. 配置目标详情：
    • 目标名称：用于识别此目标的名称，例如“大查询仓库”
    • 发布物：用来复制数据的发布物
    • 区域：托管管道在固定的 AWS eu-central-1（法兰克福） 区域运行。这与你的 BigQuery 数据集位置是分开的，无法更改。
  5. 配置 BigQuery 设置：

    • 项目ID：你的BigQuery项目标识符，可以在GCP控制台找到

    • 数据集 ID：你的 BigQuery 数据集的名字，不包括项目 ID

    • 服务账户密钥：你的 GCP 服务账户密钥，JSON 格式

BigQuery destination form with pipeline details and BigQuery credentials
Configure the BigQuery destination details and credentials.

  1. 可选择展开 高级设置 来进行管道和 BigQuery 特定的调整：

    常规批处理、初始同步并发以及无效槽设置在设置管道中有描述。BigQuery 添加了这些设置：

    SettingDefaultDescription
    Connection pool size4 connectionsNumber of BigQuery Storage Write API connections used for destination writes. More connections can increase write throughput, but consume more pipeline and BigQuery resources.
    Maximum stalenessFreshest resultsMaximum acceptable staleness, in whole minutes, of table data returned by queries while BigQuery applies CDC UPSERT and DELETE changes in the background. Leave unset for the freshest table data. A larger number of minutes allows BigQuery to return older data, which can reduce query-time CDC merge cost and latency. For example, 15 allows data to be up to 15 minutes stale. This value is applied when Pipelines creates or recreates a table; changing it doesn't alter existing destination tables.

  2. 查看 源表要求，然后点击 创建并启动管道 开始复制

管道开始将你的数据库初始同步到 BigQuery。

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

Supabase Pipelines 的费用和 Google Cloud 的费用是分开的。BigQuery 可能会对 Storage Write API 的摄取、存储以及用于应用 CDC 变更的计算资源收费。详见 BigQuery CDC 定价。

🌐 Supabase Pipelines charges and Google Cloud charges are separate. BigQuery can charge for Storage Write API ingestion, storage, and the compute used to apply CDC changes. See BigQuery CDC pricing.

它是怎么运作的 #

🌐 How it works

配置完成后，数据将复制到 BigQuery：

🌐 Once configured, replication to BigQuery:

  1. 捕获你的 Postgres 发布中包含的 INSERT、UPDATE、DELETE 和 TRUNCATE 操作
  2. 自动优化配送
  3. 使用与 BigQuery 兼容的名称和类型从复制的源模式创建目标表
  4. 将数据流传输到 BigQuery

Pipelines 会保留一个当前状态表，你可以查询每个被复制的源表，而且在截断或新的初始同步时可能会替换其目标数据。但它不会提供可以查询的每一行版本的历史记录。

🌐 Pipelines keeps a current-state table that you can query for each replicated source table and may replace its destination data during a truncate or new initial sync. It does not provide a history of every row version that you can query.

源表要求 #

🌐 Source table requirements

BigQuery 复制要求每个源表都有一个主键，并且发布必须包含主键列。Pipelines 会将那些列声明为 BigQuery 目标的主键，这样 BigQuery 的变更数据捕获（CDC）就可以应用 UPSERT 和 DELETE 行。

🌐 BigQuery replication requires each source table to have a primary key, and the publication must include the primary-key columns. Pipelines declares those columns as the BigQuery destination primary key so BigQuery change data capture (CDC) can apply UPSERT and DELETE rows.

BigQuery 的主键是 NOT ENFORCED，而 BigQuery 的变更数据捕获（CDC）支持最多 16 列的复合主键。你的源主键必须保持唯一且非空，因为 BigQuery 用它来匹配 CDC 行。

🌐 BigQuery primary keys are NOT ENFORCED, and BigQuery change data capture (CDC) supports composite primary keys with up to 16 columns. Your source primary key must stay unique and non-null because BigQuery uses it to match CDC rows.

源表也必须使用与 BigQuery 兼容的 Postgres REPLICA IDENTITY 设置。大多数表可以保持 Postgres 默认设置，只要它们有主键，并且所有主键列都包含在发布中。

🌐 Source tables must also use a BigQuery-compatible Postgres REPLICA IDENTITY setting. Most tables can keep the Postgres default, as long as they have a primary key and all primary-key columns are included in the publication.

源表设置BigQuery 支持指南
有主键的 REPLICA IDENTITY DEFAULT支持推荐用于大多数表。BigQuery 使用复制的源主键来应用 upsert 和 delete 操作。
REPLICA IDENTITY FULL支持推荐用于具有大量 text、jsonb、bytea 或 Postgres 可能通过 TOAST 外部存储的其他值的表，特别是那些会更新的行。
REPLICA IDENTITY USING INDEX有限制仅当选定的唯一索引恰好包含源主键列时才支持。不支持其他唯一键身份。
REPLICA IDENTITY NOTHING仅插入可以复制插入操作，但更新和删除没有足够的行身份信息供 BigQuery 安全应用。
没有主键的 REPLICA IDENTITY DEFAULT不支持BigQuery 需要源主键。

关于副本标识如何影响更新和删除事件的一般说明，请参见 副本标识如何影响更新和删除？。

🌐 For a general explanation of how replica identity affects update and delete events, see How does replica identity affect updates and deletes?.

对于更新来说，Postgres 在逻辑复制中并不总是发送完整的旧行。它也可能把没有变化的 toasted 值标记为 unchanged toast，而不是重新发送该值。BigQuery 的变更数据捕获 (CDC) upsert 需要完整的新行，因为省略的列在目标端不会被保留。当旧行图片包含缺失值时，复制管道可以重建完整的更新，对于 REPLICA IDENTITY FULL 来说这是可靠的。

🌐 For updates, Postgres does not always send a complete old row through logical replication. It can also mark unchanged toasted values as unchanged toast instead of resending the value. BigQuery change data capture (CDC) upserts require a complete new row because omitted columns are not preserved in the destination. The replication pipeline can reconstruct a complete update when the old row image contains the missing value, which is reliable with REPLICA IDENTITY FULL.

如果 BigQuery 流水线因为部分更新行的错误失败，在受影响的源表上设置 REPLICA IDENTITY FULL 然后重启流水线。更改副本身份只会影响新的 WAL 记录，所以在更改之前写入的保留更新可能仍然需要通过重新创建流水线或重启受影响表的初始同步来跳过。

🌐 If a BigQuery pipeline fails with an error about a partial update row, set REPLICA IDENTITY FULL on the affected source table and restart the pipeline. Changing replica identity only affects new WAL records, so a retained update that was written before the change may still need to be skipped by recreating the pipeline or restarting the affected table's initial sync.

查看表的当前副本标识：

🌐 Check a table's current replica identity:

1
select
2
  n.nspname as schema_name,
3
  c.relname as table_name,
4
  c.relreplident as replica_identity
5
from
6
  pg_class as c
7
  join pg_namespace as n on n.oid = c.relnamespace
8
where n.nspname = 'public' and c.relname = 'your_table';

replica_identity 的默认值是 d，完整时是 f，索引时是 i，什么都不选时是 n。

🌐 The replica_identity value is d for default, f for full, i for index, and n for nothing.

当表有 TOAST 列并且更新复制必须可靠时，设置完整副本标识：

🌐 Set full replica identity when a table has toasted columns and update replication must be reliable:

1
alter table public.your_table replica identity full;

REPLICA IDENTITY FULL 会增加 WAL 的容量，因为 Postgres 在更新和删除时会记录完整的旧行。对那些更新的正确性比额外复制开销更重要的表使用它。

支持模式更改 #

🌐 Schema change support

目前 BigQuery 的模式更改支持处于测试阶段。Pipelines 在该功能进一步开发期间，仅支持 BigQuery 的有限模式更改。

🌐 Schema change support for BigQuery is currently in beta. Pipelines supports a limited set of schema changes for BigQuery while the feature is developed further.

支持的模式更改：

🌐 Supported schema changes:

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

不支持或有限的模式更改：

🌐 Unsupported or limited schema changes:

  • 更改列的数据类型
  • 把 NOT NULL 和 SET NOT NULL 加在一起
  • 填充 ADD COLUMN ... DEFAULT 的现有行
  • 不支持的默认表达式

当初始同步创建一个 BigQuery 表时，Pipelines 会保留每个标量、非数组源列是否允许 NULL：Postgres 的 NOT NULL 列会变成 REQUIRED，可为空的列会变成 NULLABLE。BigQuery 会把 Postgres 的数组表示为 REPEATED 字段，而不是用 REQUIRED 或 NULLABLE 模式。

🌐 When the initial sync creates a BigQuery table, Pipelines preserves whether each scalar, non-array source column allows NULL: Postgres NOT NULL columns become REQUIRED, and nullable columns become NULLABLE. BigQuery represents Postgres arrays as REPEATED fields instead of using REQUIRED or NULLABLE mode.

在表存在之后，BigQuery 要求每个新添加的标量顶层列都必须是 NULLABLE。如果 Postgres 添加了一个 NOT NULL 列，Pipelines 会在 BigQuery 中将其添加为 NULLABLE，并记录一个警告。Postgres 仍然是事实来源，并且会在新 NULL 值到达目标之前拒绝它们。

🌐 After the table exists, BigQuery requires every newly added scalar, top-level column to be NULLABLE. If Postgres adds a NOT NULL column, Pipelines adds it as NULLABLE in BigQuery and logs a warning. Postgres remains the source of truth and rejects new NULL values before they reach the destination.

对于 Postgres DROP NOT NULL，Pipelines 会将现有的 BigQuery 列从 REQUIRED 放宽到 NULLABLE。对于 Postgres SET NOT NULL，BigQuery 无法将现有的 NULLABLE 列更改为 REQUIRED，所以 Pipelines 会保留目标列为可空并记录一个警告。

🌐 For Postgres DROP NOT NULL, Pipelines relaxes an existing BigQuery column from REQUIRED to NULLABLE. For Postgres SET NOT NULL, BigQuery cannot change an existing NULLABLE column to REQUIRED, so Pipelines leaves the destination column nullable and logs a warning.

列的默认值处理是独立于该列是否允许 NULL 的。BigQuery 不支持在已有表上使用 ADD COLUMN ... DEFAULT，所以 Pipelines 会先添加可为空的列，然后用单独的语句应用支持的默认元数据。这是针对将来在 BigQuery 写入时省略该列的目标元数据；管道写入已经包含由 Postgres 计算的值，而且元数据不会填充已有的目标行。不支持的默认值，包括目标主键列上的默认值，会以警告方式跳过，而不会导致复制失败。

🌐 Column defaults are handled independently from whether the column allows NULL. BigQuery does not support ADD COLUMN ... DEFAULT on an existing table, so Pipelines first adds the nullable column and then applies supported default metadata with a separate statement. This is destination metadata for future BigQuery writes that omit the column; pipeline writes already contain the value evaluated by Postgres, and the metadata doesn't populate existing destination rows. Unsupported defaults, including defaults on destination primary-key columns, are skipped with a warning instead of failing replication.

限制 #

🌐 Limitations

  • 行大小：由于 BigQuery 存储写入 API 的限制，每行最多 10 MB
  • 主键：源表必须有主键，复制的主键最多可以包含16列，BigQuery 不强制唯一性
  • 列：BigQuery CDC 最多支持 2,000 个顶层列
  • 副本标识：更新和删除需要支持的主键标识或 REPLICA IDENTITY FULL
  • 架构和表名：在复制到 BigQuery 时，源架构和表名不能以 _ 开头或结尾，也不能包含 " 或 ;
  • 数组和数值：数组不能包含 NULL 元素。超过 38 位小数的数值以及超出 BigQuery 支持范围的精确 JSON 整数值无法复制。
  • BigQuery CDC 表：在 CDC 激活时，BigQuery 不支持在目标表上执行变更 DML（UPDATE、DELETE 或 MERGE）、通配符表查询或搜索索引。完整列表请参见 BigQuery CDC 限制。
  • 托管的目标对象：不要删除或修改由 Pipelines 创建的表或视图。这样做可能会导致复制停止，并可能需要重新进行一次需要付费的初始同步。
  • 模式更改：仅限于上面列出的支持的模式更改

额外资源 #

🌐 Additional resources