Welcome to Riak.

Overview

Riak is a distributed, decentralized data storage system.

Below, you will find the “quick start” directions for setting up and using Riak. For more information, browse the following files:

README: this file
TODO: a list of improvements planned for Riak
LICENSE: the license under which Riak is released
apps/ the source tree for Riak and all its dependencies
doc/
- admin.org: Riak Administration Guide
- architecture.txt: details about the underlying design of Riak
- basic-client.txt: slightly more detail on using Riak
- basic-setup.txt: slightly more detail on setting up Riak
- basic-mapreduce.txt: introduction to map/reduce on Riak
- js-mapreduce.org: using Javascript with Riak map/reduce
- man/riak.1.gz: manual page for the riak(1) command
- man/riak-admin.1.gz manual page for the riak-admin(1) command
- raw-http-howto.txt: using the Riak HTTP interface

Quick Start

This section assumes that you have copy of the Riak source tree. To get started, you need to:

Build Riak
Start the Riak server
Connect a client and store/fetch data

Building Riak

Assuming you have a working Erlang (R13B04 or later) installation, building Riak should be as simple as:

$ cd $RIAK
$ make rel

Starting Riak

Once you have successfully built Riak, you can start the server with the following commands:

$ cd $RIAK/rel/riak
$ bin/riak start

Now, verify that the server started up cleanly and is working:

$ bin/riak-admin test

Note that the $RIAK/rel/riak directory is a complete, self-contained instance of Riak and Erlang. It is strongly suggested that you move this directory outside the source tree if you plan to run a production instance.

Connecting a client to Riak

Now that you have a functional server, let’s try storing some data in it. First, start up a erlang node using our embedded version of erlang:

$ erts-<vsn>/bin/erl -name riaktest@127.0.0.1 -setcookie riak

Eshell V5.7.4  (abort with ^G)
(riaktest@127.0.0.1)1>

Now construct the node name of Riak server and make sure we can talk to it:

(riaktest@127.0.0.1)4> RiakNode = 'riak@127.0.0.1'.

(riaktest@127.0.0.1)2> net_adm:ping(RiakNode).
pong
(riaktest@127.0.0.1)2>

We are now ready to start the Riak client:

(riaktest@127.0.0.1)2> {ok, C} = riak:client_connect(RiakNode).
{ok,{riak_client,'riak@127.0.0.1',<<4,136,81,151>>}}

Let’s create a shopping list for bread at /groceries/mine:

(riaktest@127.0.0.1)6> O0 = riak_object:new(<<"groceries">>, <<"mine">>, ["bread"]).
O0 = riak_object:new(<<"groceries">>, <<"mine">>, ["bread"]).
{r_object,<<"groceries">>,<<"mine">>,
       [{r_content,{dict,0,16,16,8,80,48,
                         {[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                         {{[],[],[],[],[],[],[],[],[],[],[],[],...}}},
                   ["bread"]}],
       [],
       {dict,1,16,16,8,80,48,
             {[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
             {{[],[],[],[],[],[],[],[],[],[],[],[],[],...}}},
       undefined}

 (riaktest@127.0.0.1)3> C:put(O0, 1).

Now, read the list back from the Riak server and extract the value

(riaktest@127.0.0.1)4> {ok, O1} = C:get(<<"groceries">>, <<"mine">>, 1).
{ok,{r_object,<<"groceries">>,<<"mine">>,
          [{r_content,{dict,2,16,16,8,80,48,
                            {[],[],[],[],[],[],[],[],[],[],[],[],...},
                            {{[],[],[],[],[],[],
                              [["X-Riak-Last-Modified",87|...]],
                              [],[],[],...}}},
                      ["bread"]}],
          [{"20090722191020-riaktest@127.0.0.1-riakdemo@127.0.0.1-266664",
            {1,63415509105}}],
          {dict,0,16,16,8,80,48,
                {[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                {{[],[],[],[],[],[],[],[],[],[],[],...}}},
          undefined}}

 (riaktest@127.0.0.1)5> %% extract the value
 (riaktest@127.0.0.1)5> V = riak_object:get_value(O1).
 ["bread"]

Add milk to our list of groceries and write the new value to Riak:

(riaktest@127.0.0.1)6> %% add milk to the list
(riaktest@127.0.0.1)6> O2 = riak_object:update_value(O1, ["milk" | V]).
{r_object,<<"groceries">>,<<"mine">>,
     [{r_content,{dict,2,16,16,8,80,48,
                       {[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                       {{[],[],[],[],[],[],
                         [["X-Riak-Last-Modified",87,101,100|...]],
                         [],[],[],[],[],...}}},
                 ["bread"]}],
     [{"20090722191020-riaktest@127.0.0.1-riakdemo@127.0.0.1-266664",
       {1,63415509105}}],
     {dict,0,16,16,8,80,48,
           {[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
           {{[],[],[],[],[],[],[],[],[],[],[],[],[],...}}},
     ["milk","bread"]}

(riaktest@127.0.0.1)7> %% store the new list
(riaktest@127.0.0.1)7> C:put(O2, 1).
ok

Finally, see what other keys are available in groceries bucket:

(riaktest@127.0.0.1)8> C:list_keys(<<"groceries">>).
{ok,[<<"mine">>]}

Clients for Other Languages

Client libraries are available for many languages. Rather than bundle them with the Riak server source code, we have given them each their own source repository. Currently, official Riak client language libraries include:

Javascript https://github.com/basho/riak-javascript-client
Python

https://github.com/basho/riak-python-client

Ruby http://github.com/seancribbs/ripple/
Java

https://github.com/basho/riak-java-client

PHP https://github.com/basho/riak-php-client
Erlang https://github.com/basho/riak-erlang-client (using protocol buffers instead of distributed Erlang)

Server Management

Configuration

Configuration for the Riak server is stored in $RIAK/rel/riak/etc directory. There are two files:

vm.args This file contains the arguments that are passed to the Erlang VM in which Riak runs. The default settings in this file shouldn’t need to be changed for most environments.
app.config This file contains the configuration for the Erlang applications that run on the Riak server.

More information about this files is available in doc/basic-setup.txt.

Server Control

bin/riak

This script is the primary interface for starting and stopping the Riak server.

To start a daemonized (background) instance of Riak:

$ bin/riak start

Once a server is running in the background you can attach to the Erlang console via:

$ bin/riak attach

Alternatively, if you want to run a foreground instance of Riak, start it with:

$ bin/riak console

Stopping a foreground or background instance of Riak can be done from a shell prompt via:

$ bin/riak stop

Or if you are attached/on the Erlang console:

(riak@127.0.0.1)1> q().

You can determine if the server is running by:

$ bin/riak ping

bin/riak-admin

This script provides access to general administration of the Riak server. The below commands assume you are running a default configuration for parameters such as cookie.

To join a new Riak node to an existing cluster:

$ bin/riak start # If a local server is not already running
$ bin/riak-admin join <node in cluster>

(Note that you must have a local node already running for this to work)

To verify that the local Riak node is able to read/write data:

$ bin/riak-admin test

To backup a node or cluster run the following:

$ bin/riak-admin backup riak@X.X.X.X riak <directory/backup_file> node
$ bin/riak-admin backup riak@X.X.X.X riak <directory/backup_file> all

Restores can function in two ways, if the backup file was of a node the node will be restored and if the backup file contains the data for a cluster all nodes in the cluster will be restored.

To restore from a backup file:

$ riak-admin restore riak@X.X.X.X riak <directory/backup_file>

To view the status of a node:

$ bin/riak-admin status

If you change the IP or node name you will need to use the reip command:

$ bin/riak-admin reip <old_nodename> <new_nodename>

dreverri/riak