InterSystems IRIS 驅動程式
sqlly-iris,適用於原生 IRIS 協定的開源非同步 Rust 驅動:SQL、大量插入、程序和全域變數,附範例及支援矩陣。
sqlly-iris 是一個開源的非同步 Rust 驅動程式,適用於 InterSystems IRIS。它直接用原生 xDBC 通訊協定連上 IRIS superserver 連接埠,不需要 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 | 已測試 | 結果完成或捨棄時,陳述式就會關閉;伺服器記憶體在 20,000 次查詢間保持平穩。 |
| 交易與隔離 | 已測試 | 自動提交、讀取已提交、讀取未提交、提交與回滾。 |
| 預存程序 | 已測試 | 輸入參數、純量傳回值以及多個結果集。 |
| 參數陣列與快速插入 | 已測試 | 識別欄位、主鍵與複合鍵資料表、預設值、重新排序的欄位,以及逐列失敗。 |
| 資料類型 | 已測試 | 整數、精確小數、雙精度浮點數、位元、Latin-1 與 Unicode 文字、二進位、DATE、TIME、TIMESTAMP,以及長文字與二進位。 |
| 全域變數、方法、屬性 | 已測試 | 原生錯誤會附帶 IRIS 訊息傳回,例如 <METHOD DOES NOT EXIST>. |
| 目錄 | 已測試 | 結構描述、資料表、欄位與程序。 |
| TLS | 已實作 | 已測試明文連線會遭到拒絕;對設定好 TLS 的 IRIS 伺服器成功交握這點則尚未測試。 |
| 快速插入長度檢查 | 觀察到的 | 伺服器不會將它們套用到封裝的資料列上。 |
| 超過 65,534 位元組的值 | 已規劃 | 目前會傳回明確的錯誤;串流參數推出後將解除此限制。 |
| 輸出參數、預先編譯的程序 | 已規劃 | |
| 產生的索引鍵 | 已規劃 | 還不夠穩定,所以沒有對外宣傳。 |
| Kerberos 和 OAuth | 已規劃 | |
| 客戶端取消 | 已規劃 | 捨棄進行中的請求會讓連線一併除役,而不是取消伺服器端的工作。 |
| 較舊的 IRIS 版本、XEP、向量 | 已規劃 | 尚未研究。 |