riak / README.org

Bryan Fink fefa52d 
dizzyd 01bca2b 





















dizzyd 68da746 

dizzyd 01bca2b 








Bryan Fink 4b6e77d 
dizzyd 01bca2b 

Bryan Fink 4b6e77d 
dizzyd 01bca2b 


dizzyd 68da746 

dizzyd 01bca2b 
Bryan Fink 4b6e77d 
dizzyd 01bca2b 

Bryan Fink 4b6e77d 
dizzyd 01bca2b 


Bryan Fink 4b6e77d 
dizzyd 01bca2b 
dizzyd 68da746 


dizzyd efcf70b 
dizzyd 01bca2b 

dizzyd 68da746 

dizzyd 01bca2b 
Bryan Fink 4b6e77d 
dizzyd dfec613 



Bryan Fink 4b6e77d 
dizzyd 01bca2b 
dizzyd dfec613 
dizzyd 01bca2b 
Bryan Fink 4b6e77d 
dizzyd dfec613 
dizzyd 01bca2b 
dizzyd dfec613 


Bryan Fink 4b6e77d 
dizzyd dfec613 


Bryan Fink 4b6e77d 
dizzyd dfec613 

Bryan Fink 4b6e77d 
dizzyd dfec613 


Bryan Fink 4b6e77d 
dizzyd dfec613 


dizzyd 01bca2b 




dizzyd dfec613 
dizzyd 01bca2b 



Bryan Fink ec5c681 
Bryan Fink 4b6e77d 
dizzyd dfec613 

dizzyd 01bca2b 
Bryan Fink 4b6e77d 
dizzyd dfec613 

dizzyd 01bca2b 





dizzyd dfec613 
dizzyd 01bca2b 





dizzyd dfec613 


Bryan Fink 4b6e77d 
dizzyd 01bca2b 
dizzyd dfec613 

Bryan Fink 4b6e77d 
dizzyd dfec613 


dizzyd 01bca2b 





dizzyd dfec613 
dizzyd 01bca2b 





dizzyd dfec613 


Bryan Fink 4b6e77d 
dizzyd 01bca2b 
dizzyd dfec613 
dizzyd 01bca2b 
Bryan Fink 4b6e77d 
dizzyd dfec613 

Bryan Fink 4b6e77d 
dizzyd efcf70b 




dizzyd 68da746 





dizzyd efcf70b 
dizzyd 68da746 


dizzyd efcf70b 
Bryan Fink 9d54ab0 

dizzyd efcf70b 

dizzyd 68da746 

dizzyd efcf70b 


Bryan Fink 4b6e77d 
dizzyd efcf70b 
dizzyd 68da746 

dizzyd efcf70b 
Bryan Fink 4b6e77d 
dizzyd efcf70b 
dizzyd 68da746 

dizzyd efcf70b 
Bryan Fink 4b6e77d 
dizzyd efcf70b 
dizzyd 68da746 

dizzyd efcf70b 
Bryan Fink 4b6e77d 
dizzyd efcf70b 


Bryan Fink 4b6e77d 
dizzyd efcf70b 


Bryan Fink 4b6e77d 
dizzyd efcf70b 





Bryan Fink 4b6e77d 
dizzyd efcf70b 

Bryan Fink 4b6e77d 
dizzyd efcf70b 




Bryan Fink 4b6e77d 
dizzyd efcf70b 


#+SETUPFILE: "doc/basho-doc-style.iorg"

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/
    - basic-setup.txt:  slightly more detail on setting up Riak
    - basic-client.txt: slightly more detail on using Riak
    - architecture.txt: details about the underlying design of Riak
    - index.html:       the root of the edoc output of 'make docs'


* Quick Start

  This section assumes that you have copy of the Riak source tree. To get
  started, you need to:
  1. Build Riak
  2. Start the Riak server
  3. Connect a client and store/fetch data

** Building Riak

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

#+BEGIN_EXAMPLE
   $ cd $RIAK
   $ make all rel
#+END_EXAMPLE

** Starting Riak

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

#+BEGIN_EXAMPLE
   $ cd $RIAK/rel/riak
   $ bin/riak start
#+END_EXAMPLE

   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:

#+BEGIN_EXAMPLE
   $ erts-<vsn>/bin/erl -name riaktest -setcookie riak
   
   Eshell V5.7.4  (abort with ^G)
   (riaktest@example.com)1>
#+END_EXAMPLE

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

#+BEGIN_EXAMPLE
   (riaktest@example.com)4> RiakNode = riak_util:str_to_node(riak).

   (riaktest@example.com)2> net_adm:ping(RiakNode).
   pong
   (riaktest@example.com)2>
#+END_EXAMPLE
   
   We are now ready to start the Riak client:

#+BEGIN_EXAMPLE
   (riaktest@example.com)2> {ok, C} = riak:client_connect(RiakNode).
   {ok,{riak_client,'riak@example.com',<<4,136,81,151>>}}
#+END_EXAMPLE

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

#+BEGIN_EXAMPLE
   (riaktest@example.com)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@example.com)3> C:put(O0, 1).
#+END_EXAMPLE
    
    Now, read the list back from the Riak server and extract the value

#+BEGIN_EXAMPLE
    (riaktest@example.com)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@example.com-riakdemo@example.com-266664",
                {1,63415509105}}],
              {dict,0,16,16,8,80,48,
                    {[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                    {{[],[],[],[],[],[],[],[],[],[],[],...}}},
              undefined}}

     (riaktest@example.com)5> %% extract the value
     (riaktest@example.com)5> V = riak_object:get_value(O1).
     ["bread"]
#+END_EXAMPLE

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

#+BEGIN_EXAMPLE
     (riaktest@example.com)6> %% add milk to the list
     (riaktest@example.com)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@example.com-riakdemo@example.com-266664",
            {1,63415509105}}],
          {dict,0,16,16,8,80,48,
                {[],[],[],[],[],[],[],[],[],[],[],[],[],[],[],...},
                {{[],[],[],[],[],[],[],[],[],[],[],[],[],...}}},
          ["milk","bread"]}

     (riaktest@example.com)7> %% store the new list
     (riaktest@example.com)7> C:put(O2, 1).
     ok
#+END_EXAMPLE

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

#+BEGIN_EXAMPLE
     (riaktest@example.com)8> C:list_keys(<<"groceries">>).
     {ok,[<<"mine">>]}
#+END_EXAMPLE


* 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@example.com)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. 

    To join a new Riak node to an existing cluster:

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

    (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

    
    
     
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.