Supabase Studio Cloudflare D1 Wrapper（cfd1_wrapper）概览：用 Wasm FDW 在 Postgres 中读写 D1 数据

本文以 Supabase Studio 集成的 cfd1_wrapper（Cloudflare D1 Wrapper）官方概览文档为主体，结合仓库中该集成的完整常量定义、文档加载注册表与文档联邦配置，说明如何通过 WebAssembly 外部数据包装器（Wasm FDW）从 Supabase 的 Postgres 数据库中直接查询和写入 Cloudflare D1 数据，包括其功能边界、全部服务器选项与外表定义、凭据的安全存储方式，以及 Studio 与文档站点如何消费这份概览文档。

Cloudflare D1 与 D1 Wrapper 是什么

Cloudflare D1 是 Cloudflare 提供的托管、无服务器（serverless）数据库，它具备以下特征（来自集成概览文档）：

• 使用 SQLite 的 SQL 语义；
• 内置灾难恢复（disaster recovery）；
• 可通过 Worker 和 HTTP API 两种方式访问。

而 Cloudflare D1 Wrapper 是一个 WebAssembly（Wasm）外部数据包装器（foreign data wrapper, FDW），它允许你在自己的 Postgres 数据库中直接读取和写入 Cloudflare D1 数据库中的数据。也就是说，你不需要在应用层写同步代码，而是把 D1 当作 Postgres 中的一个“外部数据源”，用标准 SQL 完成跨库访问。

该集成的概览文档位于 cfd1_wrapper/overview.md，它在 Studio 的集成目录中对应 ID 为 cfd1_wrapper 的集成，标签为 “Cloudflare D1”。

核心功能

概览文档列出的四项核心功能如下，本节逐项展开并结合仓库中的实现佐证。

1. 直接用 SQL 查询 D1 数据库

在 Postgres 中创建对应 D1 数据的外部表（foreign table）后，即可用普通 SQL 查询 D1 中的数据，无需应用层中转。

2. 支持对 D1 表的读与写

与普通只读联邦查询不同，该 Wrapper 同时支持读和写 D1 表。仓库中集成的描述字符串也印证了这一点：Wrappers.constants.ts 中该集成的 description 为 “Read and write data from Cloudflare D1 databases using the Wasm FDW.”

3. 通过 Supabase Vault 安全存储凭据

访问 D1 需要 Cloudflare 的 API Token。从源码结构看，Wrappers.constants.ts 中该集成唯一的 api_token_id 选项被声明为：

• required: true（必填）；
• encrypted: true（加密存储）；
• secureEntry: true（安全输入项）。

这三项标记意味着该 Token 不是以明文形式保存在外部表定义中，而是经由 Supabase Vault 加密管理，这正是概览文档中 “Secure credential storage via Supabase Vault” 的落地方式。

4. 支持查询下推（query pushdown）

概览文档明确列出支持的下推子句：where、order by、limit。即这些过滤与限制条件会被下推到 D1 侧执行，而不是把全量数据拉回 Postgres 再在本地过滤，从而减少数据传输量。

集成的完整配置结构（来自 Studio 常量定义）

概览文档描述了“能做什么”，而 Wrappers.constants.ts 中 name: 'cfd1_wrapper' 的条目则定义了 Studio 集成面板（Dashboard）创建该 Wrapper 时的全部服务器选项与外表定义，是理解该集成实际参数面的关键。

集成的基础元信息

字段	值	说明
name	cfd1_wrapper	集成 ID，即静态文档目录名
label	Cloudflare D1	面板展示名称
handlerName	WRAPPER_HANDLERS.CLOUDFLARE_D1	对应的 Wrapper 处理器
validatorName	wasm_fdw_validator	选项校验器（Wasm FDW 通用校验器）
extensionName	Cfd1Fdw	Postgres 侧扩展名
categories	['data-platform']	集成分类：数据平台
minimumExtensionVersion	0.4.0	要求的基础设施扩展最低版本

服务器（Server）选项

服务器选项分为两类：一类是 Wasm 包本身的定位参数（对用户在界面上隐藏），一类是需要用户填写的 D1 连接参数。

Wasm 包定位参数（默认隐藏，hidden: true）

选项名	默认值	作用
fdw_package_url	wrappers 项目 v0.1.0 发布产物 cfd1_fdw.wasm 的下载 URL	Wasm 包下载来源
fdw_package_name	supabase:cfd1-fdw	Wasm 包名称
fdw_package_version	0.1.0	Wasm 包版本
fdw_package_checksum	783232834bb29dbd3ee6b09618c16f8a847286e63d05c54397d56c3e703fad31	Wasm 包 SHA-256 校验和，用于校验包完整性

这四个字段对应 Wasm FDW 的通用加载机制：Postgres 侧的 wasm_fdw 机制按名称、版本定位 Wasm 包，并用校验和验证其未被篡改。由于这些值在 Studio 中预填并隐藏，用户在界面上不需要关心它们。

D1 连接参数（用户需填写）

选项名	是否必填	是否加密	默认值 / 说明
api_url	否	否	默认为 Cloudflare D1 数据库 HTTP API 端点 https://api.cloudflare.com/client/v4/accounts/<account_id>/d1/database
account_id	是	否	Cloudflare 账户 ID
database_id	是	否	目标 D1 数据库 ID
api_token_id	是	是（Vault）	Cloudflare D1 API Token，加密存储于 Supabase Vault

可以看到，连接一个 D1 数据库本质上只需要四个业务参数：api_url（可省）、account_id、database_id 和加密的 api_token_id，与概览文档描述的 “Worker 和 HTTP API 访问” 中 HTTP API 路径相对应。

外表（Foreign Table）定义

该集成的 tables 配置定义了两类可创建的外部表：

1. D1 Databases（元数据表）：table 选项被固定为 _meta_databases（editable: false），列出该 Cloudflare 账户下的所有 D1 数据库。可用列（见 Wrappers.constants.ts）：

   列名	类型	含义
   uuid	text	数据库 UUID
   name	text	数据库名称
   version	text	版本
   num_tables	bigint	表数量
   file_size	bigint	文件大小
   created_at	text	创建时间
   _attrs	jsonb	原始属性 JSON

2. D1 Table（业务表）：table 选项可编辑（如 mytable），列定义需要与你的 D1 schema 对齐，例如 id（bigint）、name（text）、amount（double precision）、metadata（text）、_attrs（jsonb）；另有一个可选项 rowid_column（默认 id，可编辑、非必填），用于指定 D1 表中的行 ID 列。

概览文档在 Studio 中的加载机制

overview.md 并不是死内容，它被 Studio 以代码分割的方式按需加载。overviews.ts 维护了一张“集成 ID → overview 懒加载函数”的注册表，其中 cfd1_wrapper 对应：

cfd1_wrapper: () => import('@/static-data/integrations/cfd1_wrapper/overview.md'),

该文件源码注释还说明了两个工程细节，可帮助理解该文档在整个构建链路中的位置：

• 导入说明符必须保持为字符串字面量，因为 Next.js（next.config.ts 中的 raw-loader 规则）与 TanStack/Vite（vite.config.ts 中的 mdRawLoader 插件）两种构建链都只能对可静态分析的导入应用“md 作为字符串”的加载逻辑；
• overviews.test.ts 会断言该注册表与磁盘上的文件保持同步——新增 overview.md 时必须同步添加条目。

运行时，Studio 调用 loadIntegrationOverview('cfd1_wrapper') 即可拿到本文所依据的 Markdown 原文并在集成详情页渲染，未注册的集成（如 marketplace 应用）则返回 null。

与文档站点的关联：联邦内容构建

Supabase 文档站（apps/docs）中 “Cloudflare D1” 的 Wrapper 文档页并非直接存放在本仓库，而是构建时从外部的 wrappers 仓库联邦拉取。在 wrappers.ts 中可以看到对应映射：

• 站点路径（section）：database/extensions/wrappers；
• 页面 slug：cloudflare-d1，页面标题 “Cloudflare D1”；
• dashboardIntegrationPath: 'cfd1_wrapper'，与 Studio 中的集成 ID 对应；
• 远端文件：cfd1.md（来自 wrappers 仓库 docs/catalog 目录，按 docs_vX.Y.Z 文档 tag 拉取）。

这说明 Studio 概览文档与文档站的 Wrapper 页面通过 cfd1_wrapper 这一集成 ID 形成双端关联：Studio 展示轻量概览与创建面板，文档站承载完整教程。

使用前提与限制

结合仓库中的常量定义，使用本 Wrapper 的前提包括：

1. 扩展版本要求：minimumExtensionVersion: '0.4.0'，基础设施侧的 Wrapper 基础扩展需不低于 0.4.0；
2. Wasm 包完整性校验：加载 Wasm 包时会使用 fdw_package_checksum 做校验和验证，校验不通过则无法加载；
3. 凭据要求：必须提供一个具备 D1 访问权限的 Cloudflare API Token，该 Token 以加密方式存入 Supabase Vault，而非明文写进外部表；
4. 表结构对齐：创建业务外部表时，Postgres 侧列定义需与 D1 中的 schema 匹配，并可显式指定 rowid_column（默认 id）以便正确定位行；
5. 下推能力边界：从概览文档列出的能力看，当前明确支持的下推子句为 where、order by、limit，其他复杂子句的执行位置以实际计划为准。

小结

cfd1_wrapper 是 Supabase Studio 集成目录中“数据平台”类别的一个 Wasm FDW 集成：它把 Cloudflare D1 暴露为 Postgres 中的可读写外部数据源，支持 where/order by/limit 查询下推，并通过 Supabase Vault 加密托管 Cloudflare API Token。其概览文档（overview.md）由 overviews.ts 注册表按需加载，完整参数面定义在 Wrappers.constants.ts 中，文档站对应页面则由联邦内容管线从 wrappers 仓库构建期拉取。若要在自己的 Supabase 项目中使用，按上述服务器选项（api_url、account_id、database_id、加密的 api_token_id）在 Studio 集成面板创建即可，业务表列结构需与 D1 schema 对齐。