-
Notifications
You must be signed in to change notification settings - Fork 1
/
README_RIAK
296 lines (206 loc) · 8.98 KB
/
README_RIAK
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
Welcome to Riak.
================
Date: 2010-06-09 10:06:44 CDT
Table of Contents
=================
1 Overview
2 Quick Start
2.1 Building Riak
2.2 Starting Riak
2.3 Connecting a client to Riak
2.4 Clients for Other Languages
3 Server Management
3.1 Configuration
3.2 Server Control
3.2.1 bin/riak
3.2.2 bin/riak-admin
1 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
2 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
2.1 Building Riak
==================
Assuming you have a working Erlang (R13B04 or later) installation,
building Riak should be as simple as:
$ cd $RIAK
$ make rel
2.2 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.
2.3 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">>]}
2.4 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
[http://bitbucket.org/basho/riak-javascript-client]
+ Python
[http://bitbucket.org/basho/riak-python-client]
+ Ruby
[http://bitbucket.org/basho/riak-ruby-client]
[http://github.com/seancribbs/ripple/]
+ Java
[http://bitbucket.org/basho/riak-java-client]
+ PHP
[http://bitbucket.org/basho/riak-php-client]
+ Erlang
[http://bitbucket.org/basho/riak-erlang-client]
(using protocol buffers instead of distributed Erlang)
3 Server Management
~~~~~~~~~~~~~~~~~~~~
3.1 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.
3.2 Server Control
===================
3.2.1 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
3.2.2 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>