2个版本
0.1.1 | 2022年3月30日 |
---|---|
0.1.0 | 2022年1月21日 |
#2615 在 数据库接口
205KB
3K SLoC
Rust Arango
rust_arango
是由 ManevilleF 的 arangors lite 和 fMeow 的 arangors 衍生而来的。
rust_arango
允许您连接到 ArangoDB 服务器,访问数据库,执行 AQL 查询,以简单直观的方式管理 ArangoDB,支持任何您喜欢的 HTTP 生态系统中的异步和同步代码。
rust_arango 的哲学
rust_arango
致力于为 ArangoDB 提供舒适、直观且类似 OOP 的 API,提供顶级和底层 API 以供用户选择。
ArangoDB 的整体架构
数据库 -> 集合 -> 文档/边
实际上,rust_arango
的设计模仿了这种架构,略有不同的是,在顶级有一个数据库对象,包含用于认证信息的 HTTP 客户端。
rust_arango 的层次结构
连接 -> 数据库 -> 集合 -> 文档/边
特性
截至目前,rust_arango 的可用功能包括
- 连接到 ArangoDB
- 获取数据库和集合列表
- 获取数据库和集合信息
- 创建和删除数据库或集合
- 全功能 AQL 查询
- 支持异步和同步
概述
使用异步或同步代码
[dependencies]
## This one is async
rust_arango = { version = "0.1" }
## This one is synchronous
rust_arango = { version = "0.1", features = ["blocking"] }
得益于 maybe_async
,rust_arango
可以统一同步和异步 API,并通过功能门进行切换。rust_arango 采用异步优先策略。
默认情况下,reqwest
使用 OpenSSL。要使用 rustls
,您可能需要禁用默认功能并使用 rustls
功能。
[dependencies]
## This one uses openssl
rust_arango = { version = "0.1" }
## This one rustls
rust_arango = { version = "0.1", features = ["rustls"], default-features = false }
连接
建立连接有三种方式
- jwt
- 基本认证
- 无认证
rust_arango API 也是如此。
示例
- 带认证
use rust_arango::Connection;
// (Recommended) Handy functions
let conn = Connection::establish_jwt("https://127.0.0.1:8529", "username", "password")
.await
.unwrap();
let conn = Connection::establish_basic_auth("https://127.0.0.1:8529", "username", "password")
.await
.unwrap();
- 不带认证,仅用于评估环境
let conn = Connection::establish_without_auth("https://127.0.0.1:8529").await.unwrap();
数据库 && 集合
use rust_arango::Connection;
let db = conn.db("test_db").await.unwrap();
let collection = db.collection("test_collection").await.unwrap();
AQL 查询
所有与 AQL 查询相关的函数都与数据库相关联,因为 AQL 查询是在数据库级别执行的。
执行 AQL 查询有几种方式,可以分为两类
-
带游标的批量查询
aql_query_batch
aql_next_batch
-
获取所有结果的查询
aql_str
aql_bind_vars
aql_query
后一种提供了方便的高级 API,而批量查询提供了更多的控制。
类型化或非类型化
请注意,来自 ArangoDB 服务器的结果,例如获取的文档,可以给定可反序列化的结构体或具有 serde::Value
的任意 JSON 对象进行强类型化。
#[derive(Deserialize, Debug)]
struct User {
pub username: String,
pub password: String,
}
// Typed
let resp: Vec<User> = db
.aql_str("FOR u IN test_collection RETURN u")
.await
.unwrap();
// Not typed: Arbitrary JSON objects
let resp: Vec<serde_json::Value> = db
.aql_str("FOR u IN test_collection RETURN u")
.await
.unwrap();
批量查询
rust_arango
提供了一种手动处理批量查询的方法。
使用 aql_query_batch
获取游标,并使用 aql_next_batch
获取下一批结果并使用游标更新游标。
let aql = AqlQuery::builder()
.query("FOR u IN @@collection LIMIT 3 RETURN u")
.bind_var("@collection", "test_collection")
.batch_size(1)
.count(true)
.build();
// fetch the first cursor
let mut cursor = db.aql_query_batch(aql).await.unwrap();
// see metadata in cursor
println!("count: {:?}", cursor.count);
println!("cached: {}", cursor.cached);
let mut results: Vec<serde_json::Value> = Vec::new();
loop {
if cursor.more {
let id = cursor.id.unwrap().clone();
// save data
results.extend(cursor.result.into_iter());
// update cursor
cursor = db.aql_next_batch(id.as_str()).await.unwrap();
} else {
break;
}
}
println!("{:?}", results);
获取所有结果
有三种 AQL 查询函数可以获取 ArangoDB 中的所有结果。这些函数内部逐个获取批量结果以获取所有结果。
获取所有结果的功能如下所示
aql_str
此函数只接受 AQL 查询字符串。
以下是一个使用 aql_str
的强类型查询结果的示例
#[derive(Deserialize, Debug)]
struct User {
pub username: String,
pub password: String,
}
let result: Vec<User> = db
.aql_str(r#"FOR i in test_collection FILTER i.username=="test2" return i"#)
.await
.unwrap();
aql_bind_vars
此函数可以用于以绑定变量开始 AQL 查询。
use rust_arango::{Connection, Document};
#[derive(Serialize, Deserialize, Debug)]
struct User {
pub username: String,
pub password: String,
}
let mut vars = HashMap::new();
let user = User {
username: "test".to_string(),
password: "test_pwd".to_string(),
};
vars.insert("user", serde_json::value::to_value(&user).unwrap());
let result: Vec<Document<User>> = db
.aql_bind_vars(r#"FOR i in test_collection FILTER i==@user return i"#, vars)
.await
.unwrap();
aql_query
此函数提供了调整 AQL 查询的所有选项。用户必须首先构建一个 AqlQuery
对象。然后 AqlQuery
提供了调整 AQL 查询所需的所有选项。您可以设置批量大小、添加绑定变量、限制内存,以及其他所有选项。
use rust_arango::{AqlQuery, Connection, Cursor, Database};
use serde_json::value::Value;
let aql = AqlQuery::builder()
.query("FOR u IN @@collection LIMIT 3 RETURN u")
.bind_var("@collection", "test_collection")
.batch_size(1)
.count(true)
.build();
let resp: Vec<Value> = db.aql_query(aql).await.unwrap();
println!("{:?}", resp);
贡献
欢迎按照 Github 工作流程进行贡献和反馈。
许可
rust_arango
在 MIT 许可下提供。见 LICENSE。一个 Rust 的舒适 ArangoDB 客户端。
依赖关系
~4–17MB
~275K SLoC