iris-wasm-fdw

English | 简体中文

Query InterSystems IRIS from Supabase/Postgres using a WebAssembly foreign data wrapper. The wrapper sends static SQL to the IRIS Atelier HTTP/JSON API and exposes the results as PostgreSQL foreign tables.

Postgres foreign table → Supabase Wrappers → Wasm FDW → IRIS Atelier API

Features

• Basic authentication over HTTP(S).
• Integer, floating-point, boolean, text, date, timestamp, timestamptz and JSON mappings.
• Explicit errors for HTTP failures, IRIS SQL errors, invalid types and numeric range violations.
• A release Wasm component built with a pinned Rust toolchain and locked dependencies.

The current implementation is intended for small-scale trials and read queries with a bounded result set.

Requirements

• An IRIS instance with the Atelier API enabled and a user authorized to query the selected namespace.
• PostgreSQL with the Supabase Wrappers extension and Wasm support.
• A reachable API URL from the PostgreSQL host or container.
• Rust installed through rustup and cargo-component 0.13.2 for building.

Validated locally with IRIS 2026.2, PostgreSQL 17 and Wrappers 0.6.1. Other versions need their own compatibility checks.
This validation used local containers, not a hosted Supabase project.

For a step-by-step isolated Docker walkthrough with synthetic data and expected results, see Reproduce the IRIS query.

Build

The v0.1.0 release provides the Wasm component and its SHA256 checksum. You can also build from source:

Clone or download this project, then run from its root:

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

rust-toolchain.toml pins Rust 1.82.0 and the wasm32-unknown-unknown target. The setup script installs cargo-component 0.13.2 with its own locked dependencies. Keep Cargo.lock when uploading the project.

Output:

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

Compute the SHA256 for the exact file you distribute:

# macOS
shasum -a 256 target/wasm32-unknown-unknown/release/iris_fdw.wasm
# Linux
sha256sum target/wasm32-unknown-unknown/release/iris_fdw.wasm

The WIT bindings in src/bindings.rs are generated by the component build and are not committed.

Configure PostgreSQL

Upload the Wasm file to a location accessible by PostgreSQL. Replace every placeholder in https://github.com/boanerges1227/iris-wasm-fdw/blob/main/examples/setup.sql, including the package URL, checksum, API URL and credentials. For an existing wrapper installation, reuse its extension schema and wrapper name instead of recreating them.

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;

Replace Sample.Person with your real IRIS table. Aliases returned by IRIS must match the foreign-table column names. If Wrappers is installed in a separate schema, qualify its handler and validator accordingly.

The API URL ends at the Atelier API version; the wrapper appends /<namespace>/action/query. Inside a container, localhost refers to that container, not the host machine.

Always configure api_url, namespace, username and password explicitly. If omitted, the code falls back to the local demo URL http://localhost:52773/api/atelier/v3, namespace USER and demo credentials _SYSTEM / SYS. Basic authentication over plain HTTP does not encrypt credentials; use HTTPS for non-local connections. The password in the example is stored as a foreign-server option, and the wrapper does not implement secret management.

Type mappings and limits

• NUMERIC uses the current WIT f64 carrier and does not provide arbitrary decimal precision. For exact decimal values, return them as strings from IRIS and map the column as TEXT; TEXT does not accept a JSON numeric scalar.
• Unzoned timestamps are interpreted as UTC; explicit offsets are normalized to UTC. Timestamp precision is microseconds.
• JSON null becomes SQL NULL. Atelier may encode SQL NULL as an empty string: non-text/non-JSON empty strings become NULL, TEXT preserves empty strings, and an empty JSON string is rejected.
• Wrappers 0.6.1 reparses JSON cells. Values it would silently round are rejected with a TEXT mapping suggestion. For exact JSON numbers, return the JSON as a string, object or array, declare the field as TEXT, and cast it to jsonb in PostgreSQL. A JSON numeric scalar cannot be mapped directly to TEXT.
• Missing columns and incompatible types produce errors rather than silent NULL values.

Query scope

query is static SQL. There is no placeholder substitution, parameter binding, automatic pagination or automatic WHERE/LIMIT/sort pushdown. Put source-side conditions and an appropriate IRIS TOP limit in the configured query; the response is buffered in memory.

The wrapper does not implement INSERT, UPDATE, DELETE or host-driven rescans. Independent repeated SELECT statements work; joins that require a rescan may fail. The FDW’s query interface does not itself enforce read-only SQL: configure an IRIS account with appropriate read-only privileges.

Repository layout

.github/workflows/       Public build/lint and release workflows
examples/               SQL setup and release templates
docs/                   Reproducible local walkthrough
scripts/                Toolchain setup and public validation
src/                    FDW implementation and type conversion
supabase-wrappers-wit/   Host interface definitions
wit/                    Component world
.local/                 Local tests, development notes and work logs (Git-ignored)

Run bash scripts/check.sh to build, check formatting and run Clippy. The included CI workflow builds and uploads an artifact; the release workflow uses that artifact and calculates its checksum for matching version tags.

License

MIT License.