Pilote InterSystems IRIS
sqlly-iris, le pilote Rust asynchrone open source pour le protocole IRIS natif : SQL, insertions en masse, procédures et globals, avec des exemples et une matrice de support.
sqlly-iris est un pilote Rust open-source et asynchrone pour InterSystems IRIS. Il utilise le protocole xDBC natif directement vers le port du superserver IRIS, donc il n'a pas besoin de gestionnaire de pilote ODBC ni de bibliothèque client du fournisseur, et le crate ne contient aucun unsafe code. Il est sous licence Apache-2.0 et en version 0.1 ; il n'est pas encore sur crates.io, donc dépendez-en via GitHub.
Ajouter le crate
# Cargo.toml
[dependencies]
sqlly-iris = { git = "https://github.com/sql-ly/sqlly-iris" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
Connecter, insérer, interroger
? Les espaces réservés se lient positionnellement et sont laissés tels quels dans les chaînes, les identifiants entre guillemets et les commentaires. Les dates et heures arrivent sous forme de texte ISO tel que 1815-12-10, et non $HOROLOG les comptes de jours et le texte conservent un caractère par point de code en Latin-1 et en 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
}
Transactions
Validez ou annulez explicitement. Abandonner une transaction sans faire ni l'un ni l'autre met volontairement la connexion hors service, afin que rien ne s'exécute ensuite dans une transaction que personne ne suit.
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?;
Instructions préparées et insertions en masse
Avec fast_insert activé, IRIS prend les lots éligibles INSERT lots dans une seule requête groupée. Les lignes refusées par le serveur sont signalées une par une avec leur index, leur SQLCODE et leur message, et le reste est tout de même écrit ; placez donc le lot dans une transaction s'il doit être tout ou rien.
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) colonne. NOT NULL et les contraintes d'unicité sont toujours appliquées. Validez les longueurs vous-même, ou désactivez l'insertion rapide pour cette table.Diffusion de grands résultats
Les lignes sont récupérées au fur et à mesure de votre lecture. Arrêtez quand vous voulez : abandonner le flux jette le reste et ferme l'instruction avant votre requête suivante, et la connexion reste utilisable.
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?;
Procédures stockées
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 et objets
La moitié non-SQL d’IRIS. Un nœud qui n’existe pas s’affiche comme Value::Null, et global_data vous indique si un nœud possède une valeur, des enfants, ou les deux.
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
Les racines de confiance natives sont utilisées par défaut. Un fichier CA supplémentaire s'ajoute à elles ; il ne les remplace pas et ne désactive pas les vérifications de nom d'hôte, et Encryption::Required ne revient jamais au texte brut.
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 de connexion
iris://user:password@host:port/NAMESPACE?option=value. Le port par défaut est 1972, les hôtes IPv6 sont entre crochets, les caractères spéciaux dans le nom d'utilisateur ou le mot de passe doivent être encodés en pourcentage, et les options inconnues sont rejetées au lieu d'être ignorées silencieusement.
| Option | Ce que cela fait |
|---|---|
encryption | disable (par défaut) ou require. |
ca_certificate | Chemin vers un fichier CA PEM supplémentaire pour TLS. |
connect_timeout | Secondes autorisées au total pour la connexion TCP, la négociation TLS et l'authentification. |
query_timeout | Délai d'expiration de la requête côté serveur, en secondes. |
max_rows | Nombre total de lignes renvoyées par IRIS par requête. C’est un plafond, pas une taille de récupération. |
fast_insert | 1 ou 0. Regroupe les tableaux de paramètres en une seule requête. |
application_name | Le nom que le serveur voit pour cette connexion. |
Ce qui fonctionne aujourd'hui
Vérifié avec IRIS 2026.1 build 234U sur le protocole 69, la seule version testée jusqu'à présent. La matrice complète avec ses preuves se trouve dans le dépôt docs/compatibility.md.
| Aire | État | Notes |
|---|---|---|
| Connexion par mot de passe | testé | L’encodage du mot de passe transmis sur le réseau est une obfuscation réversible, donc utilisez TLS sur tout réseau qui n’est pas le vôtre. |
| SQL direct et préparé | testé | Les instructions sont fermées lorsque les résultats se terminent ou sont supprimés ; la mémoire du serveur est restée stable sur 20 000 requêtes. |
| Transactions et isolation | testé | Autocommit, lecture validée (read committed), lecture non validée (read uncommitted), validation (commit) et annulation (rollback). |
| Procédures stockées | testé | Paramètres d'entrée, valeurs de retour scalaires et plusieurs ensembles de résultats. |
| Tableaux de paramètres et insertion rapide | testé | Tables à colonne d'identité, à clé primaire et à clé composite, valeurs par défaut, colonnes réordonnées et échecs ligne par ligne. |
| Types de données | testé | Entiers, décimaux exacts, doubles, bits, texte Latin-1 et Unicode, binaire, DATE, TIME, TIMESTAMP, ainsi que texte long et binaire. |
| Globaux, méthodes, propriétés | testé | Les erreurs natives sont renvoyées avec le message IRIS, par exemple <METHOD DOES NOT EXIST>. |
| Catalogue | testé | Schémas, tables, colonnes et procédures. |
| TLS | implémenté | Le refus en texte clair est testé ; une connexion réussie avec un serveur IRIS configuré pour TLS ne l'est pas encore. |
| Contrôles de longueur pour l'insertion rapide | observé | Le serveur ne les applique pas aux lignes compactées. |
| Valeurs supérieures à 65 534 octets | prévu | Renvoie aujourd'hui une erreur claire ; les paramètres de flux permettront de lever la limite. |
| Paramètres de sortie, procédures préparées | prévu | |
| Clés générées | prévu | Pas encore fiable, donc non publié. |
| Kerberos et OAuth | prévu | |
| Annulation côté client | prévu | Abandonner une requête en cours retire la connexion du pool plutôt que d'annuler le travail côté serveur. |
| Anciennes versions d'IRIS, XEP, vecteurs | prévu | Pas encore étudié. |