Controlador de InterSystems IRIS

sqlly-iris, el controlador Rust asíncrono y de código abierto para el protocolo nativo de IRIS: SQL, inserciones masivas, procedimientos y globals, con ejemplos y una matriz de compatibilidad.

sqlly-iris es un controlador Rust asíncrono de código abierto para InterSystems IRIS. Habla el protocolo xDBC nativo directamente con el puerto del superservidor IRIS, así que no necesita gestor de controladores ODBC ni biblioteca cliente del proveedor, y el crate no contiene ningún unsafe código. Es Apache-2.0 y está en la versión 0.1; aún no está en crates.io, así que añádelo como dependencia desde GitHub.

Lo que significa "soportado" aquí. Cada fila en la tabla al final indica cómo lo sabemos: probado significa que una prueba de integración en vivo lo ejecuta contra IRIS 2026.1 (protocolo 69), observado significa que vimos al servidor hacerlo pero no lo prometemos, y planificado significa que aún no. Que un opcode exista en el protocolo no cuenta como soporte.

Añadir la crate

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

Conectar, insertar, consultar

? los marcadores de posición se enlazan por posición y se dejan intactos dentro de cadenas, identificadores entre comillas y comentarios. Las fechas y horas llegan como texto ISO, como 1815-12-10, no $HOROLOG conteos de días, y el texto mantiene un carácter por punto de código tanto en Latin-1 como 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
}

Transacciones

Confirma o revierte explícitamente. Descartar una transacción sin hacer ninguna de las dos cosas retira la conexión a propósito, para que nada posterior se ejecute dentro de una transacción de la que nadie lleva el control.

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

Instrucciones preparadas e inserciones masivas

Con fast_insert activadas, IRIS toma los lotes elegibles INSERT lotes en una sola petición empaquetada. Las filas que el servidor rechaza se reportan una a una con su índice, SQLCODE y mensaje, y el resto también se escribe, así que envuelve el lote en una transacción si tiene que ser todo o nada.

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?;
Una peculiaridad de la inserción rápida que observamos: IRIS omite las comprobaciones de longitud de columna en filas empaquetadas, por lo que se almacenó un valor de 12 caracteres en un VARCHAR(5) columna. NOT NULL y las restricciones únicas se siguen aplicando. Valida tú las longitudes, o deja la inserción rápida desactivada para esa tabla.

Transmisión de resultados grandes

Las filas se recuperan a medida que las lees. Detente cuando quieras: al descartar la transmisión se desecha el resto y se cierra la instrucción antes de tu siguiente solicitud, y la conexión queda utilizable.

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

Procedimientos almacenados

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());
}

Globales y objetos

La mitad de IRIS que no es SQL. Un nodo que no existe se lee como Value::Null, y global_data te dice si un nodo tiene un valor, hijos o ambos.

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

Las raíces de confianza nativas se usan por defecto. Un archivo CA adicional se suma a ellas; no las reemplaza ni desactiva las comprobaciones de nombre de host, y Encryption::Required nunca vuelve a texto plano.

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 conexión

iris://user:password@host:port/NAMESPACE?option=value. El puerto por defecto es 1972, los hosts IPv6 van entre corchetes, los caracteres especiales del usuario o la contraseña necesitan codificación porcentual, y las opciones desconocidas se rechazan en lugar de ignorarse en silencio.

OpciónLo que hace
encryptiondisable (predeterminado) o require.
ca_certificateRuta a un archivo CA PEM adicional para TLS.
connect_timeoutSegundos permitidos en total para la conexión TCP, TLS y el inicio de sesión.
query_timeoutTiempo de espera de consulta del lado del servidor, en segundos.
max_rowsNúmero total de filas que IRIS devuelve por consulta. Es un límite, no un tamaño de obtención.
fast_insert1 o 0. Agrupa arrays de parámetros en una sola solicitud.
application_nameEl nombre que ve el servidor para esta conexión.

Lo que funciona hoy

Verificado contra IRIS 2026.1 build 234U en protocolo 69, la única versión probada hasta ahora. La matriz completa con su evidencia está en el repositorio docs/compatibility.md.

ÁreaEstadoNotas
Inicio de sesión con contraseñaprobadoLa codificación de la contraseña en tránsito es una ofuscación reversible, así que usa TLS en cualquier red que no sea tuya.
SQL directo y preparadoprobadoLas instrucciones se cierran cuando los resultados terminan o se descartan; la memoria del servidor se mantuvo estable a lo largo de 20.000 consultas.
Transacciones y aislamientoprobadoAutocommit, lectura confirmada, lectura no confirmada, commit y rollback.
Procedimientos almacenadosprobadoParámetros de entrada, valores de retorno escalares y varios conjuntos de resultados.
Arrays de parámetros e inserción rápidaprobadoTablas de identidad, clave primaria y clave compuesta, valores predeterminados, columnas reordenadas y fallos por fila.
Tipos de datosprobadoEnteros, decimales exactos, dobles, bits, texto Latin-1 y Unicode, binario, DATE, TIME, TIMESTAMP y texto y binario largos.
Globales, métodos, propiedadesprobadoLos errores nativos llegan con el mensaje de IRIS, por ejemplo <METHOD DOES NOT EXIST>.
CatálogoprobadoEsquemas, tablas, columnas y procedimientos.
TLSimplementadoEl rechazo de conexiones en texto plano ya está probado; un handshake correcto contra un servidor IRIS con TLS configurado, todavía no.
Comprobaciones de longitud en inserciones rápidasobservadoEl servidor no las aplica a filas empaquetadas.
Valores superiores a 65.534 bytesplanificadoHoy devuelve un error claro; los parámetros de flujo levantarán el límite.
Parámetros de salida, procedimientos preparadosplanificado
Claves generadasplanificadoAún no son fiables, así que no se anuncian.
Kerberos y OAuthplanificado
Cancelación del lado del clienteplanificadoEliminar una solicitud en curso retira la conexión en lugar de cancelar el trabajo del servidor.
Versiones antiguas de IRIS, XEP, vectoresplanificadoAún no investigado.
Independiente, y con buenas maneras. El trabajo del protocolo se basó en el de Apache-2.0 go-irisnative proyecto y comprobado contra los controladores ODBC y JDBC del proveedor. InterSystems e InterSystems IRIS son marcas registradas de InterSystems Corporation, y este proyecto no tiene ninguna afiliación con ellos. ¿Encontraste algún rincón de IRIS que se nos haya pasado? Abrir un issue con lo que ejecutaste y lo que IRIS respondió.