InterSystems IRIS-Treiber

sqlly-iris, der Open-Source-Async-Rust-Treiber für das native IRIS-Protokoll: SQL, Masseninserts, Prozeduren und Globals, mit Beispielen und einer Support-Matrix.

sqlly-iris ist ein Open-Source-, asynchroner Rust-Treiber für InterSystems IRIS. Er spricht das native xDBC-Protokoll direkt zum IRIS-Superserver-Port, daher benötigt er keinen ODBC-Treiber-Manager und keine Vendor-Client-Bibliothek, und das Crate enthält keine unsafe Code. Apache-2.0, aktuell Version 0.1; noch nicht auf crates.io, daher über GitHub einbinden.

Was hier „unterstützt“ bedeutet. Jede Zeile in der Tabelle am Ende sagt, wie wir es wissen: getestet bedeutet, ein Live-Integrationstest führt es gegen IRIS 2026.1 (Protokoll 69) aus, beobachtet bedeutet, wir haben den Server dabei beobachtet, aber wir versprechen es nicht, und geplant bedeutet noch nicht. Ein Opcode, der im Protokoll existiert, zählt nicht als Unterstützung.

Crate hinzufügen

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

Verbinden, einfügen, abfragen

? Platzhalter binden sich positionsabhängig und bleiben unverändert innerhalb von Zeichenketten, in Anführungszeichen gesetzten Bezeichnern und Kommentaren. Datums- und Zeitwerte werden als ISO-Text geliefert, wie zum Beispiel 1815-12-10, nicht $HOROLOG Tageszählungen und Text behalten je ein Zeichen pro Codepunkt sowohl in Latin-1 als auch in 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
}

Transaktionen

Führe ausdrücklich ein Commit oder Rollback durch. Wird eine Transaktion ohne beides verworfen, wird die Verbindung absichtlich stillgelegt, sodass später nichts innerhalb einer Transaktion läuft, die niemand mehr verfolgt.

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 und Bulk-Inserts

Mit fast_insert Wenn aktiviert, übernimmt IRIS geeignete INSERT Batches in einer einzigen gebündelten Anfrage ab. Vom Server abgelehnte Zeilen werden einzeln mit ihrem Index, SQLCODE und Meldung gemeldet, und der Rest wird trotzdem geschrieben; packe den Batch also in eine Transaktion, wenn er alles-oder-nichts sein muss.

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?;
Eine Eigenart beim schnellen Einfügen, die wir beobachtet haben: IRIS überspringt Spaltenlängenprüfungen bei gepackten Zeilen, sodass ein 12-Zeichen-Wert in einer VARCHAR(5) Spalte hinzu. NOT NULL gespeichert wurde, und eindeutige Constraints werden weiterhin erzwungen. Prüfe die Längen selbst oder lass Schnell-Einfügen für diese Tabelle aus.

Streaming großer Ergebnisse

Zeilen werden abgerufen, während du liest. Hör auf, wann du willst: Das Verwerfen des Streams verwirft den Rest und schließt die Anweisung vor deiner nächsten Anfrage, und die Verbindung bleibt nutzbar.

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

Gespeicherte Prozeduren

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 und Objekte

Die Nicht-SQL-Hälfte von IRIS. Ein Knoten, der nicht existiert, liest sich als Value::Null, und global_data gelesen und zeigt dir, ob ein Knoten einen Wert, Kinder oder beides hat.

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

Die nativen Vertrauensanker werden standardmäßig verwendet. Eine zusätzliche CA-Datei kommt hinzu; sie ersetzt die Vertrauensanker nicht und schaltet die Hostnamen-Prüfung nicht aus, und Encryption::Required fällt niemals auf Klartext zurück.

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

Verbindungs-URL

iris://user:password@host:port/NAMESPACE?option=value. Der Port ist standardmäßig 1972, IPv6-Hosts kommen in Klammern, Sonderzeichen in Benutzername oder Passwort müssen prozentkodiert werden, und unbekannte Optionen werden abgelehnt statt stillschweigend ignoriert zu werden.

OptionWas es bewirkt
encryptiondisable (Standard) oder require.
ca_certificatePfad zu einer zusätzlichen PEM-CA-Datei für TLS.
connect_timeoutSekunden, die für TCP-Verbindung, TLS und Login zusammen erlaubt sind.
query_timeoutServerseitiges Abfrage-Timeout in Sekunden.
max_rowsGesamtanzahl der Zeilen, die IRIS pro Abfrage zurückgibt. Es ist eine Obergrenze, keine Abrufgröße.
fast_insert1 oder 0. Packt Parameterarrays in eine Anfrage.
application_nameDer Name, unter dem der Server diese Verbindung sieht.

Was heute funktioniert

Verifiziert gegen IRIS 2026.1 Build 234U über Protokoll 69, die bisher einzige getestete Version. Die vollständige Matrix mit den Belegen befindet sich im Repository docs/compatibility.md.

FlächeStatusNotizen
PasswortanmeldunggetestetDie Passwort-Kodierung auf der Leitung ist umkehrbare Verschleierung, nutze also TLS in jedem Netzwerk, das dir nicht gehört.
Direktes und vorbereitetes SQLgetestetAnweisungen werden geschlossen, wenn Ergebnisse abgeschlossen sind oder gelöscht werden; der Server-Speicher blieb über 20.000 Abfragen stabil.
Transaktionen und IsolationgetestetAutocommit, Read Committed, Read Uncommitted, Commit und Rollback.
Gespeicherte ProzedurengetestetEingabeparameter, skalare Rückgaben und mehrere Ergebnismengen.
Parameter-Arrays und schnelles EinfügengetestetTabellen mit Identity-, Primär- und zusammengesetzten Schlüsseln, Standardwerte, umsortierte Spalten und Fehler pro Zeile.
DatentypengetestetGanzzahlen, exakte Dezimalzahlen, Doubles, Bits, Latin-1- und Unicode-Text, Binärdaten, DATE, TIME, TIMESTAMP sowie langer Text und Binärdaten.
Globale Variablen, Methoden, EigenschaftengetestetNative Fehler werden mit der IRIS-Meldung zurückgegeben, zum Beispiel <METHOD DOES NOT EXIST>.
KataloggetestetSchemas, Tabellen, Spalten und Prozeduren.
TLSimplementiertKlartext-Ablehnung wird getestet; ein erfolgreicher Handshake gegen einen TLS-konfigurierten IRIS-Server noch nicht.
Längenprüfungen beim SchnelleinfügenbeobachtetDer Server wendet sie nicht auf gepackte Zeilen an.
Werte über 65.534 BytesgeplantGibt heute einen klaren Fehler zurück; Stream-Parameter werden das Limit aufheben.
Ausgabeparameter, vorbereitete Prozedurengeplant
Generierte SchlüsselgeplantNoch nicht zuverlässig, daher nicht beworben.
Kerberos und OAuthgeplant
Abbruch auf Client-SeitegeplantDas Verwerfen einer laufenden Anfrage legt die Verbindung still, statt die Arbeit auf dem Server abzubrechen.
Ältere IRIS-Versionen, XEP, VektorengeplantNoch nicht recherchiert.
Unabhängig und höflich dabei. Die Protokollarbeit orientierte sich an dem unter Apache-2.0 lizenzierten go-irisnative Projekt und gegen die ODBC- und JDBC-Treiber des Anbieters geprüft. InterSystems und InterSystems IRIS sind Marken der InterSystems Corporation, und dieses Projekt steht in keiner Verbindung zu ihnen. Hast du eine IRIS-Ecke gefunden, die wir übersehen haben? Issue anlegen mit dem, was du ausgeführt hast, und was IRIS zurückgemeldet hat.