InterSystems IRIS driver

sqlly-iris, the open-source async Rust driver for the native IRIS protocol: SQL, bulk inserts, procedures and globals, with samples and a support matrix.

sqlly-iris is an open-source, asynchronous Rust driver for InterSystems IRIS. It speaks the native xDBC protocol straight to the IRIS superserver port, so it needs no ODBC driver manager and no vendor client library, and the crate contains no unsafe code. It is Apache-2.0 and at version 0.1; it is not on crates.io yet, so depend on it from GitHub.

What "supported" means here. Every row in the table at the end says how we know: tested means a live integration test runs it against IRIS 2026.1 (protocol 69), observed means we watched the server do it but do not promise it, and planned means not yet. An opcode existing in the protocol does not count as support.

Add the crate

# Cargo.toml
[dependencies]
sqlly-iris = { git = "https://github.com/sql-ly/sqlly-iris" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Connect, insert, query

? placeholders bind positionally and are left alone inside strings, quoted identifiers, and comments. Dates and times arrive as ISO text such as 1815-12-10, not $HOROLOG day counts, and text keeps one character per code point in both Latin-1 and Unicode.

use sqlly_iris::{Client, Config, Result, Value};

#[tokio::main]
async fn main() -> Result<()> {
    let config = Config::from_url("iris://_SYSTEM:[email protected]:1972/USER")?;
    let mut client = Client::connect(config).await?;
    println!("{}", client.server_info().product_info);

    client
        .execute(
            "INSERT INTO Sample.Person (Name, Born) VALUES (?, ?)",
            &[Value::from("Ada Lovelace"), Value::Date("1815-12-10".into())],
        )
        .await?;

    let rows = client
        .query("SELECT ID, Name, Born FROM Sample.Person WHERE ID > ?", &[Value::I32(0)])
        .await?
        .collect()
        .await?;
    for row in &rows {
        let name = row.get_by_name("Name")?.as_str();
        let born = row.get(2)?.as_str(); // Some("1815-12-10")
        println!("{name:?} born {born:?}");
    }

    client.close().await
}

Transactions

Commit or roll back explicitly. Dropping a transaction without either retires the connection on purpose, so nothing later runs inside a transaction nobody is tracking.

let mut tx = client.begin().await?;
tx.execute("UPDATE Bank.Account SET Balance = Balance - ? WHERE ID = ?", &[Value::Decimal("25.00".into()), Value::I32(1)]).await?;
tx.execute("UPDATE Bank.Account SET Balance = Balance + ? WHERE ID = ?", &[Value::Decimal("25.00".into()), Value::I32(2)]).await?;
tx.commit().await?;

Prepared statements and bulk inserts

With fast_insert on, IRIS takes eligible INSERT batches in one packed request. Rows the server refuses are reported one by one with their index, SQLCODE and message, and the rest are still written, so wrap the batch in a transaction if it has to be all-or-nothing.

use sqlly_iris::Error;

let mut config = Config::from_url(&dsn)?;
config.fast_insert(true); // or ?fast_insert=1 in the URL
let mut client = Client::connect(config).await?;

let mut insert = client
    .prepare("INSERT INTO Lab.Reading (Sensor, Reading) VALUES (?, ?)")
    .await?;
let batches: Vec<Vec<Value>> = (0..5_000)
    .map(|n| vec![Value::String(format!("probe-{}", n % 4)), Value::F64(f64::from(n))])
    .collect();

match insert.execute_many(&batches).await {
    Ok(done) => println!("{} rows", done.rows_affected),
    Err(Error::BatchFailed { rows_affected, failures }) => {
        for f in &failures {
            eprintln!("row {} refused, SQLCODE -{}: {}", f.row, f.code, f.message);
        }
        println!("{rows_affected} rows still written");
    }
    Err(other) => return Err(other),
}
insert.close().await?;
One fast-insert quirk we observed: IRIS skips column length checks on packed rows, so a 12-character value was stored in a VARCHAR(5) column. NOT NULL and unique constraints are still enforced. Validate lengths yourself, or leave fast insert off for that table.

Streaming large results

Rows are fetched as you read them. Stop whenever you like: dropping the stream discards the rest and closes the statement before your next request, and the connection stays usable.

use futures_util::TryStreamExt;

let mut rows = client.query("SELECT ID, Name FROM Sample.Person ORDER BY ID", &[]).await?;
while let Some(row) = rows.next_row().await? {
    if row.get(0)?.as_i64() == Some(1_000) { break; }
}
drop(rows);

let total = client
    .query("SELECT Reading FROM Lab.Reading", &[])
    .await?
    .into_stream()
    .try_fold(0.0, |sum, row| async move { Ok(sum + row.get(0)?.as_f64().unwrap_or(0.0)) })
    .await?;

Stored procedures

let results = client
    .call_procedure("Sample.TopPeople", &[Value::I32(10)])
    .await?
    .collect()
    .await?;
for result in &results {
    println!("return {:?}, {} rows", result.return_value, result.rows.len());
}

Globals and objects

The non-SQL half of IRIS. A node that does not exist reads as Value::Null, and global_data tells you whether a node has a value, children, or both.

use sqlly_iris::GlobalDirection;

client.global_set("^Population", &Value::I64(650_000), &["Boston".into()]).await?;
let boston = client.global_get("^Population", &["Boston".into()]).await?;

// walk the first-level subscripts in collation order
let mut city = String::new();
while let Some(next) = client.global_order("^Population", &city, &[], GlobalDirection::Next).await? {
    println!("{next}");
    city = next;
}

let version = client.class_method("%SYSTEM.Version", "GetVersion", &[]).await?;

TLS

Native trust roots are used by default. An extra CA file adds to them; it does not replace them or switch off hostname checks, and Encryption::Required never falls back to plaintext.

use sqlly_iris::Encryption;

let mut config = Config::from_url("iris://_SYSTEM:[email protected]:1972/USER")?;
config.encryption(Encryption::Required).ca_certificate("/path/to/private-ca.pem");
let client = Client::connect(config).await?;

Connection URL

iris://user:password@host:port/NAMESPACE?option=value. The port defaults to 1972, IPv6 hosts go in brackets, special characters in the user name or password need percent-encoding, and unknown options are rejected instead of quietly ignored.

OptionWhat it does
encryptiondisable (default) or require.
ca_certificatePath to an additional PEM CA file for TLS.
connect_timeoutSeconds allowed for TCP connect, TLS, and login together.
query_timeoutServer-side query timeout, in seconds.
max_rowsTotal rows IRIS returns per query. It is a cap, not a fetch size.
fast_insert1 or 0. Packs parameter arrays into one request.
application_nameThe name the server sees for this connection.

What works today

Verified against IRIS 2026.1 build 234U on protocol 69, the only version tested so far. The full matrix with its evidence is in the repository's docs/compatibility.md.

AreaStateNotes
Password logintestedThe password encoding on the wire is reversible obfuscation, so use TLS on any network you do not own.
Direct and prepared SQLtestedStatements are closed when results finish or are dropped; server memory stayed flat across 20,000 queries.
Transactions and isolationtestedAutocommit, read committed, read uncommitted, commit, and rollback.
Stored procedurestestedInput parameters, scalar returns, and multiple result sets.
Parameter arrays and fast inserttestedIdentity, primary-key, and composite-key tables, defaults, reordered columns, and per-row failures.
Data typestestedIntegers, exact decimals, doubles, bits, Latin-1 and Unicode text, binary, DATE, TIME, TIMESTAMP, and long text and binary.
Globals, methods, propertiestestedNative errors come back with the IRIS message, for example <METHOD DOES NOT EXIST>.
CatalogtestedSchemas, tables, columns, and procedures.
TLSimplementedPlaintext refusal is tested; a successful handshake against a TLS-configured IRIS server is not yet.
Fast-insert length checksobservedThe server does not apply them to packed rows.
Values over 65,534 bytesplannedReturns a clear error today; stream parameters will lift the limit.
Output parameters, prepared proceduresplanned
Generated keysplannedNot reliable yet, so not advertised.
Kerberos and OAuthplanned
Client-side cancellationplannedDropping an in-flight request retires the connection rather than cancelling the server work.
Older IRIS releases, XEP, vectorsplannedNot researched yet.
Independent, and polite about it. The protocol work was informed by the Apache-2.0 go-irisnative project and checked against the vendor ODBC and JDBC drivers. InterSystems and InterSystems IRIS are trademarks of InterSystems Corporation, and this project is not affiliated with them. Found an IRIS corner we missed? Open an issue with what you ran and what IRIS said back.