Драйвер InterSystems IRIS

sqlly-iris — асинхронный Rust-драйвер с открытым кодом для нативного протокола IRIS: SQL, массовые вставки, процедуры и глобалы, с примерами и матрицей поддержки.

sqlly-iris — это асинхронный драйвер на Rust с открытым кодом для InterSystems IRIS. Он говорит по нативному протоколу xDBC прямо с портом суперсервера IRIS, поэтому не нуждается ни в менеджере ODBC-драйверов, ни в клиентской библиотеке вендора, а в пакете нет unsafe код. Он под лицензией Apache-2.0, версия 0.1; его пока нет на crates.io, поэтому подключайте его через GitHub.

Что здесь означает «поддерживается». Каждая строка таблицы в конце объясняет, как мы это узнали: проверено означает, что живой интеграционный тест прогоняет его на IRIS 2026.1 (протокол 69), observed означает, что мы видели, как сервер это делает, но не обещаем этого, и запланировано означает пока нет. Существование кода операции в протоколе не считается поддержкой.

Добавьте crate

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

Подключиться, вставить, выполнить запрос

? заполнители привязываются позиционно и остаются нетронутыми внутри строк, идентификаторов в кавычках и комментариев. Даты и время приходят в виде ISO-текста, например 1815-12-10, а не $HOROLOG число дней, и текст хранит один символ на кодовую точку как в Latin-1, так и в 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
}

Транзакции

Явно зафиксируйте или откатите транзакцию. Если отбросить транзакцию, не сделав ни того, ни другого, соединение намеренно закрывается, чтобы ничего позже не выполнялось внутри транзакции, за которой никто не следит.

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

Подготовленные запросы и массовые вставки

С fast_insert включён, IRIS принимает подходящие INSERT пакеты в одном упакованном запросе. Отклонённые сервером строки сообщаются по одной, с индексом, SQLCODE и сообщением, а остальные всё равно записываются, так что оберните пакет в транзакцию, если операция должна быть «всё или ничего».

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?;
Одна особенность быстрой вставки, которую мы заметили: IRIS пропускает проверки длины столбцов для упакованных строк, поэтому значение из 12 символов было сохранено в VARCHAR(5) столбце. NOT NULL и уникальные ограничения всё ещё соблюдаются. Длину проверяйте сами или оставьте быструю вставку выключенной для этой таблицы.

Потоковая передача больших результатов

Строки извлекаются по мере чтения. Останавливайтесь когда угодно: если прервать поток, остальные строки отбрасываются, а оператор закроется до вашего следующего запроса — соединение останется рабочим.

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

Хранимые процедуры

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

Глобальные переменные и объекты

Не-SQL половина IRIS. Несуществующий узел возвращается как Value::Null, и global_data показывает, есть ли у узла значение, потомки или и то, и другое.

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

По умолчанию используются корневые сертификаты, встроенные в ОС. Дополнительный файл CA добавляется к ним; он не заменяет их и не отключает проверку имени хоста, и Encryption::Required никогда не переходит на открытый текст.

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 подключения

iris://user:password@host:port/NAMESPACE?option=value. Порт по умолчанию — 1972, хосты IPv6 пишутся в скобках, специальные символы в имени пользователя или пароле требуют процентного кодирования, а неизвестные параметры отклоняются, а не тихо игнорируются.

ОпцияЧто оно делает
encryptiondisable (по умолчанию) или require.
ca_certificateПуть к дополнительному PEM-файлу CA для TLS.
connect_timeoutСекунды на TCP-подключение, TLS и вход суммарно.
query_timeoutТайм-аут запроса на стороне сервера в секундах.
max_rowsОбщее количество строк, возвращаемых IRIS за один запрос. Это максимум, а не размер выборки.
fast_insert1 или 0. Упаковывает массивы параметров в один запрос.
application_nameИмя, под которым это подключение видит сервер.

Что работает сегодня

Проверено на IRIS 2026.1, сборка 234U, протокол 69 — единственной протестированной пока версии. Полная матрица с доказательствами лежит в репозитории docs/compatibility.md.

ПлощадьСостояниеЗаметки
Вход по паролюпровереноПароль в передаваемых данных закодирован лишь обратимой обфускацией, поэтому в любой сети, которая вам не принадлежит, используйте TLS.
Прямой и подготовленный SQLпровереноОператоры закрываются, когда результаты завершены или освобождены; память сервера не росла на протяжении 20 000 запросов.
Транзакции и изоляцияпровереноАвтокоммит, read committed, read uncommitted, commit и rollback.
Хранимые процедурыпровереноВходные параметры, скалярные возвращаемые значения и множественные наборы результатов.
Массивы параметров и быстрая вставкапровереноТаблицы с IDENTITY-столбцами, первичными и составными ключами, значения по умолчанию, изменённый порядок столбцов и ошибки в отдельных строках.
Типы данныхпровереноЦелые числа, точные десятичные, числа двойной точности, биты, текст Latin-1 и Unicode, двоичные данные, DATE, TIME, TIMESTAMP, а также длинный текст и двоичные данные.
Глобальные переменные, методы, свойствапровереноНативные ошибки возвращаются с сообщением IRIS, например <METHOD DOES NOT EXIST>.
КаталогпровереноСхемы, таблицы, столбцы и процедуры.
TLSреализованоОтказ при подключении без шифрования протестирован; успешное рукопожатие с сервером IRIS, настроенным на TLS, пока нет.
Проверки длины при быстрой вставкеobservedСервер не применяет их к упакованным строкам.
Значения больше 65 534 байтзапланированоСегодня возвращает явную ошибку; параметры потока снимут ограничение.
Выходные параметры, подготовленные процедурызапланировано
Сгенерированные ключизапланированоПока ненадёжно, поэтому об этом не заявляем.
Kerberos и OAuthзапланировано
Отмена на стороне клиентазапланированоПрерывание выполняющегося запроса выводит соединение из использования, а не отменяет работу на сервере.
Более старые версии IRIS, XEP, векторызапланированоЕщё не изучено.
Независимая работа — и вежливо об этом сказано. Работа над протоколом опиралась на выпущенный под Apache-2.0 go-irisnative проект проверен по ODBC- и JDBC-драйверам производителя. InterSystems и InterSystems IRIS — торговые марки InterSystems Corporation, и этот проект с ней не связан. Нашли уголок IRIS, который мы пропустили? Создайте issue с информацией о том, что вы запустили и что IRIS ответил.