Home Applications supabase-iris-reader

supabase-iris-reader

Community Project
This project is maintained by its author and is not officially supported by InterSystems. For technical support, please contact the project developer.
0
0 reviews
0
Awards
1
Views
0
IPM installs
0
Add to bundle
Details
Releases (1)
Reviews
Issues
Query InterSystems IRIS tables from Supabase PostgreSQL through a read-only Wasm foreign data wrapper and an ObjectScript REST service.

What's new in this version

Initial Release

IRIS Keyset Reader for Supabase

English · 简体中文

Query selected InterSystems IRIS tables or views from Supabase SQL. The native ObjectScript REST service authenticates requests, validates the allowlist, and reads ordered pages through IRIS dynamic SQL. A Rust WebAssembly guest implements the Supabase Wrappers ABI and converts each JSON value into a PostgreSQL cell. The local demo uses a small Python HTTPS transport that forwards requests to the IRIS Web Gateway. Each administrator-defined dataset exposes a projection of one IRIS table and an integer pagination key. Credentials used by PostgreSQL are stored in Supabase Vault.

Idea implemented: Add InterSystems wrapper for Supabase.

Run the local demonstration

Install Docker with Compose v2, Python 3.9+ and OpenSSL with the -addext option. Allow Docker to use both official images in compose.yaml. The release component is included under dist/. From the project directory run:

./demo/start.sh
docker compose exec -T postgres psql -U postgres -c \
  'SELECT code, label FROM reader_demo.shelves ORDER BY code'

The query returns codes 1, 2 and 3 with labels North, SQL NULL and South. The script creates random local credentials and an ephemeral TLS CA, starts three containers on a private network with no host ports, creates two synthetic IRIS tables, registers the wrapper, then exercises real SQL reads. All three containers belong to this project’s Compose stack. Every invocation of the start script seeds its dedicated test rows. To repeat the checks on that stack, run python3 demo/verify.py. To stop the demonstration, run docker compose stop. The demo certificate is valid for 30 days and the CA for 90 days; create a fresh private demo for later trials.

The checks read both mappings with a one-row page size, join their rows, apply a PostgreSQL predicate, preserve NULL, and observe an update immediately after its IRIS transaction commits. The verification script also empties and restores the synthetic count table and checks that a PostgreSQL insert is refused. Demonstrated with the local Supabase PostgreSQL 17.6 distribution, Wrappers 0.6.1, and IRIS for Health Community 2026.2.

Runtime components

File Responsibility
iris/Config.cls Validate mappings and atomically install the read allowlist and token digest.
iris/Routes.cls Dispatch GET requests, authenticate, validate arguments, and emit status codes and JSON.
iris/Reader.cls Execute parameterized keyset queries and serialize rows using IRIS SQL metadata.
src/lib.rs Implement the mandatory Wasm host callbacks, Vault and HTTP imports, and PostgreSQL cell conversion.
gateway/server.py Forward HTTPS requests to the native IRIS REST application for the local demo.

Map a table

  1. Give the REST web application’s dedicated IRIS account SELECT privileges on your approved table or view. Grant access to the application namespace. Connect the TLS transport and IRIS Web Gateway on a trusted private network.
  2. Add an alias to the IRIS dataset configuration, as shown in demo/datasets.json. Set table to a schema-qualified name, columns to the ordered names exposed to SQL, and key to a unique, non-null, immutable integer column included in that list. Use simple identifiers, and choose lowercase exposed column names to match unquoted PostgreSQL identifiers. Load the classes under iris/ into the application namespace. Run ##class(KeyRead.Config).Install(path,token) from an administrator session when you change mappings or rotate credentials. Supply the path as seen by IRIS and a high-entropy bearer token of at least 32 characters. One write installs the fully validated mappings together with a digest of the token.
  3. Configure a password-authenticated IRIS web application at /keyread with dispatch class KeyRead.Routes. The demo setup in demo/seed.os creates this application in USER. Configure IRIS_HOST, IRIS_WEB_PORT (default 52773), IRIS_USER, IRIS_PASSWORD, TLS_CERT, and TLS_KEY for the example transport. It listens for HTTPS on port 8080 and relays the public bearer credential as X-Reader-Authorization alongside the dedicated application’s Basic login. In other deployments an equivalent HTTPS web proxy can perform this transport role.
  4. Enable the Wrappers and Vault extensions in Supabase. Register the guest with the Wasm handler and validator. Use the UUID of the gateway token stored in Vault for the foreign server’s token_id. The full SQL is in demo/install.sql. For a remote host configure an immutable, reachable HTTPS URL to the release Wasm file, add the SHA-256 from dist/iris_scan.sha256 in fdw_package_checksum, and replace the demonstration endpoint with the trusted HTTPS address reachable from the database. The local file URL applies inside the demonstration container.
  5. Define a foreign table with the chosen alias. PostgreSQL users granted access to this table can query the dataset permitted by the gateway token. Grant foreign server usage and table privileges only to intended database roles.
CREATE FOREIGN TABLE reader_demo.stock (code integer, quantity integer)
  SERVER iris_reader OPTIONS (dataset 'counts', page_size '100');
SELECT code, quantity FROM reader_demo.stock WHERE quantity > 0;

The keyset cursor binds the previous page’s last key as a SQL parameter. The ObjectScript reader fetches one extra row to detect the end. It uses the SQL result metadata to distinguish integer and text values, including numeric-looking text, and preserves the difference between empty text and SQL NULL. Valid page sizes are 1–500. Integer, bigint, smallint, text and SQL NULL are supported. PostgreSQL evaluates filters and joins locally. Concurrent IRIS changes may be visible between pages; use a stable source for snapshot-style reporting. With Wrappers 0.6.1, name the fields explicitly when building a JSON aggregate, e.g. json_build_object('code',code,'label',label). This host can omit projected columns when a query references a composite row only.

Build the Wasm package

The tested toolchain is Rust 1.82.0 with cargo-component 0.13.2. The latter expects the legacy wasm32-wasi target even for an unknown-unknown build. Install this toolchain once:

rustup toolchain install 1.82.0
rustup target add --toolchain 1.82.0 wasm32-wasi wasm32-unknown-unknown
cargo +1.82.0 install cargo-component --version 0.13.2 --locked
./demo/build.sh

This regenerates dist/iris_scan.wasm and its checksum from src/lib.rs, Cargo.lock and the pinned WIT interface definitions. The local test exercises the resulting component using Supabase’s own Wrappers host. A managed Supabase environment requires its own connectivity and extension checks.

Project code uses the MIT license. Files in vendor/wrappers-v2 are the publicly documented ABI from Supabase Wrappers v0.6.4, with its Apache 2.0 license. The native IRIS service, Wasm guest, demonstration transport, and synthetic examples are authored for this project. See the official guest packaging guide for additional deployment information.

Version
1.0.021 Nov, 2026
Category
Data Set
Works with
InterSystems IRIS
First published
21 Nov, 2026
Last edited
21 Nov, 2026