Driver InterSystems IRIS

sqlly-iris, o driver Rust assíncrono open-source para o protocolo nativo IRIS: SQL, inserções em lote, procedures e globals, com exemplos e uma matriz de suporte.

sqlly-iris é um driver Rust assíncrono e de código aberto para InterSystems IRIS. Ele utiliza o protocolo xDBC nativo diretamente na porta do superservidor IRIS, portanto, não necessita de gerenciador de driver ODBC nem de biblioteca cliente do fornecedor, e o crate não contém nenhum unsafe código. É Apache-2.0 e está na versão 0.1; ainda não está no crates.io, então dependa dele a partir do GitHub.

O que «suportado» significa aqui. Cada linha na tabela no final diz como sabemos: testado significa que um teste de integração real o executa contra o IRIS 2026.1 (protocolo 69), observado significa que observamos o servidor fazê-lo, mas não prometemos que funcione, e planejado significa ainda não. Um opcode existente no protocolo não conta como suporte.

Adicionar o crate

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

Conectar, inserir, consultar

? os placeholders são vinculados posicionalmente e permanecem intactos dentro de strings, identificadores entre aspas e comentários. Datas e horários chegam como texto ISO, como 1815-12-10, não $HOROLOG contagens de dias, e o texto mantém um caractere por ponto de código tanto em Latin-1 quanto em 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
}

Transações

Confirme ou faça rollback explicitamente. Descartar uma transação sem nenhuma das duas ações aposenta a conexão deliberadamente, para que nada mais rode dentro de uma transação que ninguém controla.

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

Instruções preparadas e inserções em massa

Com fast_insert ativado, o IRIS aceita lotes elegíveis INSERT em uma solicitação empacotada. Linhas que o servidor recusa são relatadas uma a uma com seu índice, SQLCODE e mensagem, e o restante ainda é gravado, então envolva o lote em uma transação se precisar ser tudo ou 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?;
Uma peculiaridade do fast-insert que observamos: IRIS não verifica o tamanho das colunas em linhas compactadas, então um valor de 12 caracteres foi armazenado em um VARCHAR(5) coluna. NOT NULL e restrições de unicidade ainda são aplicadas. Valide os comprimentos você mesmo, ou desative o fast insert para essa tabela.

Streaming de grandes resultados

As linhas são buscadas à medida que você lê. Pare quando quiser: descartar o stream joga fora o restante e fecha a instrução antes da sua próxima solicitação, e a conexão continua utilizável.

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

Procedimentos armazenados

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

Globais e objetos

A metade não-SQL do IRIS. Um nó que não existe é lido como Value::Null, e global_data diz se um nó tem valor, filhos ou 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

As raízes de confiança nativas são usadas por padrão. Um arquivo CA extra é adicionado a elas; não as substitui nem desativa as verificações de hostname, e Encryption::Required nunca cai para texto simples.

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 conexão

iris://user:password@host:port/NAMESPACE?option=value. A porta padrão é 1972, hosts IPv6 vão entre colchetes, caracteres especiais no nome de usuário ou senha precisam de percent-encoding, e opções desconhecidas são rejeitadas em vez de ignoradas em silêncio.

OpçãoO que faz
encryptiondisable (padrão) ou require.
ca_certificateCaminho para um arquivo PEM CA adicional para TLS.
connect_timeoutSegundos permitidos para conexão TCP, TLS e login, combinados.
query_timeoutTempo limite de consulta do lado do servidor, em segundos.
max_rowsTotal de linhas que o IRIS retorna por consulta. É um limite, não um tamanho de busca.
fast_insert1 ou 0. Agrupa arrays de parâmetros em uma única requisição.
application_nameO nome que o servidor vê para esta conexão.

O que funciona hoje

Verificado contra IRIS 2026.1 build 234U no protocolo 69, a única versão testada até agora. A matriz completa com as evidências está no repositório docs/compatibility.md.

ÁreaEstadoNotas
Login com senhatestadoA codificação da senha na transmissão é uma ofuscação reversível, então use TLS em qualquer rede que você não possua.
SQL direto e preparadotestadoInstruções são fechadas quando os resultados terminam ou são descartados; a memória do servidor permaneceu estável em 20.000 consultas.
Transações e isolamentotestadoAutocommit, leitura confirmada, leitura não confirmada, commit e rollback.
Procedimentos armazenadostestadoParâmetros de entrada, retornos escalares e múltiplos conjuntos de resultados.
Arrays de parâmetros e inserção rápidatestadoTabelas com coluna de identidade, chave primária e chave composta, valores padrão, colunas reordenadas e falhas por linha.
Tipos de dadostestadoInteiros, decimais exatos, doubles, bits, texto Latin-1 e Unicode, binário, DATE, TIME, TIMESTAMP, além de texto e binário longos.
Globais, métodos, propriedadestestadoErros nativos retornam com a mensagem do IRIS, por exemplo <METHOD DOES NOT EXIST>.
CatálogotestadoEsquemas, tabelas, colunas e procedimentos.
TLSimplementadoA recusa de conexões em texto puro é testada; um handshake bem-sucedido contra um servidor IRIS configurado com TLS, ainda não.
Verificações de comprimento para inserções rápidasobservadoO servidor não as aplica a linhas empacotadas.
Valores acima de 65.534 bytesplanejadoHoje ele retorna um erro claro; parâmetros de streaming vão levantar esse limite.
Parâmetros de saída, procedimentos preparadosplanejado
Chaves geradasplanejadoAinda não confiável, portanto não divulgado.
Kerberos e OAuthplanejado
Cancelamento no lado do clienteplanejadoDescartar uma requisição em andamento aposenta a conexão, em vez de cancelar o trabalho do servidor.
Versões mais antigas do IRIS, XEP, vetoresplanejadoAinda não pesquisado.
Independente, e educado ao dizer isso. O trabalho no protocolo teve como referência a Apache-2.0 go-irisnative projeto e verificado contra os drivers ODBC e JDBC do fornecedor. InterSystems e InterSystems IRIS são marcas comerciais da InterSystems Corporation, e este projeto não é afiliado a ela. Encontrou algum detalhe do IRIS que deixamos passar? Abra uma issue com o que você executou e o que o IRIS respondeu.