Crate rustis

rustis is a Redis client for Rust.

Philosophy

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

Features

• Support all Redis Commands until Redis 7.0
• Async support (tokio or async-std)
• Different client types:
  • Single client
  • Multiplexed client
  • Pooled client manager (based on bb8)
• Automatic command batching
• Advanced reconnection & retry strategy
• Pipelining support
• Configuration with Redis URL or dedicated builder
• TLS support
• Transaction support
• Pub/sub support
• Sentinel support
• LUA Scripts/Functions support
• Cluster support
• Redis Stack support:
  • RedisJSON v2.4 support
  • RedisSearch v2.6 support
  • RedisGraph v2.10 support
  • RedisBloom v2.4 support
  • RedisTimeSeries v1.8 support

Optional Features

Feature	Description
tokio-runtime	Tokio runime (default)
async-std-runtime	async-std runtime (optional)
tokio-tls	Tokio TLS support (optional)
async-std-tls	async-std TLS support (optional)
pool	Pooled client manager (optional)
redis-json	RedisJSON v2.4 support (optional)
redis-search	RedisSearch v2.6 support (optional)
redis-graph	RedisGraph v2.10 support (optional)
redis-bloom	RedisBloom v2.4 support (optional)
redis-time-series	RedisTimeSeries v1.8 support (optional)
redis-stack	activate 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:

• send
• send_and_forget
• send_batch

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

pub use bb8;

Modules

client

Defines types related to the clients structs and their dependencies: Client, PooledClientManager, Pipeline, Transaction and how to configure them

commands

Define Redis built-in commands in a set of traits

resp

Defines types related to the RESP protocol and their encoding/decoding

Structs

RedisError

Error issued by the Redis server

Enums

Error

All error kinds

RedisErrorKind

Redis server error kind

Type Aliases

Future

Library general future type.

Result

Library general result type.