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.
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?;
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.
| Option | Was es bewirkt |
|---|---|
encryption | disable (Standard) oder require. |
ca_certificate | Pfad zu einer zusätzlichen PEM-CA-Datei für TLS. |
connect_timeout | Sekunden, die für TCP-Verbindung, TLS und Login zusammen erlaubt sind. |
query_timeout | Serverseitiges Abfrage-Timeout in Sekunden. |
max_rows | Gesamtanzahl der Zeilen, die IRIS pro Abfrage zurückgibt. Es ist eine Obergrenze, keine Abrufgröße. |
fast_insert | 1 oder 0. Packt Parameterarrays in eine Anfrage. |
application_name | Der 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äche | Status | Notizen |
|---|---|---|
| Passwortanmeldung | getestet | Die Passwort-Kodierung auf der Leitung ist umkehrbare Verschleierung, nutze also TLS in jedem Netzwerk, das dir nicht gehört. |
| Direktes und vorbereitetes SQL | getestet | Anweisungen werden geschlossen, wenn Ergebnisse abgeschlossen sind oder gelöscht werden; der Server-Speicher blieb über 20.000 Abfragen stabil. |
| Transaktionen und Isolation | getestet | Autocommit, Read Committed, Read Uncommitted, Commit und Rollback. |
| Gespeicherte Prozeduren | getestet | Eingabeparameter, skalare Rückgaben und mehrere Ergebnismengen. |
| Parameter-Arrays und schnelles Einfügen | getestet | Tabellen mit Identity-, Primär- und zusammengesetzten Schlüsseln, Standardwerte, umsortierte Spalten und Fehler pro Zeile. |
| Datentypen | getestet | Ganzzahlen, exakte Dezimalzahlen, Doubles, Bits, Latin-1- und Unicode-Text, Binärdaten, DATE, TIME, TIMESTAMP sowie langer Text und Binärdaten. |
| Globale Variablen, Methoden, Eigenschaften | getestet | Native Fehler werden mit der IRIS-Meldung zurückgegeben, zum Beispiel <METHOD DOES NOT EXIST>. |
| Katalog | getestet | Schemas, Tabellen, Spalten und Prozeduren. |
| TLS | implementiert | Klartext-Ablehnung wird getestet; ein erfolgreicher Handshake gegen einen TLS-konfigurierten IRIS-Server noch nicht. |
| Längenprüfungen beim Schnelleinfügen | beobachtet | Der Server wendet sie nicht auf gepackte Zeilen an. |
| Werte über 65.534 Bytes | geplant | Gibt heute einen klaren Fehler zurück; Stream-Parameter werden das Limit aufheben. |
| Ausgabeparameter, vorbereitete Prozeduren | geplant | |
| Generierte Schlüssel | geplant | Noch nicht zuverlässig, daher nicht beworben. |
| Kerberos und OAuth | geplant | |
| Abbruch auf Client-Seite | geplant | Das Verwerfen einer laufenden Anfrage legt die Verbindung still, statt die Arbeit auf dem Server abzubrechen. |
| Ältere IRIS-Versionen, XEP, Vektoren | geplant | Noch nicht recherchiert. |