Developing with Riak Redis Add-on

This page will walk you through setting up your environment for development with Riak Redis Add-on (RRA), as well as present examples and configuration parameters for basic development operations.

Overview

Riak Redis Add-on (RRA) packages a cache proxy service. The cache proxy service provides accessibility to Riak KV, as a persistent data store, with Redis, as a cache through the various Redis client libraries and command-line interface tool redis-cli.

As with Riak KV, the cache proxy service almost always performs best and most predictably when you use the basic CRUD operations – Create, Read, Update, Delete – that you’d find in any key/value store. Learning these operations is a great place to start when beginning to develop applications that use RRA.

The set of clients (including recommendations) for Redis are listed at Redis clients. For brevity sake, examples provided here are in:

• Erlang (Eredis)
• Javascript (node_redis)
• Python (redis-py)
• Ruby (redis-rb)
• Scala (lettuce)
• Java, see the Scala examples. The code intentionally uses as few Scala tricks as possible to focus on the use of the Redis client.

Riak KV Setup

While you can use Riak Redis Add-on with Riak KV configured so either last_write_wins is set to ‘true’ or allow_mult is set to ‘true’, we recommend using the allow_mult setting in order to provide client sibling resolution in the event of a network partition. The examples and instructions on this page will assume allow_mult is set to ‘true’.

The cache proxy service is tested under both configurations. However, due to lack of support via the Redis protocol for returning multiple values for a single GET, effectively last_write_wins semantics apply.

For a deeper explanation of Riak KV’s configurable behaviors, see John Daily’s blog series part 4 .

Bucket Type Setup

Create a Bucket Type

If your application organizes data in a way that does not include bucket-type and instead only uses bucket to organize its keyspace, the default bucket-type can be used by omitting the bucket-type portion of the colon-delimited hierarchical namespaced key. Otherwise said, test:food is equivalent to default:test:food where the bucket-type is default, the bucket is test, and the key is food. For examples here, we will use rra:test:food to clearly use a bucket-type.

If your application organizes data including a bucket-type, ensure that that bucket-type is created in Riak without specifying the data type, so effectively an opaque value, ie a string. The following command provides an example of creating the bucket-type rra:

if ! riak admin bucket-type status rra >/dev/null 2>&1; then
    riak admin bucket-type create rra '{"props":{}}'
    riak admin bucket-type activate rra
fi

Set Bucket Props

The following is an example, using Riak KV’s default HTTP port, of setting allow_mult to ‘true’ and last_write_wins to ‘false’:

curl -XPUT -H 'Content-Type: application/json' \
         -d '{"props": {"allow_mult": true, "last_write_wins": false}}' \
         'http://127.0.0.1:8098/types/rra/buckets/test/props'

For additional configuration options see bucket properties.

Object/Key Operations

Riak KV organizes data into buckets, keys, and values, with bucket types acting as an additional namespace in Riak KV versions 2.0 and greater. Values, which we’ll refer to as objects, are identifiable by a unique key, and each key/value pair is stored in a bucket.

Objects accessed via the cache proxy service in Riak Redis Add-on are restricted to plaintext format. This plaintext format may be a simple string, JSON, XML, or other plaintext representations that can be parsed in the client application (e.g. YAML).

While buckets are a flat namespace in Riak KV and you can name them whatever you’d like (bucket or a90bf521c or ___), within the cache proxy service, Redis bucket_type:bucket:key is mapped to Riak KV bucket_type/bucket/key, so bucket type and bucket names should not contain colon (:). When not specified, bucket type defaults to “default”.

Outside of the above restriction, bucket names have no intrinsic significance beyond allowing you to store objects with the same key in different buckets.

The same goes for naming keys: many objects can have the same key as long as they’re in different buckets. There is no restriction on key containing colon (:), and this practice of representing a nested namespace is common in applications using Redis.

Riak KV bucket types enable you to provide common configurations for buckets (as many buckets as you wish). This means you can easily enable buckets to share common configurations, i.e. identical replication properties or commit hooks.

Reading Objects

Reads via the cache proxy service are analogous to a Redis GET, with the added benefit of reading-through to Riak KV which results in greater resilience through node outages and network partitions.

To request a value at a bucket/key in Riak KV, issue the following:

{ok, RedisClientPid} = eredis:start_link("127.0.0.1", 22122).
{ok, Value} = eredis:q(RedisClientPid, ["GET", "rra:test:food"]).

var redis = require("redis"),
    client = redis.createClient(22122, "127.0.0.1");

client.get("rra:test:food", redis.print);

import redis

r = redis.StrictRedis(host="127.0.0.1", port=22122)

r.get("rra:test:food")

require "redis"

redis = Redis.new(host: "127.0.0.1", port: 22122)

redis.get("rra:test:food")

import com.lambdaworks.redis._

var client = RedisClient.create("redis://127.0.0.1:22122")
var connection = client.connect()

var value = connection.get("rra:test:food")

Get Configuration Parameters

Note: The cache proxy service read option (related to replication factor and consistency concern) may optionally be set within the nutcracker.conf. This will result in an override of the setting value at the bucket-level in Riak KV.

The following configuration parameters apply to GET and may be set within the RRA configuration file /etc/cache_proxy/cache_proxy_22122.yml:

Sibling Resolution

As the Redis protocol does not provide a means to return multiple siblings, the cache proxy service must provide server-side sibling resolution. At present, only last-write-wins sibling resolution is available. The result is an effective last-write-wins configuration for access through the cache proxy service.

Writing Objects

Writes via the cache proxy service are analogous to a Redis SET, with the added benefit of writing to Riak KV followed by a PEXPIRE to Redis, invalidating cache. As with HTTP PUT, SET semantically covers both create and update operations.

To set a value at a bucket/key in Riak KV, issue the following:

{ok, RedisClientPid} = eredis:start_link("127.0.0.1", 22122).
{ok, KeysAffected} = eredis:q(RedisClientPid, ["SET", "rra:test:food", "apple"]).

var redis = require("redis"),
    client = redis.createClient(22122, "127.0.0.1");

client.set("rra:test:food", "apple", redis.print);

import redis

r = redis.StrictRedis(host="127.0.0.1", port=22122)

r.set("rra:test:food", "apple")

require "redis"

redis = Redis.new(host: "127.0.0.1", port: 22122)

redis.set("rra:test:food', 'apple")

import com.lambdaworks.redis._

var client = RedisClient.create("redis://127.0.0.1:22122")
var connection = client.connect()

connection.set("rra:test:food", "apple")

Set Configuration Parameters

Note: The cache proxy service write option (related to replication factor and consistency concern) may optionally be set within the nutcracker.conf, resulting in an override of the setting value at the bucket-level in Riak KV.

The following configuration parameters apply to SET and may be set within the RRA configuration file /etc/cache_proxy/cache_proxy_22122.yml:

Sibling Explosion

As noted in the section “Sibling Resolution” above, Riak KV provides for a line of descendency (known as the [causal context][concept causal context]) for a value stored at a key. Clients performing write operations provide this causal context by setting the vector clock (VClock) that they last read.

If a client does not provide the causal context, Riak KV makes no assumptions and treats the write as a new causal context, semantically equivalent to a create. In the case that a value is already stored at the key, this would lead to a sibling.

Since the Redis protocol does not provide a means to pass a VClock, the cache proxy service needs to perform a read-before-write to obtain the current VClock so the write can continue the causal context previously established and avoid “sibling explosion”.

Despite these efforts, in the event of a network partition, siblings will still be created as clients writing to nodes on either side of the network partition can create divergent lines of descendency. Sibling resolution remains the means to merge these lines of descent into a coherent causal context.

Deleting Objects

Deletes via the cache proxy service are analogous to a Redis DEL, with the added benefit of writing to Riak KV followed by a PEXPIRE to Redis, invalidating cache.

To delete a value at a bucket/key in Riak KV, issue the following:

{ok, RedisClientPid} = eredis:start_link("127.0.0.1", 22122).
{ok, KeysAffected} = eredis:q(RedisClientPid, ["DEL", "rra:test:food"]).

var redis = require("redis"),
    client = redis.createClient(22122, "127.0.0.1");

client.del("rra:test:food", redis.print);

import redis

r = redis.StrictRedis(host="127.0.0.1", port=22122)

r.del("rra:test:food")

require "redis"

redis = Redis.new(host: "127.0.0.1", port: 22122)

redis.del("rra:test:food")

import com.lambdaworks.redis._

var client = RedisClient.create("redis://127.0.0.1:22122")
var connection = client.connect()

connection.del("rra:test:food")

Delete Configuration Parameters

The following configuration parameters apply to DEL and may be set within the RRA configuration file /etc/cache_proxy/cache_proxy_22122.yml: