2个版本

0.1.1 2022年3月30日
0.1.0 2022年1月21日

#2615数据库接口

MIT 协议

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_asyncrust_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