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.
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?;
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.
| Option | What it does |
|---|---|
encryption | disable (default) or require. |
ca_certificate | Path to an additional PEM CA file for TLS. |
connect_timeout | Seconds allowed for TCP connect, TLS, and login together. |
query_timeout | Server-side query timeout, in seconds. |
max_rows | Total rows IRIS returns per query. It is a cap, not a fetch size. |
fast_insert | 1 or 0. Packs parameter arrays into one request. |
application_name | The 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.
| Area | State | Notes |
|---|---|---|
| Password login | tested | The password encoding on the wire is reversible obfuscation, so use TLS on any network you do not own. |
| Direct and prepared SQL | tested | Statements are closed when results finish or are dropped; server memory stayed flat across 20,000 queries. |
| Transactions and isolation | tested | Autocommit, read committed, read uncommitted, commit, and rollback. |
| Stored procedures | tested | Input parameters, scalar returns, and multiple result sets. |
| Parameter arrays and fast insert | tested | Identity, primary-key, and composite-key tables, defaults, reordered columns, and per-row failures. |
| Data types | tested | Integers, exact decimals, doubles, bits, Latin-1 and Unicode text, binary, DATE, TIME, TIMESTAMP, and long text and binary. |
| Globals, methods, properties | tested | Native errors come back with the IRIS message, for example <METHOD DOES NOT EXIST>. |
| Catalog | tested | Schemas, tables, columns, and procedures. |
| TLS | implemented | Plaintext refusal is tested; a successful handshake against a TLS-configured IRIS server is not yet. |
| Fast-insert length checks | observed | The server does not apply them to packed rows. |
| Values over 65,534 bytes | planned | Returns a clear error today; stream parameters will lift the limit. |
| Output parameters, prepared procedures | planned | |
| Generated keys | planned | Not reliable yet, so not advertised. |
| Kerberos and OAuth | planned | |
| Client-side cancellation | planned | Dropping an in-flight request retires the connection rather than cancelling the server work. |
| Older IRIS releases, XEP, vectors | planned | Not researched yet. |