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.

Ce que signifie « pris en charge » ici. Chaque ligne dans le tableau à la fin indique comment nous le savons : testé signifie qu'un test d'intégration en direct l'exécute contre IRIS 2026.1 (protocole 69), observé signifie que nous avons observé le serveur le faire mais sans le promettre, et prévu signifie pas encore. Qu'un opcode existe dans le protocole ne compte pas comme une prise en charge.

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?;
Une bizarrerie de l'insertion rapide que nous avons observée : IRIS ignore les vérifications de longueur des colonnes sur les lignes packées, donc une valeur de 12 caractères a été stockée dans un 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.

OptionCe que cela fait
encryptiondisable (par défaut) ou require.
ca_certificateChemin vers un fichier CA PEM supplémentaire pour TLS.
connect_timeoutSecondes autorisées au total pour la connexion TCP, la négociation TLS et l'authentification.
query_timeoutDélai d'expiration de la requête côté serveur, en secondes.
max_rowsNombre total de lignes renvoyées par IRIS par requête. C’est un plafond, pas une taille de récupération.
fast_insert1 ou 0. Regroupe les tableaux de paramètres en une seule requête.
application_nameLe 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ÉtatNotes
Connexion par mot de passetesté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 isolationtestéAutocommit, lecture validée (read committed), lecture non validée (read uncommitted), validation (commit) et annulation (rollback).
Procédures stockéestestéParamètres d'entrée, valeurs de retour scalaires et plusieurs ensembles de résultats.
Tableaux de paramètres et insertion rapidetesté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éestesté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éstestéLes erreurs natives sont renvoyées avec le message IRIS, par exemple <METHOD DOES NOT EXIST>.
CataloguetestéSchémas, tables, colonnes et procédures.
TLSimplé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 rapideobservéLe serveur ne les applique pas aux lignes compactées.
Valeurs supérieures à 65 534 octetsprévuRenvoie aujourd'hui une erreur claire ; les paramètres de flux permettront de lever la limite.
Paramètres de sortie, procédures préparéesprévu
Clés généréesprévuPas encore fiable, donc non publié.
Kerberos et OAuthprévu
Annulation côté clientprévuAbandonner 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, vecteursprévuPas encore étudié.
Indépendant, et poli là-dessus. Le travail sur le protocole s'est appuyé sur le projet sous licence Apache-2.0 go-irisnative projet et vérifié par rapport aux pilotes ODBC et JDBC du fournisseur. InterSystems et InterSystems IRIS sont des marques commerciales d'InterSystems Corporation, et ce projet n'est pas affilié à cette société. Vous avez trouvé un recoin d'IRIS que nous avons manqué ? Ouvrir un ticket avec ce que vous avez exécuté et ce qu'IRIS a renvoyé.