Rust gRPC客户端驱动程序

此crate提供用于查询Stargate的高级异步Rust驱动程序。它公开了由gRPC proto文件生成的客户端存根以及一组实用工具，使它们更容易使用。

• 功能
• 快速入门指南
• 构建
• 运行示例

功能

• 所有Stargate gRPC协议消息都作为Rust结构和枚举公开
• 基于令牌的认证
• 异步查询
• 带有通过名称或位置轻松绑定变量的查询构建器
• 查询绑定值的编译时类型检查（可选）
• 轻松在gRPC值类型和常用Rust类型之间进行转换；支持基本类型、列表、映射、元组和用户定义类型，具有任意嵌套级别
• 结果集分页

快速入门指南

添加所需依赖项。您至少需要stargate-grpc和一个异步框架，例如tokio或async-std。

[dependencies]
stargate-grpc = "0.3"
tokio = { version = "1", features = ["full"]}

此时，您应该可以使用cargo build构建项目，并且它会获取和编译依赖项。

为了方便起见，将以下行添加到应用程序源代码的包含中

use stargate_grpc::*;

以下所有代码都假设在异步上下文中执行（例如，在async main内部）。

连接

提供Stargate接口的主要结构是StargateClient。获取实例的最简单方法是使用提供的builder

use std::str::FromStr;

let mut client = StargateClient::builder()
    .uri("https://127.0.0.1:8090/")?                           // replace with a proper address
    .auth_token(AuthToken::from_str("XXXX-YYYY-ZZZZ...")?)    // replace with a proper token
    .tls(Some(client::default_tls_config()?))                 // optionally enable TLS
    .connect()
    .await?;

查询

使用Query::builder创建查询，绑定查询值并传递查询参数

let query = Query::builder()
    .keyspace("test")                                         // set the keyspace the query applies to
    .consistency(Consistency::LocalQuorum)                    // set consistency level
    .query("SELECT login, emails FROM users WHERE id = :id")  // set the CQL string
    .bind_name("id", 1000)                                    // bind :id to 1000
    .build();                                                 // build the Query

运行查询并等待其结果

use std::convert::TryInto;

let response = client.execute_query(query).await?;  // send the query and wait for gRPC response
let result_set: ResultSet = response.try_into()?;   // convert the response to a ResultSet

处理结果集

结果集以行集合的形式返回。一个Row可以轻松地解包到元组中

for row in result_set.rows {
    let (login, emails): (String, Vec<String>) = row.try_into()?;
    // ...
}

也可以将row中的每个字段分别移出，并将其转换为所需类型

for mut row in result_set.rows {
    let login: String = row.try_take(0)?;         // == row.values[0].take().try_into()?;
    let emails: Vec<String> = row.try_take(1)?;   // == row.values[1].take().try_into()?;
    // ...
}

从源代码构建

1. 安装Rust工具链

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   

2. 在项目的根目录中运行 build

   git clone https://github.com/stargate/stargate-grpc-rust-client stargate-grpc
   cd stargate-grpc
   cargo build
   

运行示例

为了方便，该项目包含一些位于 examples 目录中的示例，这些示例演示了连接、创建模式、插入数据和查询。您需要有一个运行的Stargate集群实例才能运行它。有关如何设置Stargate的详细信息，请参阅官方Stargate文档。

每个示例程序都接受Stargate协调器的URL、身份验证令牌和命名空间名称。

cargo run --example <example> [-- [--keyspace <keyspace>] [--token <token>] [--tls] [<url>]] 

身份验证令牌值也可以通过 SG_TOKEN 环境变量提供。

1. 使用Docker设置开发模式下的Stargate服务器

   docker run --name stargate \
    -p 8081:8081 \
    -p 8090:8090 \
    -d \
    -e CLUSTER_NAME=stargate \
    -e CLUSTER_VERSION=3.11 \
    -e DEVELOPER_MODE=true \
    stargateio/stargate-3_11:v1.0.42
   

2. 获取身份验证令牌

   curl -L -X POST 'http://127.0.0.1:8081/v1/auth' \
        -H 'Content-Type: application/json' \
        --data-raw '{
           "username": "cassandra",
           "password": "cassandra"
        }'
          
   {"authToken":"2df7e75d-92aa-4cda-9816-f96ccbc91d80"}
   

3. 设置身份验证令牌变量

   export SG_TOKEN=2df7e75d-92aa-4cda-9816-f96ccbc91d80
   

4. 运行 keyspace 示例以测试连接并创建测试命名空间（默认命名空间名称：stargate_examples）

   cargo run --example keyspace 
   Connected to http://127.0.0.1:8090
   Created keyspace stargate_examples
   

5. 运行其他示例

   cargo run --example query 
   Finished dev [unoptimized + debuginfo] target(s) in 0.04s
   Running `target/debug/examples/basic`
   Connected to http://127.0.0.1:8090
   Created schema
   Inserted data. Now querying.
   All rows:
   2 user_2 ["[email protected]", "[email protected]"]
   3 user_3 ["[email protected]", "[email protected]"]
   7 user_7 ["[email protected]", "[email protected]"]
   9 user_9 ["[email protected]", "[email protected]"]
   4 user_4 ["[email protected]", "[email protected]"]
   0 user_0 ["[email protected]", "[email protected]"]
   8 user_8 ["[email protected]", "[email protected]"]
   5 user_5 ["[email protected]", "[email protected]"]
   6 user_6 ["[email protected]", "[email protected]"]
   1 user_1 ["[email protected]", "[email protected]"]
   Row with id = 1:
   1 user_1 ["[email protected]", "[email protected]"]