Supabase S3 Wrapper 完全指南：用只读外表把 S3 对象存储变成 Postgres 可查询的表

Supabase S3 Wrapper 完全指南：用只读外表把 S3 对象存储变成 Postgres 可查询的表

【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase

本文基于 Supabase 仓库中 Studio 控制台内置的 S3 Wrapper 集成文档 overview.md 展开，系统讲解 S3 Wrapper 支持的文件格式与压缩算法、CSV/JSONL/Parquet 各自的类型与内存限制，并结合 Studio 前端源码、仪表盘配置项与端到端测试，还原在 Supabase Dashboard 中创建 S3 Wrapper 的完整流程与安全注意事项。

一、S3 Wrapper 是什么：只读的对象存储外表

S3 Wrapper 是 Supabase 基于 Foreign Data Wrapper（FDW）体系封装的 AWS S3 集成。按官方集成文档的原文定义：

AWS S3 is an object storage service offering industry-leading scalability, data availability, security, and performance. It isread-onlyand supports below file formats.

也就是说，S3 Wrapper 的定位是只读——你可以把 S3 Bucket 中的文件映射为 Postgres 外表并直接SELECT查询，但不能通过它向 S3 写入数据。这一点在配置 UI 中也能得到印证：s3_wrapper在 Wrappers.constants.ts 中注册的外表模板只有一个 "S3 File"，没有任何写入型选项。

支持的文件格式

支持的压缩算法

S3 Wrapper 在读取上述文件时支持四种压缩算法：

• gzip
• bzip2
• xz
• zlib

两条重要的使用限制（原文档核心约束）

原文档给出了两条必须牢记的限制，直接决定了实际可用性：

1. CSV 与 JSONL 文件：S3 文件中的所有列都必须在外表中显式定义，且列类型必须是text。这意味着查询时如果需要数值、日期等类型，要在 SQL 层自行转换（如col::int），而不能指望外表直接给出强类型。
2. Parquet 文件：如果 Parquet 文件是压缩过的，整个文件会被一次性加载进本地内存，因此应尽可能控制文件大小，避免大文件压缩 Parquet 造成内存压力。

这两条限制是原文档中最具实战价值的部分——前者影响建表 DDL 的写法（全部列声明为text），后者影响数据文件的组织策略（大文件建议不压缩或拆分）。

二、Studio 中的文档注册机制：overview.md 如何被控制台读取

这份overview.md并非孤立的静态文件，它是 Studio「集成总览」页面的内容源。从源码结构看，其加载链路如下：

1. 注册表：overviews.ts 维护了一个以集成 id 为键、懒加载 markdown 的映射，其中 S3 Wrapper 的条目为s3_wrapper: () => import('@/static-data/integrations/s3_wrapper/overview.md')（第 41 行）。
2. 加载函数：同文件的loadIntegrationOverview(integrationId)（第 58–63 行）在仪表盘路由/project/:ref/integrations/s3_wrapper/overview被访问时异步取回该 markdown 字符串；没有配套 overview 的集成（如 marketplace apps）则返回null。
3. 同步保证：overviews.test.ts 断言注册表映射与磁盘文件保持同步——新增overview.md时必须在注册表中补登记。
4. 构建约束：注册表文件头部注释解释了为何 import 说明符必须是字符串字面量而非模板字符串：webpack/turbopack 依赖静态分析做代码拆分，而 Vite/Rolldown（TanStack 构建）不处理模板字符串动态 import，会在运行时抛TypeError: Failed to resolve module specifier。

理解这一机制的价值在于：你看到s3_wrapper/overview.md里描述的格式与压缩能力，正是控制台 UI 对该 Wrapper 的能力声明；当文档与 UI 行为不一致时（见下文 format 选项差异），可以沿这条链路定位是前端元数据还是文档需要更新。

三、在 Dashboard 中创建 S3 Wrapper：配置项全解

S3 Wrapper 在 Studio 中的完整元数据定义在 Wrappers.constants.ts 的WRAPPERS数组中：

{ name: 's3_wrapper', handlerName: 's3_fdw_handler', // 底层 FDW handler validatorName: 's3_fdw_validator', extensionName: 'S3Fdw', // 关联的 Postgres 扩展 label: 'S3', description: 'Cloud object storage service', docsUrl: `${DOCS_URL}/guides/database/extensions/wrappers/s3`, categories: ['storage'], server: { options: [ /* 见下 */ ] }, tables: [ { label: 'S3 File', /* 见下 */ } ], }

3.1 Server 选项（连接凭据）

注意选项名中的vault_前缀：Supabase 使用vault扩展把密钥写入vault.secrets表，FDW 运行时从 Vault 读取凭据，而不是把明文密钥写进foreign server的 options 里。端到端测试的清理逻辑直接印证了这一点——见 wrappers.spec.ts 第 106–108 行：

delete from vault.secrets where name = '${wrapperName}_vault_access_key_id'; delete from vault.secrets where name = '${wrapperName}_vault_secret_access_key';

即密钥在 Vault 中的命名规则为{wrapper_name}_vault_access_key_id与{wrapper_name}_vault_secret_access_key。

3.2 外表（Foreign Table）选项

外表模板 "S3 File"（描述为 "Map to a file in S3"）提供以下选项：

一个值得注意的差异：overview 文档声明底层 Wrapper 支持 CSV、JSONL、Parquet 三种格式与四种压缩算法，而当前 UI 的format下拉只暴露了csv和jsonl，compress也只暴露gzip。从源码结构看，这说明仪表盘 UI 元数据是底层能力的子集——如果你需要 Parquet 或非 gzip 压缩（bzip2/xz/zlib），可以绕过 UI 直接用 SQL 创建外表，在options (format 'parquet', compress 'xz')中指定（该能力以原文档的能力声明为准）。UI 未暴露只是界面层面的收敛。

四、端到端测试还原的完整创建流程

wrappers.spec.ts 中的 "can create an S3 wrapper" 用例完整走了一遍仪表盘创建流程，可视为操作步骤的可执行版本：

1. 前置：create extension if not exists wrappers schema extensions version '0.6.2' cascade;（测试使用的 Wrappers 扩展版本为 0.6.2）；
2. 打开/project/{ref}/integrations/s3_wrapper/overview，点击Add new wrapper；
3. 填写Wrapper Name（如test_s3_wrapper）、Access Key ID、Access Key Secret；
4. 点击Add foreign table，在模板下拉中选择S3 File；
5. 填写Table name（如test_s3_wrapper_table）与URI（如s3://bucket/s3_table.csv）；
6. 点击Add column添加列（如s3_column，对应上文「所有列必须显式定义且为 text 类型」的要求）；
7. Save保存外表定义，Create wrapper创建 Wrapper；
8. 断言出现 "Successfully created S3 foreign data wrapper" 提示。

测试用withSetupCleanup包裹，结束后会drop foreign data wrapper ... cascade并清理 Vault 密钥与测试表，这套清理序列也说明了 S3 Wrapper 的资源三件套：foreign data wrapper + vault secrets + 映射的外表。

五、底层机制：s3_fdw_handler 与只读语义

从 Wrappers.constants.ts 的WRAPPER_HANDLERS映射表可见，各集成与底层 FDW handler 的对应关系：

S3: 's3_fdw_handler', S3_VECTORS: 's3_vectors_fdw_handler',

S3: 's3_fdw_handler'表明 S3 Wrapper 在数据库侧是名为s3_fdw_handler的 FDW handler，配套验证器为s3_fdw_validator，关联扩展为S3Fdw（extensionName字段）。创建 Dashboard Wrapper 本质上是生成一组 DDL：CREATE FOREIGN DATA WRAPPER ... HANDLER s3_fdw_handler VALIDATOR s3_fdw_validator、CREATE SERVER（凭据走 Vault）、CREATE FOREIGN TABLE（带uri/format/has_header/compress选项）。

「只读」语义与整体 Wrappers 生态一致：Supabase 文档站对 FDW 的总述 overview.mdx 解释了 FDW 的核心概念——Remote Server（如 S3 这类外部数据系统）与 Foreign Table（数据仍留在远端、只是映射进 Postgres 的表）。S3 Wrapper 正是「把 S3 对象作为 Remote Server 上的数据源」这一模式的落地。

六、安全与使用建议

Supabase 的 FDW 文档 overview.mdx 在「Security」一节给出了适用于所有 Wrapper（含 S3 Wrapper）的通用安全准则，这里继承三条关键建议：

1. FDW 不提供 Row Level Security：不要把 foreign server / foreign table 直接暴露到 Supabase API。
2. 存放在私有 schema：所有 S3 相关外表应放在专用私有 schema 中，且该 schema 不应加入 API 设置里的 "Additional Schemas"。
3. 确需对外暴露时走 security definer 函数：在publicschema 创建security definer函数查询外表并附加过滤条件，同时用revoke execute ... from public/anon+grant execute ... to authenticated收窄执行权限。

结合 S3 场景补充一点：由于凭据由 Vault 加密保管（vault_access_key_id/vault_secret_access_key），建议 AWS 侧对该 Access Key 只授予目标 Bucket 的s3:GetObject读取权限，与 Wrapper 的只读定位保持一致。

七、与 S3 Vectors Wrapper 的区分

仓库中还有一个易混淆的姊妹集成 s3_vectors_wrapper/overview.md：

AWS S3 Vectors is a managed service that stores and queries high-dimensional vectors at scale... The S3 Vectors Wrapper allows you toread, write, and perform vector similarity searchoperations on S3 Vectors within your Postgres database.

两者定位差异清晰：

如果你要做向量检索（AI 场景），应选择 S3 Vectors Wrapper；如果只是把数据文件（报表 CSV、日志 JSONL、分析用 Parquet）直接纳入 SQL 查询，则使用本文所述的 S3 Wrapper。

八、如何获取更完整的官方文档

S3 Wrapper 的详细操作文档并不内置于本仓库。从 wrappers.ts 的联邦内容源映射可见，文档站构建时会从外部 Wrappers 仓库拉取s3.md并映射到本地 slugs3，同时通过dashboardIntegrationPath: 's3_wrapper'与控制台集成页互链；Studio 侧s3_wrapper的docsUrl也指向guides/database/extensions/wrappers/s3这一路由。因此完整建表 DDL、参数取值范围等细节应以该文档页为准，本文则以仓库内可直接验证的集成元数据、能力声明与测试用例为证据边界。

小结

• 能力边界：S3 Wrapper 只读，支持 CSV（含/不含表头）、JSONL、Parquet，压缩支持 gzip/bzip2/xz/zlib；
• 两条硬限制：CSV/JSONL 所有列须在外表中定义且为text类型；压缩 Parquet 整文件加载进内存，文件宜小；
• 配置要点：Vault 加密的 Access Key ID/Secret +aws_region（默认us-east-1）+ 外表选项uri/format/has_header/compress；
• UI 与底层差异：界面仅暴露 csv/jsonl 与 gzip，Parquet 与其他压缩算法需通过 SQL 直接建表使用；
• 安全基线：私有 schema 隔离、不加入 API Additional Schemas、必要时用 security definer 函数收窄暴露面。

【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase