/aerospike-client-rust

Rust client for the Aerospike database

Primary LanguageRustOtherNOASSERTION

Aerospike Rust Client crates-io docs travis appveyor

An Aerospike client library for Rust.

Notice: This is a work in progress. Use with discretion. Feedback, bug reports and pull requests are welcome!

This library is compatible with Rust v1.26+ and supports the following operating systems: Linux, Mac OS X, and Windows.

Usage:

The following is a very simple example of CRUD operations in an Aerospike database.

#[macro_use]
extern crate aerospike;

use std::env;
use std::time::Instant;

use aerospike::{Bins, Client, ClientPolicy, ReadPolicy, WritePolicy};
use aerospike::operations;

fn main() {
    let cpolicy = ClientPolicy::default();
    let hosts = env::var("AEROSPIKE_HOSTS")
        .unwrap_or(String::from("127.0.0.1:3000"));
    let client = Client::new(&cpolicy, &hosts)
        .expect("Failed to connect to cluster");

    let now = Instant::now();
    let rpolicy = ReadPolicy::default();
    let wpolicy = WritePolicy::default();
    let key = as_key!("test", "test", "test");

    let bins = [
        as_bin!("int", 999),
        as_bin!("str", "Hello, World!"),
    ];
    client.put(&wpolicy, &key, &bins).unwrap();
    let rec = client.get(&rpolicy, &key, Bins::All);
    println!("Record: {}", rec.unwrap());

    client.touch(&wpolicy, &key).unwrap();
    let rec = client.get(&rpolicy, &key, Bins::All);
    println!("Record: {}", rec.unwrap());

    let rec = client.get(&rpolicy, &key, Bins::None);
    println!("Record Header: {}", rec.unwrap());

    let exists = client.exists(&wpolicy, &key).unwrap();
    println!("exists: {}", exists);

    let bin = as_bin!("int", "123");
    let ops = &vec![operations::put(&bin), operations::get()];
    let op_rec = client.operate(&wpolicy, &key, ops);
    println!("operate: {}", op_rec.unwrap());

    let existed = client.delete(&wpolicy, &key).unwrap();
    println!("existed (sould be true): {}", existed);

    let existed = client.delete(&wpolicy, &key).unwrap();
    println!("existed (should be false): {}", existed);

    println!("total time: {:?}", now.elapsed());
}

Known Limitations

The client currently supports all single-key operations supported by Aerospike, incl. the operate command with full support of List and (Sorted) Map operations. The client also supports scan and query operations incl. support for User-Defined Functions in the Lua scripting language, as well as APIs to manage secondary indexes. For Aerospike Enterprise edition deployments the client supports managing users and roles.

However the following features are not yet supported in the Aerospike Rust client:

  • Query Aggregation using Lua User-Defined Functions (which requires integrating the Lua run-time environment into the client)
  • Async Task operations (like execute UDF on scan/queries, index drop/create operations, etc.)
  • Secure connections using TLS (requires AS 3.10+)
  • IPv6 support

Tests

This library is packaged with a number of tests. The tests assume that an Aerospike cluster is running at localhost:3000. To test using a cluster at a different address, set the AEROSPIKE_HOSTS environment variable to the list of cluster hosts.

To run all the test cases:

$ export AEROSPIKE_HOSTS=127.0.0.1:3000
$ cargo test
``

To enable debug logging for the `aerospike` crate:

```shell
$ RUST_LOG=aerospike=debug cargo test

To enable backtraces set the RUST_BACKTRACE environment variable:

$ RUST_BACKTRACE=1 cargo test

Benchmarks

The micro-benchmarks in the benches directory use the bencher crate and can be run on Rust stable releases:

$ export AEROSPIKE_HOSTS=127.0.0.1:3000
$ cargo bench

There is a separate benchmark tool under the tools/benchmark directory that is designed to insert data into an Aerospike server cluster and generate load.