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 相依。

這裡的「支援」是什麼意思。 結尾表格裡的每一列都說明了我們是怎麼知道的: 已測試 表示有一個即時整合測試會對 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_certificate用於 TLS 的額外 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已測試結果完成或捨棄時,陳述式就會關閉;伺服器記憶體在 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 遺漏的部分? 回報問題 提供你執行的操作以及 IRIS 回傳的內容。