Crate rustis

source ·
Expand description

rustis is a Redis client for Rust.

§Philosophy

  • Low allocations
  • Full async library
  • Lock free implementation
  • Rust idiomatic API

§Features

§Optional Features

FeatureDescription
tokio-runtimeTokio runime (default)
async-std-runtimeasync-std runtime (optional)
tokio-tlsTokio TLS support (optional)
async-std-tlsasync-std TLS support (optional)
poolPooled client manager (optional)
redis-jsonRedisJSON v2.4 support (optional)
redis-searchRedisSearch v2.6 support (optional)
redis-graphRedisGraph v2.10 support (optional)
redis-bloomRedisBloom v2.4 support (optional)
redis-time-seriesRedisTimeSeries v1.8 support (optional)
redis-stackactivate redis-json, redis-search, redis-graph, redis-bloom & redis-time-series at the same time (optional)

§Basic Usage

use rustis::{
    client::Client, 
    commands::{FlushingMode, ServerCommands, StringCommands},
    Result,
};

#[cfg_attr(feature = "tokio-runtime", tokio::main)]
#[cfg_attr(feature = "async-std-runtime", async_std::main)]
async fn main() -> Result<()> {
    // Connect the client to a Redis server from its IP and port
    let client = Client::connect("127.0.0.1:6379").await?;

    // Flush all existing data in Redis
    client.flushdb(FlushingMode::Sync).await?;

    // sends the command SET to Redis. This command is defined in the StringCommands trait
    client.set("key", "value").await?;

    // sends the command GET to Redis. This command is defined in the StringCommands trait
    let value: String = client.get("key").await?;
    println!("value: {value:?}");

    Ok(())
}

§Client

See the module client to discover which are the 3 usages of the Client struct and how to configure it.

You will also learn how to use pipeline, pub/sub and transactions.

§RESP

RESP is the Redis Serialization Protocol.

See the module resp to discover how rustis allows programmers to communicate with Redis in a Rust idiomatic way.

You will learn how to:

  • Manipulate the rustis object model, the enum Value, which is a generic Rust data structure over RESP.
  • Convert Rust type into Rust Commands with the Command struct and the ToArgs trait.
  • Convert Rust command responses into Rust type with serde and helpful marker traits.

§Commands

In order to send Commands to the Redis server, rustis offers two API levels:

  • High-level Built-in commands that implement all Redis 7.0 commands + Redis Stack commands.
  • Low-level Generic command API to express any request that may not exist in rustis:
    • new official commands not yet implemented by rustis.
    • commands exposed by additional Redis modules not included in Redis Stack.

§Built-in commands

See the module commands to discover how Redis built-in commands are organized in different traits.

§Generic command API

To use the generic command API, you can use the cmd function to specify the name of the command, followed by one or multiple calls to the Commmand::arg associated function to add arguments to the command.

This command can then be passed as a parameter to one of the following associated functions, depending on the client, transaction or pipeline struct used:

use rustis::{client::Client, resp::cmd, Result};

#[cfg_attr(feature = "tokio-runtime", tokio::main)]
#[cfg_attr(feature = "async-std-runtime", async_std::main)]
async fn main() -> Result<()> {
    let client = Client::connect("127.0.0.1:6379").await?;

    client
        .send(
            cmd("MSET")
                .arg("key1")
                .arg("value1")
                .arg("key2")
                .arg("value2")
                .arg("key3")
                .arg("value3")
                .arg("key4")
                .arg("value4"),
            None,
        )
        .await?
        .to::<()>()?;

    let values: Vec<String> = client
        .send(
            cmd("MGET").arg("key1").arg("key2").arg("key3").arg("key4"),
            None,
        )
        .await?
        .to()?;

    assert_eq!(vec!["value1".to_owned(), "value2".to_owned(), "value3".to_owned(), "value4".to_owned()], values);

    Ok(())
}

Re-exports§

Modules§

Structs§

Enums§

Type Aliases§

  • Future
    Library general future type.
  • Result
    Library general result type.