Awesome
redis-macros
Simple macros and wrappers to redis-rs to automatically serialize and deserialize structs with serde.
Installation
To install it, simply add the package redis-macros
. This package is a helper for redis
and uses serde
and serde_json
(or any other serializer), so add these too to the dependencies.
[dependencies]
redis-macros = "0.3.0"
redis = { version = "0.25.2" }
serde = { version = "1.0", features = ["derive"] }
serde_json = { version = "1.0" }
Basic usage
Simple usage
The simplest way to start is to derive Serialize
, Deserialize
, FromRedisValue
, ToRedisArgs
for any kind of struct... and that's it! You can now get and set these values with regular redis commands:
use redis::{Client, Commands, RedisResult};
use redis_macros::{FromRedisValue, ToRedisArgs};
use serde::{Deserialize, Serialize};
#[derive(Serialize, Deserialize)]
enum Address {
Street(String),
Road(String),
}
// Derive the necessary traits
#[derive(Serialize, Deserialize, FromRedisValue, ToRedisArgs)]
struct User {
id: u32,
name: String,
addresses: Vec<Address>,
}
fn main () -> redis::RedisResult<()> {
let client = redis::Client::open("redis://localhost:6379/")?;
let mut con = client.get_connection()?;
let user = User {
id: 1,
name: "Ziggy".to_string(),
addresses: vec![
Address::Street("Downing".to_string()),
Address::Road("Abbey".to_string()),
],
};
// Just use it as you would a primitive
con.set("user", user)?;
// user and stored_user will be the same
let stored_user: User = con.get("user")?;
}
For more information, see the Basic or Async examples.
Usage with RedisJSON
You can even use it with RedisJSON, to extract separate parts of the object.
// Use `JsonCommands`
use redis::{Client, JsonCommands, RedisResult};
// Derive FromRedisValue, ToRedisArgs to the inner struct
#[derive(Serialize, Deserialize, FromRedisValue, ToRedisArgs)]
enum Address { /* ... */ }
// Simple usage is equivalent to set-get
con.json_set("user", "$", &user)?;
let stored_user: User = con.json_get("user", "$")?;
// But you can get deep values - don't forget to derive traits for these too!
let stored_address: Address = con.json_get("user", "$.addresses[0]")?;
For more information, see the RedisJSON example.
One issue you might be facing is that redis
already has overrides for some types, for example Vec, String and most primitives. For this you have to use the Json wrapper.
// This WON'T work
let stored_addresses: Vec<Address> = con.json_get("user", "$.addresses")?;
Json wrapper with RedisJSON
To deserialize Vecs and primitive types when using RedisJSON, you cannot use the regular types, because these are non-compatible with RedisJSON. However redis-macros
exports a useful wrapper struct: Json
. When using RedisJSON, you can wrap your non-structs return values into this:
use redis_macros::Json;
// Return type can be wrapped into Json
let Json(stored_name): Json<String> = con.json_get("user", "$.name")?;
// It works with Vecs as well
let Json(stored_addresses): Json<Vec<Address>> = con.json_get("user", "$.addresses")?;
// ...now stored_addresses will be equal to user.addresses
If you only use RedisJSON, you can even do away with deriving FromRedisValue
and ToRedisArgs
, and use Json
everywhere.
#[derive(Serialize, Deserialize)]
struct User { /* ... */ }
// This works with simple redis-rs
con.json_set("user", "$", &user)?;
// ...and you can get back with Json wrapper
let Json(stored_user): Json<User> = con.json_get("user", "$")?;
For more information, see the Json Wrapper and Json Wrapper Advanced examples.
Using other serializer (e.g. serde-yaml)
In case you want to use another serializer, for example serde_yaml
, you can install it and use the derives, the same way you would. The only difference should be adding an attribute redis_serializer
under the derive, with the library you want to serialize with. You can use any Serde serializer as long as they support from_str
and to_string
methods. For the full list, see: Serde data formats.
#[derive(Debug, PartialEq, Serialize, Deserialize, FromRedisValue, ToRedisArgs)]
#[redis_serializer(serde_yaml)]
struct User { /* ... */ }
For more information, see the YAML example.
Using deadpool-redis or other crates
You can still use the macros if you are using a crate that reexports the redis
traits, for example deadpool-redis. The only change you have to make is to use
the reexported redis
package explicitly:
// In the case of deadpool-redis, bring the reexported crate into scope
use deadpool_redis::redis;
// Or if you are importing multiple things from redis, use redis::self
use deadpool_redis::{redis::{self, AsyncCommands}, Config, Runtime};
For more information, see the deadpool-redis example.
Testing
You can run the unit tests on the code with cargo test
:
cargo test
For integration testing, you can run the examples. You will need a RedisJSON compatible redis-server on port 6379, redis-stack docker image is recommended:
docker run -d --rm -p 6379:6379 --name redis docker.io/redis/redis-stack
cargo test --examples
# cleanup the container
docker stop redis
Coverage
For coverage, you can use grcov
. Simply install llvm-tools-preview
and grcov
if you don't have it already:
rustup component add llvm-tools-preview
cargo install grcov
You have to export a few flags to make it work properly:
export RUSTFLAGS='-Cinstrument-coverage'
export LLVM_PROFILE_FILE='.coverage/cargo-test-%p-%m.profraw'
And finally, run the tests and generate the output:
cargo test
cargo test --examples
grcov .coverage/ -s . --binary-path ./target/debug/ -t html --branch --ignore-not-existing -o ./target/debug/coverage/
Now you can open ./target/debug/coverage/index.html
, and view it in the browser to see the coverage.