使用 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
查询过程可以分为四步:
- 在 PostgreSQL 中创建外部服务器和外部表,并在外部表选项中配置 IRIS SQL。
- 应用执行
SELECT,Supabase Wrappers 调用 Wasm 组件。 - 组件向 IRIS Atelier API 发送 HTTP 请求,执行配置好的 SQL。
- 组件解析 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,让应用通过外部表访问预先定义的查询结果。
它适合用于受控数据集的原型验证和只读查询。对于更大数据量或生产部署,仍需结合分页、查询性能、凭据管理、网络安全和目标环境兼容性进行进一步评估。
参考资料: