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.
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?;
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ção | O que faz |
|---|---|
encryption | disable (padrão) ou require. |
ca_certificate | Caminho para um arquivo PEM CA adicional para TLS. |
connect_timeout | Segundos permitidos para conexão TCP, TLS e login, combinados. |
query_timeout | Tempo limite de consulta do lado do servidor, em segundos. |
max_rows | Total de linhas que o IRIS retorna por consulta. É um limite, não um tamanho de busca. |
fast_insert | 1 ou 0. Agrupa arrays de parâmetros em uma única requisição. |
application_name | O 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.
| Área | Estado | Notas |
|---|---|---|
| Login com senha | testado | A 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 preparado | testado | Instruçõ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 isolamento | testado | Autocommit, leitura confirmada, leitura não confirmada, commit e rollback. |
| Procedimentos armazenados | testado | Parâmetros de entrada, retornos escalares e múltiplos conjuntos de resultados. |
| Arrays de parâmetros e inserção rápida | testado | Tabelas com coluna de identidade, chave primária e chave composta, valores padrão, colunas reordenadas e falhas por linha. |
| Tipos de dados | testado | Inteiros, 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, propriedades | testado | Erros nativos retornam com a mensagem do IRIS, por exemplo <METHOD DOES NOT EXIST>. |
| Catálogo | testado | Esquemas, tabelas, colunas e procedimentos. |
| TLS | implementado | A 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ápidas | observado | O servidor não as aplica a linhas empacotadas. |
| Valores acima de 65.534 bytes | planejado | Hoje ele retorna um erro claro; parâmetros de streaming vão levantar esse limite. |
| Parâmetros de saída, procedimentos preparados | planejado | |
| Chaves geradas | planejado | Ainda não confiável, portanto não divulgado. |
| Kerberos e OAuth | planejado | |
| Cancelamento no lado do cliente | planejado | Descartar uma requisição em andamento aposenta a conexão, em vez de cancelar o trabalho do servidor. |
| Versões mais antigas do IRIS, XEP, vetores | planejado | Ainda não pesquisado. |