拓冰网站定制 
Supabase Stripe Wrapper用 Postgres FDW 直接读写 Stripe 数据的技术详解【免费下载链接】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 仓库中 Stripe Wrapper 集成概览 为起点深入解析这个 Foreign Data Wrapper外部数据包装器的完整技术定义它的扩展、处理器与校验器命名、服务器级连接参数如api_key_id、api_url、Studio 中按表创建与外部 Schema两种使用模式、全部 27 个可映射的 Stripe 对象及其列结构以及它依赖的wrappers、supabase_vault前置扩展。读完后你将能够基于仓库中的真实元数据在自己的 Postgres 数据库中正确配置并查询 Stripe 的客户、订阅、发票与支付数据。什么是 Stripe Wrapper官方概览文档 给出的核心定义只有两句但信息密度很高Stripe 是一个 API 驱动的支付处理和订阅管理平台。Stripe Wrapper 是一个 Foreign Data Wrapper允许你在 Postgres 数据库内部直接从 Stripe 读取和写入数据。这意味着 Stripe 的账户数据不需要经过 ETL 管道或 Webhook 搬运就能以 Postgres 外表foreign table的形式出现在你的数据库里直接用 SQL 完成 JOIN、聚合和 BI 查询。读写两个方向都要注意既支持SELECT拉取 Stripe API 的对象列表也支持通过INSERT/UPDATE回写到 Stripe。在 Supabase Studio 的集成市场中该集成的标识为stripe_wrapper其展示描述为Payment processing and subscription management归类于billing分类。技术身份扩展、Handler 与 Validator从源码定义 Wrappers.constants.ts 可以看到每个 Wrapper 在 Postgres 侧都由三元组标识属性stripe_wrapper 的取值作用extensionNameStripeFdw需要安装的 Postgres 扩展handlerNamestripe_fdw_handlerCREATE SERVER ... HANDLER时指定的 FDW 处理函数validatorNamestripe_fdw_validator校验服务器/外表选项合法性的函数namestripe_wrapperStudio 内部集成标识docsUrl/guides/database/extensions/wrappers/stripe官方文档页在 WRAPPER_HANDLERS 映射表 中Stripe 与 Firebase、S3、ClickHouse、BigQuery、Airtable 等属于原生非 WASMFDW 处理器一列而 Paddle、Snowflake、Slack、Notion 等则统一走wasm_fdw_handler。这种区分说明 Stripe 使用的是针对其 REST API 专门实现的 C 层 FDW而非通用 WASM 封装。服务器级连接参数在 stripe_wrapper 的 server.options 定义 中连接 Stripe 需要配置以下三个服务器选项选项名表单标签必填说明api_key_idStripe Secret Key是Stripe 密钥encrypted: true且secureEntry: true表示 Studio 会以密文形式存入 Vault输入框为安全输入api_urlStripe API URL否默认值https://api.stripe.com/v1可覆盖以指向其他 API 端点supabase_target_schemaTarget Schema否隐藏且只读 的框架选项hidden: true, readOnly: true由 Studio 在后台自动写入用于指定外表落位的 target schema密钥通过encrypted标记说明其不直接落在CREATE SERVER的明文中而是经由 Supabase Vault 扩展托管——这也是下面前置扩展一节中supabase_vault成为必需项的原因。表单层面对这些选项做了强制校验Wrappers.utils.ts 的getWrapperCreationFormSchema会遍历server.options把所有required: true的选项即api_key_id编译为 Zod 必填字段可选项api_url编译为z.string().optional()。对应的单测 Wrappers.utils.test.ts 断言了缺少api_key_id时校验失败并定位到该字段而缺少api_url时不产生错误——与上面的参数表一一对应。两种使用模式Tables 模式与 Schema 模式创建 Wrapper 表单是一个以mode为判别字段的 discriminated union源码Tables 模式mode: tables逐表映射。用户从预定义的 Stripe 对象列表中选择要映射的对象每张外表需要table_name、所属schema可选custom 自定义schema_name、列集合columns以及该对象的object选项要求至少一张表。Schema 模式mode: schema整 Schema 映射。只需提供source_schemaStripe 侧源 schema与target_schemaPostgres 侧唯一目标 schema。stripe_wrapper 的 source_schema 选项 默认值为stripe。单测 Wrappers.utils.test.ts 明确验证了两个分支tables模式缺tables字段会报错schema模式缺source_schema/target_schema会报错。支持的 27 个 Stripe 对象stripe_wrapper 的 tables 数组 完整枚举了可映射的 Stripe API 对象每个对象由一个不可编辑、必填的object选项指向对应的 API 端点对象object默认值说明原文描述摘要AccountsaccountsStripe 账户下的账户列表Balancebalance账户当前余额Balance Transactionsbalance_transactions构成账户余额的交易Chargescharges已发生的扣款Checkout Sessionscheckout/sessionsCheckout/Payment Links 支付会话Customerscustomers客户Disputesdisputes客户向发卡机构发起的争议EventseventsStripe 账户内发生的事件Filesfiles托管在 Stripe 服务器上的文件File Linksfile_links与非 Stripe 用户共享文件的链接Invoicesinvoices发票Mandatesmandates客户授权扣款的凭证记录Metersbilling/meters计费中的用量计量事件Payment Intentspayment_intents支付意向Payoutspayouts提现/打款到银行账户或借记卡Pricesprices产品价格对象Productsproducts产品Refundsrefunds退款Setup Attemptssetup_attemptsSetupIntent 的确认尝试Setup Intentssetup_intents保存支付凭证的意向Subscriptionssubscriptions订阅Tokenstokens令牌Top-upstopups充值Transferstransfers转账列结构上有两点值得注意的设计固定列 attrsjsonb 列每张表都暴露少量强类型列id/text、金额类bigint、created/timestamp、状态类text、布尔bool等并统一附加一个attrsjsonb列承载 Stripe API 返回的完整 JSON。例如 Balance Transactions 表暴露id、amount、currency、fee、net、status、type、created之外其余字段全部收进attrs。这保证了常用字段有类型、有性能长尾字段又不丢失。rowid_column选项Accounts、Checkout Sessions、Customers、Products、Subscriptions 等对象额外提供可编辑的rowid_column默认id用于标识行身份支撑对 Stripe 的写回操作UPDATE/DELETE依赖它定位远端对象。前置扩展与版本约束Stripe Wrapper 并非开箱即用它依赖两个扩展这一点在 getRequiredExtensionsToInstall 及其测试中有明确定义wrappersFDW 框架核心扩展supabase_vault用于安全托管api_key_id等加密选项。Wrappers.utils.test.ts 验证了缺哪个补哪个的安装逻辑两个都已安装时返回空数组只装了supabase_vault时返回[wrappers]。另外hasForeignSchemaSupport 的单测界定了版本能力边界wrappers扩展 0.5.0 才支持外部 Schemaforeign schema模式0.4.9 及以下返回false。因此如果你要使用上文的 Schema 模式source_schema/target_schema应确认数据库中安装的wrappers版本满足该前提。与 Stripe Sync Engine 的分工同目录下还有一个近亲集成 stripe_sync_engine其官方描述是将 Stripe 账户中的 customers、subscriptions、invoices、payments 数据同步sync到 Supabase 账户的 Postgres 表。两者定位不同stripe_wrapper本文主题FDW数据实时代理查询时按需读写 Stripe适合交互式 SQL 分析、联表查询stripe_sync_engine同步引擎把数据物化到本地 Postgres 表适合需要本地持久副本的场景。在 Studio 集成市场里二者并列出现选择依据取决于实时代理还是物化副本。概览文档在 Studio 中的加载机制最后交代一下这份 overview.md 本身如何进入产品。overviews.ts 维护了一个以集成为键的惰性加载表stripe_wrapper的条目动态 import 本概览 Markdown文件头部注释解释了为什么必须写成字符串字面量webpack/turbopack 与 Vite/Rolldown 的 md-as-string 加载器next.config.ts 的 raw-loader 规则、vite.config.ts 的mdRawLoader插件只能静态分析字面量导入模板字符串写法会在 TanStack 构建中抛出TypeError: Failed to resolve module specifier。loadIntegrationOverview(integrationId)对没有概览的集成如 marketplace 应用返回null。配套的 overviews.test.ts 会断言这张映射表与磁盘上的overview.md文件保持同步——新增集成时overview.md与overviews.ts条目需要同时添加。小结Stripe Wrapper 让 Stripe 数据以标准 Postgres 外表的形式进入你的数据库由StripeFdw扩展、stripe_fdw_handler处理器与stripe_fdw_validator校验器构成技术底座通过api_key_idVault 加密托管与可选的api_url建立连接支持 27 个 Stripe 对象的逐表映射Tables 模式或整体 Schema 映射要求wrappers 0.5.0。所有参数、列与默认值均可在上述 Wrappers.constants.ts 与 Wrappers.utils.ts 中查证测试文件 Wrappers.utils.test.ts 则锁定了这些校验行为。【免费下载链接】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），仅供参考 Supabase Stripe Wrapper：用 Postgres FDW 直接读写 Stripe 数据的技术详解
Supabase Stripe Wrapper用 Postgres FDW 直接读写 Stripe 数据的技术详解【免费下载链接】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 仓库中 Stripe Wrapper 集成概览 为起点深入解析这个 Foreign Data Wrapper外部数据包装器的完整技术定义它的扩展、处理器与校验器命名、服务器级连接参数如api_key_id、api_url、Studio 中按表创建与外部 Schema两种使用模式、全部 27 个可映射的 Stripe 对象及其列结构以及它依赖的wrappers、supabase_vault前置扩展。读完后你将能够基于仓库中的真实元数据在自己的 Postgres 数据库中正确配置并查询 Stripe 的客户、订阅、发票与支付数据。什么是 Stripe Wrapper官方概览文档 给出的核心定义只有两句但信息密度很高Stripe 是一个 API 驱动的支付处理和订阅管理平台。Stripe Wrapper 是一个 Foreign Data Wrapper允许你在 Postgres 数据库内部直接从 Stripe 读取和写入数据。这意味着 Stripe 的账户数据不需要经过 ETL 管道或 Webhook 搬运就能以 Postgres 外表foreign table的形式出现在你的数据库里直接用 SQL 完成 JOIN、聚合和 BI 查询。读写两个方向都要注意既支持SELECT拉取 Stripe API 的对象列表也支持通过INSERT/UPDATE回写到 Stripe。在 Supabase Studio 的集成市场中该集成的标识为stripe_wrapper其展示描述为Payment processing and subscription management归类于billing分类。技术身份扩展、Handler 与 Validator从源码定义 Wrappers.constants.ts 可以看到每个 Wrapper 在 Postgres 侧都由三元组标识属性stripe_wrapper 的取值作用extensionNameStripeFdw需要安装的 Postgres 扩展handlerNamestripe_fdw_handlerCREATE SERVER ... HANDLER时指定的 FDW 处理函数validatorNamestripe_fdw_validator校验服务器/外表选项合法性的函数namestripe_wrapperStudio 内部集成标识docsUrl/guides/database/extensions/wrappers/stripe官方文档页在 WRAPPER_HANDLERS 映射表 中Stripe 与 Firebase、S3、ClickHouse、BigQuery、Airtable 等属于原生非 WASMFDW 处理器一列而 Paddle、Snowflake、Slack、Notion 等则统一走wasm_fdw_handler。这种区分说明 Stripe 使用的是针对其 REST API 专门实现的 C 层 FDW而非通用 WASM 封装。服务器级连接参数在 stripe_wrapper 的 server.options 定义 中连接 Stripe 需要配置以下三个服务器选项选项名表单标签必填说明api_key_idStripe Secret Key是Stripe 密钥encrypted: true且secureEntry: true表示 Studio 会以密文形式存入 Vault输入框为安全输入api_urlStripe API URL否默认值https://api.stripe.com/v1可覆盖以指向其他 API 端点supabase_target_schemaTarget Schema否隐藏且只读 的框架选项hidden: true, readOnly: true由 Studio 在后台自动写入用于指定外表落位的 target schema密钥通过encrypted标记说明其不直接落在CREATE SERVER的明文中而是经由 Supabase Vault 扩展托管——这也是下面前置扩展一节中supabase_vault成为必需项的原因。表单层面对这些选项做了强制校验Wrappers.utils.ts 的getWrapperCreationFormSchema会遍历server.options把所有required: true的选项即api_key_id编译为 Zod 必填字段可选项api_url编译为z.string().optional()。对应的单测 Wrappers.utils.test.ts 断言了缺少api_key_id时校验失败并定位到该字段而缺少api_url时不产生错误——与上面的参数表一一对应。两种使用模式Tables 模式与 Schema 模式创建 Wrapper 表单是一个以mode为判别字段的 discriminated union源码Tables 模式mode: tables逐表映射。用户从预定义的 Stripe 对象列表中选择要映射的对象每张外表需要table_name、所属schema可选custom 自定义schema_name、列集合columns以及该对象的object选项要求至少一张表。Schema 模式mode: schema整 Schema 映射。只需提供source_schemaStripe 侧源 schema与target_schemaPostgres 侧唯一目标 schema。stripe_wrapper 的 source_schema 选项 默认值为stripe。单测 Wrappers.utils.test.ts 明确验证了两个分支tables模式缺tables字段会报错schema模式缺source_schema/target_schema会报错。支持的 27 个 Stripe 对象stripe_wrapper 的 tables 数组 完整枚举了可映射的 Stripe API 对象每个对象由一个不可编辑、必填的object选项指向对应的 API 端点对象object默认值说明原文描述摘要AccountsaccountsStripe 账户下的账户列表Balancebalance账户当前余额Balance Transactionsbalance_transactions构成账户余额的交易Chargescharges已发生的扣款Checkout Sessionscheckout/sessionsCheckout/Payment Links 支付会话Customerscustomers客户Disputesdisputes客户向发卡机构发起的争议EventseventsStripe 账户内发生的事件Filesfiles托管在 Stripe 服务器上的文件File Linksfile_links与非 Stripe 用户共享文件的链接Invoicesinvoices发票Mandatesmandates客户授权扣款的凭证记录Metersbilling/meters计费中的用量计量事件Payment Intentspayment_intents支付意向Payoutspayouts提现/打款到银行账户或借记卡Pricesprices产品价格对象Productsproducts产品Refundsrefunds退款Setup Attemptssetup_attemptsSetupIntent 的确认尝试Setup Intentssetup_intents保存支付凭证的意向Subscriptionssubscriptions订阅Tokenstokens令牌Top-upstopups充值Transferstransfers转账列结构上有两点值得注意的设计固定列 attrsjsonb 列每张表都暴露少量强类型列id/text、金额类bigint、created/timestamp、状态类text、布尔bool等并统一附加一个attrsjsonb列承载 Stripe API 返回的完整 JSON。例如 Balance Transactions 表暴露id、amount、currency、fee、net、status、type、created之外其余字段全部收进attrs。这保证了常用字段有类型、有性能长尾字段又不丢失。rowid_column选项Accounts、Checkout Sessions、Customers、Products、Subscriptions 等对象额外提供可编辑的rowid_column默认id用于标识行身份支撑对 Stripe 的写回操作UPDATE/DELETE依赖它定位远端对象。前置扩展与版本约束Stripe Wrapper 并非开箱即用它依赖两个扩展这一点在 getRequiredExtensionsToInstall 及其测试中有明确定义wrappersFDW 框架核心扩展supabase_vault用于安全托管api_key_id等加密选项。Wrappers.utils.test.ts 验证了缺哪个补哪个的安装逻辑两个都已安装时返回空数组只装了supabase_vault时返回[wrappers]。另外hasForeignSchemaSupport 的单测界定了版本能力边界wrappers扩展 0.5.0 才支持外部 Schemaforeign schema模式0.4.9 及以下返回false。因此如果你要使用上文的 Schema 模式source_schema/target_schema应确认数据库中安装的wrappers版本满足该前提。与 Stripe Sync Engine 的分工同目录下还有一个近亲集成 stripe_sync_engine其官方描述是将 Stripe 账户中的 customers、subscriptions、invoices、payments 数据同步sync到 Supabase 账户的 Postgres 表。两者定位不同stripe_wrapper本文主题FDW数据实时代理查询时按需读写 Stripe适合交互式 SQL 分析、联表查询stripe_sync_engine同步引擎把数据物化到本地 Postgres 表适合需要本地持久副本的场景。在 Studio 集成市场里二者并列出现选择依据取决于实时代理还是物化副本。概览文档在 Studio 中的加载机制最后交代一下这份 overview.md 本身如何进入产品。overviews.ts 维护了一个以集成为键的惰性加载表stripe_wrapper的条目动态 import 本概览 Markdown文件头部注释解释了为什么必须写成字符串字面量webpack/turbopack 与 Vite/Rolldown 的 md-as-string 加载器next.config.ts 的 raw-loader 规则、vite.config.ts 的mdRawLoader插件只能静态分析字面量导入模板字符串写法会在 TanStack 构建中抛出TypeError: Failed to resolve module specifier。loadIntegrationOverview(integrationId)对没有概览的集成如 marketplace 应用返回null。配套的 overviews.test.ts 会断言这张映射表与磁盘上的overview.md文件保持同步——新增集成时overview.md与overviews.ts条目需要同时添加。小结Stripe Wrapper 让 Stripe 数据以标准 Postgres 外表的形式进入你的数据库由StripeFdw扩展、stripe_fdw_handler处理器与stripe_fdw_validator校验器构成技术底座通过api_key_idVault 加密托管与可选的api_url建立连接支持 27 个 Stripe 对象的逐表映射Tables 模式或整体 Schema 映射要求wrappers 0.5.0。所有参数、列与默认值均可在上述 Wrappers.constants.ts 与 Wrappers.utils.ts 中查证测试文件 Wrappers.utils.test.ts 则锁定了这些校验行为。【免费下载链接】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），仅供参考