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 引入。
添加这个 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?;
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 主机要放在方括号里,用户名或密码中的特殊字符需要百分号编码,未知选项会被拒绝,而不是被悄悄忽略。
| 选项 | 作用 |
|---|---|
encryption | disable (默认)或 require. |
ca_certificate | TLS 的额外 PEM CA 文件路径。 |
connect_timeout | TCP 连接、TLS 和登录允许的总秒数。 |
query_timeout | 服务器端查询超时时间,以秒为单位。 |
max_rows | IRIS 每个查询返回的总行数。这是上限,不是抓取大小。 |
fast_insert | 1 或者 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、向量 | 计划中 | 尚未研究。 |