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 WrapperFDW体系封装的 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没有任何写入型选项。支持的文件格式格式说明CSV支持带表头header line与不带表头两种情况JSON LinesJSONL每行一个 JSON 对象的流式格式ParquetApache Parquet 列式存储格式支持的压缩算法S3 Wrapper 在读取上述文件时支持四种压缩算法gzipbzip2xzzlib两条重要的使用限制原文档核心约束原文档给出了两条必须牢记的限制直接决定了实际可用性CSV 与 JSONL 文件S3 文件中的所有列都必须在外表中显式定义且列类型必须是text。这意味着查询时如果需要数值、日期等类型要在 SQL 层自行转换如col::int而不能指望外表直接给出强类型。Parquet 文件如果 Parquet 文件是压缩过的整个文件会被一次性加载进本地内存因此应尽可能控制文件大小避免大文件压缩 Parquet 造成内存压力。这两条限制是原文档中最具实战价值的部分——前者影响建表 DDL 的写法全部列声明为text后者影响数据文件的组织策略大文件建议不压缩或拆分。二、Studio 中的文档注册机制overview.md 如何被控制台读取这份overview.md并非孤立的静态文件它是 Studio「集成总览」页面的内容源。从源码结构看其加载链路如下注册表overviews.ts 维护了一个以集成 id 为键、懒加载 markdown 的映射其中 S3 Wrapper 的条目为s3_wrapper: () import(/static-data/integrations/s3_wrapper/overview.md)第 41 行。加载函数同文件的loadIntegrationOverview(integrationId)第 58–63 行在仪表盘路由/project/:ref/integrations/s3_wrapper/overview被访问时异步取回该 markdown 字符串没有配套 overview 的集成如 marketplace apps则返回null。同步保证overviews.test.ts 断言注册表映射与磁盘文件保持同步——新增overview.md时必须在注册表中补登记。构建约束注册表文件头部注释解释了为何 import 说明符必须是字符串字面量而非模板字符串webpack/turbopack 依赖静态分析做代码拆分而 Vite/RolldownTanStack 构建不处理模板字符串动态 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_access_key_idAccess Key ID是—AWS Access Key IDencrypted: true通过 Vault 加密存储vault_secret_access_keyAccess Key Secret是—AWS Secret Access Key同样加密入 Vaultaws_regionAWS Region是us-east-1S3 所在区域明文存储注意选项名中的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提供以下选项选项名界面标签类型默认值说明uriURItext—S3 对象地址占位示例s3://bucket/s3_table.csvformatFormatselectcsv取值csv/jsonlJSON Lineshas_headerHas HeaderselecttrueCSV 是否带表头行compressCompressionselect空界面仅提供gzip一项一个值得注意的差异overview 文档声明底层 Wrapper 支持 CSV、JSONL、Parquet 三种格式与四种压缩算法而当前 UI 的format下拉只暴露了csv和jsonlcompress也只暴露gzip。从源码结构看这说明仪表盘 UI 元数据是底层能力的子集——如果你需要 Parquet 或非 gzip 压缩bzip2/xz/zlib可以绕过 UI 直接用 SQL 创建外表在options (format parquet, compress xz)中指定该能力以原文档的能力声明为准。UI 未暴露只是界面层面的收敛。四、端到端测试还原的完整创建流程wrappers.spec.ts 中的 can create an S3 wrapper 用例完整走了一遍仪表盘创建流程可视为操作步骤的可执行版本前置create extension if not exists wrappers schema extensions version 0.6.2 cascade;测试使用的 Wrappers 扩展版本为 0.6.2打开/project/{ref}/integrations/s3_wrapper/overview点击Add new wrapper填写Wrapper Name如test_s3_wrapper、Access Key ID、Access Key Secret点击Add foreign table在模板下拉中选择S3 File填写Table name如test_s3_wrapper_table与URI如s3://bucket/s3_table.csv点击Add column添加列如s3_column对应上文「所有列必须显式定义且为 text 类型」的要求Save保存外表定义Create wrapper创建 Wrapper断言出现 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关联扩展为S3FdwextensionName字段。创建 Dashboard Wrapper 本质上是生成一组 DDLCREATE 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的通用安全准则这里继承三条关键建议FDW 不提供 Row Level Security不要把 foreign server / foreign table 直接暴露到 Supabase API。存放在私有 schema所有 S3 相关外表应放在专用私有 schema 中且该 schema 不应加入 API 设置里的 Additional Schemas。确需对外暴露时走 security definer 函数在publicschema 创建security definer函数查询外表并附加过滤条件同时用revoke execute ... from public/anongrant 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.mdAWS 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.两者定位差异清晰维度s3_wrappers3_vectors_wrapper目标通用 S3 对象CSV/JSONL/Parquet 文件AWS S3 Vectors 托管向量服务读写只读读、写、向量相似度检索FDW handlers3_fdw_handlers3_vectors_fdw_handlerServer 额外选项—endpoint_url、supabase_target_schema分类storageai_vectors、storage如果你要做向量检索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/compressUI 与底层差异界面仅暴露 csv/jsonl 与 gzipParquet 与其他压缩算法需通过 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考