InterSystems IRIS 驱动程序

sqlly-iris,一个支持原生 IRIS 协议的开源异步 Rust 驱动程序:SQL、批量插入、存储过程和全局变量,附带示例和支持矩阵。

sqlly-iris 是一个开源的 InterSystems IRIS 异步 Rust 驱动程序。它直接以原生 xDBC 协议连到 IRIS 超级服务器端口,因此既不需要 ODBC 驱动管理器,也不需要厂商的客户端库,而且这个 crate 不含任何 unsafe 代码。它采用 Apache-2.0 许可证,版本为 0.1;尚未上架 crates.io,所以要依赖它得从 GitHub 引入。

“支持”在这里的含义。 表格最后的每一行说明了我们是怎么知道的: 测试过的 表示有一个实时集成测试会针对 IRIS 2026.1(协议 69)运行它, 观察到的 表示我们见过服务器确实这样做了,但不作承诺,而 计划中 表示还不支持。操作码存在于协议中并不等于支持。

添加这个 crate

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

连接、插入、查询

? 占位符按位置绑定;在字符串、带引号的标识符和注释里则原样保留。日期和时间以 ISO 文本传入,例如 1815-12-10,而不是 $HOROLOG 按天数计数,而文本在 Latin-1 和 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
}

事务

请显式提交或回滚。两者都不做就丢弃事务的话,该连接会被有意停用,这样之后的操作就不会在无人跟踪的事务里运行。

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?;

预处理语句和批量插入

开启 fast_insert 开启后,IRIS 接受符合条件的 INSERT 批一起打进一个请求发送。服务器拒绝的行会连同其索引、SQLCODE 和消息逐条报告,其余行仍会写入;如果批次必须全部成功或全部失败,请把它包在事务里。

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?;
我们实测中注意到的一个快速插入怪癖: IRIS 在打包行上会跳过列长度检查,因此一个 12 字符的值被存进了一个 VARCHAR(5) 列。 NOT NULL 中,并且唯一约束仍然会被强制执行。请自行验证长度,或者对该表关闭快速插入。

流式处理大型结果

行在你读取它们时被获取。你可以随时停止:丢弃流会丢弃剩余部分并在下一次请求前关闭语句,连接仍然可以使用。

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?;

存储过程

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());
}

全局变量和对象

IRIS 的非 SQL 部分。不存在的节点会显示为 Value::Null,以及 global_data 告诉你一个节点是否有值、子节点,或者两者都有。

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

默认使用系统自带的信任根。额外的 CA 文件只是在其中追加;既不会替换它们,也不会关闭主机名检查,而且 Encryption::Required 绝不会回退到明文。

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?;

连接 URL

iris://user:password@host:port/NAMESPACE?option=value。端口默认为 1972,IPv6 主机要放在方括号里,用户名或密码中的特殊字符需要百分号编码,未知选项会被拒绝,而不是被悄悄忽略。

选项作用
encryptiondisable (默认)或 require.
ca_certificateTLS 的额外 PEM CA 文件路径。
connect_timeoutTCP 连接、TLS 和登录允许的总秒数。
query_timeout服务器端查询超时时间,以秒为单位。
max_rowsIRIS 每个查询返回的总行数。这是上限,不是抓取大小。
fast_insert1 或者 0。把参数数组打包进一个请求。
application_name此连接在服务器上显示的名称。

目前已支持的功能

已针对协议 69 上的 IRIS 2026.1 build 234U 完成验证,这是目前唯一测过的版本。完整的验证矩阵及证据在仓库的 docs/compatibility.md.

面积状态备注
密码登录测试过的线上传输的密码编码只是可逆的混淆,所以在任何不属于你的网络上都要使用 TLS。
直接 SQL 和预处理 SQL测试过的当结果完成或被丢弃时,语句会关闭;在 20,000 次查询中服务器内存保持平稳。
事务与隔离测试过的自动提交、已提交读、未提交读、提交和回滚。
存储过程测试过的输入参数、标量返回值和多个结果集。
参数数组和快速插入测试过的标识列、主键和复合键的表、默认值、重排的列,以及逐行失败的处理。
数据类型测试过的整数、精确小数、双精度、位、Latin-1 和 Unicode 文本、二进制、DATE、TIME、TIMESTAMP,以及长文本和二进制。
全局、方法、属性测试过的原生错误会连同 IRIS 消息一起返回,例如 <METHOD DOES NOT EXIST>.
目录测试过的模式、表、列和存储过程。
TLS已实现已测试明文连接会被拒绝;尚未在配置好 TLS 的 IRIS 服务器上测试成功握手。
快速插入长度检查观察到的服务器不会将其应用于打包行。
超过 65,534 字节的值计划中目前会返回明确的错误;流式参数将解除这一限制。
输出参数、预编译过程计划中
生成的键计划中还不够可靠,所以没有宣传。
Kerberos 和 OAuth计划中
客户端取消计划中丢弃进行中的请求会停用该连接,而不是取消服务器端的工作。
较旧的 IRIS 版本、XEP、向量计划中尚未研究。
独立,还不失礼貌。 协议工作参考了 Apache-2.0 的 go-irisnative 项目,并已对照厂商的 ODBC 和 JDBC 驱动做过核对。InterSystems 和 InterSystems IRIS 是 InterSystems Corporation 的商标,本项目与该公司无任何关联。发现了我们漏掉的 IRIS 角落? 提交 issue 提供你运行的内容以及 IRIS 的反馈。