Драйвер InterSystems IRIS
sqlly-iris — асинхронный Rust-драйвер с открытым кодом для нативного протокола IRIS: SQL, массовые вставки, процедуры и глобалы, с примерами и матрицей поддержки.
sqlly-iris — это асинхронный драйвер на Rust с открытым кодом для InterSystems IRIS. Он говорит по нативному протоколу xDBC прямо с портом суперсервера IRIS, поэтому не нуждается ни в менеджере ODBC-драйверов, ни в клиентской библиотеке вендора, а в пакете нет unsafe код. Он под лицензией Apache-2.0, версия 0.1; его пока нет на crates.io, поэтому подключайте его через GitHub.
Добавьте 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?;
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 пишутся в скобках, специальные символы в имени пользователя или пароле требуют процентного кодирования, а неизвестные параметры отклоняются, а не тихо игнорируются.
| Опция | Что оно делает |
|---|---|
encryption | disable (по умолчанию) или require. |
ca_certificate | Путь к дополнительному PEM-файлу CA для TLS. |
connect_timeout | Секунды на TCP-подключение, TLS и вход суммарно. |
query_timeout | Тайм-аут запроса на стороне сервера в секундах. |
max_rows | Общее количество строк, возвращаемых IRIS за один запрос. Это максимум, а не размер выборки. |
fast_insert | 1 или 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, векторы | запланировано | Ещё не изучено. |