文章 pan John · 十一月 3 5m read

使用 Wasm FDW 在 Supabase 中查询 InterSystems IRIS

在构建应用时,我们可能同时使用 Supabase 和 InterSystems IRIS:前者为应用提供基于 PostgreSQL 的后端服务,后者保存现有业务系统中的数据。如何让 PostgreSQL 查询到 IRIS 中的数据,是两套系统协作时经常遇到的问题。

iris-wasm-fdw 是一个面向这一场景的实验性项目。它使用 Supabase Wrappers 的 WebAssembly 外部数据包装器机制,通过 IRIS Atelier HTTP/JSON API 执行预先配置的 SQL,并将结果映射为 PostgreSQL 外部表。

项目目前适合结果集可控的只读查询和小规模试用。本文介绍它的工作方式、基本配置以及使用时需要注意的限制。

什么是 Wasm FDW?

PostgreSQL 的外部数据包装器(Foreign Data Wrapper,简称 FDW)允许用户将外部数据源映射为外部表。应用查询外部表时,包装器负责访问数据源并返回结果。

Supabase Wrappers 为这一机制提供了 WebAssembly 支持。开发者可以构建 Wasm 组件,由 Wrappers 扩展在 PostgreSQL 中加载;组件通过宿主提供的接口访问 HTTP API,并将数据交还给 PostgreSQL。

Supabase 也提供了一个 Postgres Wasm FDW 示例项目,展示如何使用 WIT 接口构建这样的组件。iris-wasm-fdw 沿用这一思路,将外部数据源换成了 InterSystems IRIS 的 Atelier API。

工作原理

项目的查询链路如下:

PostgreSQL / Supabase
        │
        ▼
  PostgreSQL 外部表
        │
        ▼
  Supabase Wrappers
        │
        ▼
  iris-wasm-fdw 组件
        │ HTTP/JSON
        ▼
  IRIS Atelier API
        │
        ▼
  InterSystems IRIS

查询过程可以分为四步:

  1. 在 PostgreSQL 中创建外部服务器和外部表,并在外部表选项中配置 IRIS SQL。
  2. 应用执行 SELECT,Supabase Wrappers 调用 Wasm 组件。
  3. 组件向 IRIS Atelier API 发送 HTTP 请求,执行配置好的 SQL。
  4. 组件解析 JSON 响应,将字段转换为外部表声明的 PostgreSQL 类型并返回。

例如,外部表可以配置一条带 TOP 的 IRIS 查询,应用随后使用普通的 PostgreSQL SELECT 读取结果。IRIS 仍然是数据源,Supabase 仍然使用 PostgreSQL;FDW 在查询时连接两者。

项目提供了什么?

当前实现包括:

  • 通过 HTTP(S) 和 Basic Auth 访问 IRIS Atelier API。
  • 将整数、浮点数、布尔值、文本、日期、时间戳和 JSON 映射到 PostgreSQL 类型。
  • 对 HTTP 错误、IRIS SQL 错误、缺失字段、类型不匹配和数值越界返回错误信息。
  • 使用固定的 Rust 工具链和依赖锁文件构建 Wasm 组件。

项目使用的 SQL 是在外部表中配置的静态 SQL。IRIS 返回字段的名称或别名需要与 PostgreSQL 外部表的列名一致。

构建 Wasm 组件

准备好 Rust 和 rustup 后,在项目目录中运行:

source "$HOME/.cargo/env"
bash scripts/setup-rust.sh
bash build.sh

项目使用 rust-toolchain.toml 固定 Rust 版本,并使用 cargo-component 0.13.2 构建。成功后,产物位于:

target/wasm32-unknown-unknown/release/iris_fdw.wasm

将该文件放到 PostgreSQL 所在环境能够访问的地址,并计算实际分发文件的 SHA256。例如,在 macOS 上运行:

shasum -a 256 target/wasm32-unknown-unknown/release/iris_fdw.wasm

配置外部服务器时需要使用这个校验和。

配置外部表

以下示例展示基本配置。执行前需要替换 Wasm 地址、校验和、IRIS 地址、账号和源表;同时确保 PostgreSQL 所在环境可以访问 IRIS API。

CREATE EXTENSION IF NOT EXISTS wrappers;

CREATE FOREIGN DATA WRAPPER wasm_wrapper
  HANDLER wasm_fdw_handler
  VALIDATOR wasm_fdw_validator;

CREATE SERVER iris_server
  FOREIGN DATA WRAPPER wasm_wrapper
  OPTIONS (
    fdw_package_url 'https://YOUR_HOST/iris_fdw.wasm',
    fdw_package_name 'intersystems:iris-fdw',
    fdw_package_version '0.1.0',
    fdw_package_checksum 'REPLACE_WITH_ACTUAL_SHA256',
    api_url 'https://YOUR_IRIS_HOST/api/atelier/v3',
    namespace 'USER',
    username 'YOUR_READ_ONLY_USER',
    password 'YOUR_PASSWORD'
  );

CREATE FOREIGN TABLE iris_people (
  name text
)
SERVER iris_server
OPTIONS (
  query 'SELECT TOP 100 Name AS name FROM Sample.Person'
);

SELECT * FROM iris_people;

如果环境中已经安装并配置了 Wasm 包装器,应复用现有对象;如果 Wrappers 安装在独立 schema 中,需要为 handler 和 validator 指定相应的 schema。

示例中使用 Name AS name,是为了让 IRIS 返回字段的别名与外部表列 name 对应。实际使用时,请将 Sample.Person 替换为目标 IRIS 命名空间中存在的表。

安全和数据类型

建议显式配置 API 地址、命名空间和账号,并使用权限受限的 IRIS 只读账号。组件本身不会检查配置的 SQL 是否只读,因此访问权限需要由 IRIS 账号控制。

Basic Auth 在明文 HTTP 上不会加密凭据;非本地连接应使用 HTTPS。示例中的密码存放在 PostgreSQL 外部服务器选项中,当前包装器没有实现独立的密钥管理。

数据类型方面,NUMERIC 当前通过 f64 传递,不能保证任意小数精度。对精度有严格要求时,可以让 IRIS 将数值作为字符串返回,并在外部表中映射为 TEXT。高精度 JSON 也需要关注宿主的数值精度限制;项目会拒绝检测到可能被静默舍入的 JSON 数值,并提示使用文本映射。

当前验证和限制

项目已在本地容器中使用 IRIS 2026.2、PostgreSQL 17 和 Supabase Wrappers 0.6.1 验证完整查询链路。此前的本地验证包括 32 项单元测试和 IRIS 到 PostgreSQL 的集成测试。

使用时还应考虑以下限制:

  • 查询是静态 SQL,没有参数绑定或占位符替换。
  • 没有自动分页,也不会自动将 PostgreSQL 的 WHERE、LIMIT 或排序条件下推到 IRIS。应在配置的 IRIS SQL 中设置过滤条件和合适的 TOP。
  • 响应缓存在内存中,因此应控制返回数据量。
  • 不支持通过外部表执行 INSERT、UPDATE 或 DELETE。
  • 不支持宿主触发的重新扫描;独立的重复查询可以执行,但某些依赖重新扫描的连接计划可能失败。

结语

iris-wasm-fdw 展示了一条将 InterSystems IRIS 数据接入 Supabase/PostgreSQL 查询的路径:使用 Wasm FDW 连接 Wrappers 和 IRIS Atelier API,让应用通过外部表访问预先定义的查询结果。

它适合用于受控数据集的原型验证和只读查询。对于更大数据量或生产部署,仍需结合分页、查询性能、凭据管理、网络安全和目标环境兼容性进行进一步评估。

参考资料: