[redis.git] / doc / README.html


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
    <head>
        <link type="text/css" rel="stylesheet" href="style.css" />
    </head>
    <body>
        <div id="page">
        
            <div id='header'>
            <a href="index.html">
            <img style="border:none" alt="Redis Documentation" src="redis.png">
            </a>
            </div>
        
            <div id="pagecontent">
                <div class="index">
<!-- This is a (PRE) block.  Make sure it's left aligned or your toc title will be off. -->
<b>README: Contents</b><br>&nbsp;&nbsp;<a href="#All data in memory, but saved on disk">All data in memory, but saved on disk</a><br>&nbsp;&nbsp;<a href="#Master-Slave replication made trivial">Master-Slave replication made trivial</a><br>&nbsp;&nbsp;<a href="#It's persistent but supports expires">It's persistent but supports expires</a><br>&nbsp;&nbsp;<a href="#Beyond key-value databases">Beyond key-value databases</a><br>&nbsp;&nbsp;<a href="#Multiple databases support">Multiple databases support</a><br>&nbsp;&nbsp;<a href="#Know more about Redis!">Know more about Redis!</a><br>&nbsp;&nbsp;<a href="#Redis Tutorial">Redis Tutorial</a><br>&nbsp;&nbsp;<a href="#License">License</a><br>&nbsp;&nbsp;<a href="#Credits">Credits</a>
                </div>
                
                <h1 class="wikiname">README</h1>

                <div class="summary">
                    
                </div>

                <div class="narrow">
                    &iuml;&raquo;&iquest;= Introduction =<br/><br/>Redis is an extremely fast and powerful key-value store database and server implemented in ANSI C.  Redis offers many different ways to do one straightforward thing: store a value (&quot;antirez&quot;) to a key (&quot;redis&quot;).  While the format of keys must always be simple strings, the power is with the values, which support the following data types:<br/><br/><ul><li> <a href="Strings.html">Strings</a></li><li> <a href="Lists.html">Lists</a></li><li> <a href="Sets.html">Sets</a></li><li> <a href="SortedSets.html">Sorted Sets (zsets)</a></li><li> <a href="Hashes.html">Hashes</a></li></ul>
Each value type has an associated list of commands which can operate on them, and the <a href="CommandReference.html">The Redis Command Reference</a> contains an up to date list of these commands, organized primarily by data type.  The Redis source also includes a <a href="RedisCLI.html">Redis command line interface</a> which allows you to interact directly with the server, and is the means by which this introduction will provide examples.  Once you walk through the <a href="QuickStart.html">Redis Quick Start Guide</a> to get your instance of Redis running, you can follow along.  <br/><br/>One of the most powerful aspects of Redis is the wide range of commands which are optimized to work with specific data value types and executed as atomic server-side operations.  The <a href="Lists.html">List</a> type is a great example - Redis implements O(1) operations such as <a href="RpushCommand.html">LPUSH</a> or <a href="RpushCommand.html">RPUSH</a>, which have accompanying <a href="LpopCommand.html">LPOP</a> and <a href="LpopCommand.html">RPOP</a> methods:<br/><br/><pre class="codeblock python" name="code">
redis&gt; lpush programming_languages C
OK
redis&gt; lpush programming_languages Ruby
OK
redis&gt; rpush programming_languages Python
OK
redis&gt; rpop programming_languages
Python
redis&gt; lpop programming_languages
Ruby
</pre>More complex operations are available for each data type as well.  Continuing with lists, you can get a range of elements with <a href="LrangeCommand.html">LRANGE</a> (O(start+n)) or trim the list with <a href="LtrimCommand.html">LTRIM</a> (O(n)):<br/><br/><pre class="codeblock python python" name="code">
redis&gt; lpush cities NYC
OK
redis&gt; lpush cities SF
OK
redis&gt; lpush cities Tokyo
OK
redis&gt; lpush cities London
OK
redis&gt; lpush cities Paris
OK
redis&gt; lrange cities 0 2
1. Paris
2. London
3. Tokyo
redis&gt; ltrim cities 0 1
OK
redis&gt; lpop cities
Paris
redis&gt; lpop cities
London
redis&gt; lpop cities
(nil)
</pre>You can also add and remove elements from a set, and perform intersections, unions, and differences. <br/><br/>Redis can also be looked at as a data structures server. A Redis user is virtually provided with an interface to  <a href="http://en.wikipedia.org/wiki/Abstract_data_type" target="_blank">Abstract Data Types</a>, saving them from the responsibility of implementing concrete data structures and algorithms -- indeed both algorithms and data structures in Redis are properly chosen in order to obtain the best performance.<h1><a name="All data in memory, but saved on disk">All data in memory, but saved on disk</a></h1>Redis loads and mantains the whole dataset into memory, but the dataset is persistent, since at the same time it is saved on disk, so that when the server is restarted data can be loaded back in memory.<br/><br/>There are two kinds of persistence supported: the first one is called snapshotting. In this mode Redis periodically writes to disk asynchronously. The dataset is loaded from the dump every time the server is (re)started.<br/><br/>Redis can be configured to save the dataset when a certain number of changes is reached and after a given number of seconds elapses. For example, you can configure Redis to save after 1000 changes and at most 60 seconds since the last save. You can specify any combination for these numbers.<br/><br/>Because data is written asynchronously, when a system crash occurs, the last few queries can get lost (that is acceptable in many applications but not in all).  In order to make this a non issue Redis supports another, safer persistence mode, called <a href="AppendOnlyFileHowto.html">Append Only File</a>, where every command received altering the dataset (so not a read-only command, but a write command) is written on an append only file ASAP. This commands are <i>replayed</i> when the server is restarted in order to rebuild the dataset in memory.<br/><br/>Redis Append Only File supports a very handy feature: the server is able to safely rebuild the append only file in background in a non-blocking fashion when it gets too long. You can find <a href="AppendOnlyFileHowto.html">more details in the Append Only File HOWTO</a>.<h1><a name="Master-Slave replication made trivial">Master-Slave replication made trivial</a></h1>Whatever will be the persistence mode you'll use Redis supports master-slave replications if you want to stay really safe or if you need to scale to huge amounts of reads.<br/><br/><b>Redis Replication is trivial to setup</b>. So trivial that all you need to do in order to configure a Redis server to be a slave of another one, with automatic synchronization if the link will go down and so forth, is the following config line: <code name="code" class="python">slaveof 192.168.1.100 6379</code>. <a href="ReplicationHowto.html">We provide a Replication Howto</a> if you want to know more about this feature.<h1><a name="It's persistent but supports expires">It's persistent but supports expires</a></h1>Redis can be used as a <b>memcached on steroids</b> because is as fast as memcached but with a number of features more. Like memcached, Redis also supports setting timeouts to keys so that this key will be automatically removed when a given amount of time passes.<h1><a name="Beyond key-value databases">Beyond key-value databases</a></h1>All these features allow to use Redis as the sole DB for your scalable application without the need of any relational database. <a href="TwitterAlikeExample.html">We wrote a simple Twitter clone in PHP + Redis</a> to show a real world example, the link points to an article explaining the design and internals in very simple words.<h1><a name="Multiple databases support">Multiple databases support</a></h1>Redis supports multiple databases with commands to atomically move keys from one database to the other. By default DB 0 is selected for every new connection, but using the SELECT command it is possible to select a different database. The MOVE operation can move an item from one DB to another atomically. This can be used as a base for locking free algorithms together with the 'RANDOMKEY' commands.<h1><a name="Know more about Redis!">Know more about Redis!</a></h1>To really get a feeling about what Redis is and how it works please try reading <a href="IntroductionToRedisDataTypes.html">A fifteen minutes introduction to Redis data types</a>.<br/><br/>To know a bit more about how Redis works <i>internally</i> continue reading.<h1><a name="Redis Tutorial">Redis Tutorial</a></h1>(note, you can skip this section if you are only interested in &quot;formal&quot; doc.)<br/><br/>Later in this document you can find detailed information about Redis commands,
the protocol specification, and so on. This kind of documentation is useful
but... if you are new to Redis it is also BORING! The Redis protocol is designed
so that is both pretty efficient to be parsed by computers, but simple enough
to be used by humans just poking around with the 'telnet' command, so this
section will show to the reader how to play a bit with Redis to get an initial
feeling about it, and how it works.<br/><br/>To start just compile redis with 'make' and start it with './redis-server'.
The server will start and log stuff on the standard output, if you want
it to log more edit redis.conf, set the loglevel to debug, and restart it.<br/><br/>You can specify a configuration file as unique parameter:<br/><br/><blockquote>./redis-server /etc/redis.conf</blockquote>
This is NOT required. The server will start even without a configuration file
using a default built-in configuration.<br/><br/>Now let's try to set a key to a given value:<br/><br/><pre class="codeblock python python python" name="code">
$ telnet localhost 6379
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
SET foo 3  
bar
+OK
</pre>The first line we sent to the server is &quot;set foo 3&quot;. This means &quot;set the key
foo with the following three bytes I'll send you&quot;. The following line is
the &quot;bar&quot; string, that is, the three bytes. So the effect is to set the
key &quot;foo&quot; to the value &quot;bar&quot;. Very simple!<br/><br/>(note that you can send commands in lowercase and it will work anyway,
commands are not case sensitive)<br/><br/>Note that after the first and the second line we sent to the server there
is a newline at the end. The server expects commands terminated by &quot;\r\n&quot;
and sequence of bytes terminated by &quot;\r\n&quot;. This is a minimal overhead from
the point of view of both the server and client but allows us to play with
Redis with the telnet command easily.<br/><br/>The last line of the chat between server and client is &quot;+OK&quot;. This means
our key was added without problems. Actually SET can never fail but
the &quot;+OK&quot; sent lets us know that the server received everything and
the command was actually executed.<br/><br/>Let's try to get the key content now:<br/><br/><pre class="codeblock python python python python" name="code">
GET foo
$3
bar
</pre>Ok that's very similar to 'set', just the other way around. We sent &quot;get foo&quot;,
the server replied with a first line that is just the $ character follwed by
the number of bytes the value stored at key contained, followed by the actual
bytes. Again &quot;\r\n&quot; are appended both to the bytes count and the actual data. In Redis slang this is called a bulk reply.<br/><br/>What about requesting a non existing key?<br/><br/><pre class="codeblock python python python python python" name="code">
GET blabla
$-1
</pre>When the key does not exist instead of the length, just the &quot;$-1&quot; string is sent. Since a -1 length of a bulk reply has no meaning it is used in order to specifiy a 'nil' value and distinguish it from a zero length value. Another way to check if a given key exists or not is indeed the EXISTS command:<br/><br/><pre class="codeblock python python python python python python" name="code">
EXISTS nokey
:0
EXISTS foo
:1
</pre>As you can see the server replied ':0' the first time since 'nokey' does not
exist, and ':1' for 'foo', a key that actually exists. Replies starting with the colon character are integer reply.<br/><br/>Ok... now you know the basics, read the <a href="CommandReference.html">REDIS COMMAND REFERENCE</a> section to
learn all the commands supported by Redis and the <a href="ProtocolSpecification.html">PROTOCOL SPECIFICATION</a>
section for more details about the protocol used if you plan to implement one
for a language missing a decent client implementation.<h1><a name="License">License</a></h1>Redis is released under the BSD license. See the COPYING file for more information.<h1><a name="Credits">Credits</a></h1>Redis is written and maintained by Salvatore Sanfilippo, Aka 'antirez'.
                </div>
        
            </div>
        </div>
    </body>
</html>
Commit	Line	Data
8fb13ce8	1
	2	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
	3	<html>
	4	<head>
	5	<link type="text/css" rel="stylesheet" href="style.css" />
	6	</head>
	7	<body>
	8	<div id="page">
	9
	10	<div id='header'>
	11	<a href="index.html">
	12	<img style="border:none" alt="Redis Documentation" src="redis.png">
	13	</a>
	14	</div>
	15
	16	<div id="pagecontent">
	17	<div class="index">
	18	<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
	19	<b>README: Contents</b><br>  <a href="#All data in memory, but saved on disk">All data in memory, but saved on disk</a><br>  <a href="#Master-Slave replication made trivial">Master-Slave replication made trivial</a><br>  <a href="#It's persistent but supports expires">It's persistent but supports expires</a><br>  <a href="#Beyond key-value databases">Beyond key-value databases</a><br>  <a href="#Multiple databases support">Multiple databases support</a><br>  <a href="#Know more about Redis!">Know more about Redis!</a><br>  <a href="#Redis Tutorial">Redis Tutorial</a><br>  <a href="#License">License</a><br>  <a href="#Credits">Credits</a>
	20	</div>
	21
	22	<h1 class="wikiname">README</h1>
	23
	24	<div class="summary">
	25
	26	</div>
	27
	28	<div class="narrow">
abe18d0e	29	ï»¿= Introduction =<br/><br/>Redis is an extremely fast and powerful key-value store database and server implemented in ANSI C. Redis offers many different ways to do one straightforward thing: store a value ("antirez") to a key ("redis"). While the format of keys must always be simple strings, the power is with the values, which support the following data types:<br/><br/><ul><li> <a href="Strings.html">Strings</a></li><li> <a href="Lists.html">Lists</a></li><li> <a href="Sets.html">Sets</a></li><li> <a href="SortedSets.html">Sorted Sets (zsets)</a></li><li> <a href="Hashes.html">Hashes</a></li></ul>
	30	Each value type has an associated list of commands which can operate on them, and the <a href="CommandReference.html">The Redis Command Reference</a> contains an up to date list of these commands, organized primarily by data type. The Redis source also includes a <a href="RedisCLI.html">Redis command line interface</a> which allows you to interact directly with the server, and is the means by which this introduction will provide examples. Once you walk through the <a href="QuickStart.html">Redis Quick Start Guide</a> to get your instance of Redis running, you can follow along. <br/><br/>One of the most powerful aspects of Redis is the wide range of commands which are optimized to work with specific data value types and executed as atomic server-side operations. The <a href="Lists.html">List</a> type is a great example - Redis implements O(1) operations such as <a href="RpushCommand.html">LPUSH</a> or <a href="RpushCommand.html">RPUSH</a>, which have accompanying <a href="LpopCommand.html">LPOP</a> and <a href="LpopCommand.html">RPOP</a> methods:<br/><br/><pre class="codeblock python" name="code">
	31	redis> lpush programming_languages C
	32	OK
	33	redis> lpush programming_languages Ruby
	34	OK
	35	redis> rpush programming_languages Python
	36	OK
	37	redis> rpop programming_languages
	38	Python
	39	redis> lpop programming_languages
	40	Ruby
	41	</pre>More complex operations are available for each data type as well. Continuing with lists, you can get a range of elements with <a href="LrangeCommand.html">LRANGE</a> (O(start+n)) or trim the list with <a href="LtrimCommand.html">LTRIM</a> (O(n)):<br/><br/><pre class="codeblock python python" name="code">
	42	redis> lpush cities NYC
	43	OK
	44	redis> lpush cities SF
	45	OK
	46	redis> lpush cities Tokyo
	47	OK
	48	redis> lpush cities London
	49	OK
	50	redis> lpush cities Paris
	51	OK
	52	redis> lrange cities 0 2
	53	1. Paris
	54	2. London
	55	3. Tokyo
	56	redis> ltrim cities 0 1
	57	OK
	58	redis> lpop cities
	59	Paris
	60	redis> lpop cities
	61	London
	62	redis> lpop cities
	63	(nil)
	64	</pre>You can also add and remove elements from a set, and perform intersections, unions, and differences. <br/><br/>Redis can also be looked at as a data structures server. A Redis user is virtually provided with an interface to <a href="http://en.wikipedia.org/wiki/Abstract_data_type" target="_blank">Abstract Data Types</a>, saving them from the responsibility of implementing concrete data structures and algorithms -- indeed both algorithms and data structures in Redis are properly chosen in order to obtain the best performance.<h1><a name="All data in memory, but saved on disk">All data in memory, but saved on disk</a></h1>Redis loads and mantains the whole dataset into memory, but the dataset is persistent, since at the same time it is saved on disk, so that when the server is restarted data can be loaded back in memory.<br/><br/>There are two kinds of persistence supported: the first one is called snapshotting. In this mode Redis periodically writes to disk asynchronously. The dataset is loaded from the dump every time the server is (re)started.<br/><br/>Redis can be configured to save the dataset when a certain number of changes is reached and after a given number of seconds elapses. For example, you can configure Redis to save after 1000 changes and at most 60 seconds since the last save. You can specify any combination for these numbers.<br/><br/>Because data is written asynchronously, when a system crash occurs, the last few queries can get lost (that is acceptable in many applications but not in all). In order to make this a non issue Redis supports another, safer persistence mode, called <a href="AppendOnlyFileHowto.html">Append Only File</a>, where every command received altering the dataset (so not a read-only command, but a write command) is written on an append only file ASAP. This commands are <i>replayed</i> when the server is restarted in order to rebuild the dataset in memory.<br/><br/>Redis Append Only File supports a very handy feature: the server is able to safely rebuild the append only file in background in a non-blocking fashion when it gets too long. You can find <a href="AppendOnlyFileHowto.html">more details in the Append Only File HOWTO</a>.<h1><a name="Master-Slave replication made trivial">Master-Slave replication made trivial</a></h1>Whatever will be the persistence mode you'll use Redis supports master-slave replications if you want to stay really safe or if you need to scale to huge amounts of reads.<br/><br/><b>Redis Replication is trivial to setup</b>. So trivial that all you need to do in order to configure a Redis server to be a slave of another one, with automatic synchronization if the link will go down and so forth, is the following config line: <code name="code" class="python">slaveof 192.168.1.100 6379</code>. <a href="ReplicationHowto.html">We provide a Replication Howto</a> if you want to know more about this feature.<h1><a name="It's persistent but supports expires">It's persistent but supports expires</a></h1>Redis can be used as a <b>memcached on steroids</b> because is as fast as memcached but with a number of features more. Like memcached, Redis also supports setting timeouts to keys so that this key will be automatically removed when a given amount of time passes.<h1><a name="Beyond key-value databases">Beyond key-value databases</a></h1>All these features allow to use Redis as the sole DB for your scalable application without the need of any relational database. <a href="TwitterAlikeExample.html">We wrote a simple Twitter clone in PHP + Redis</a> to show a real world example, the link points to an article explaining the design and internals in very simple words.<h1><a name="Multiple databases support">Multiple databases support</a></h1>Redis supports multiple databases with commands to atomically move keys from one database to the other. By default DB 0 is selected for every new connection, but using the SELECT command it is possible to select a different database. The MOVE operation can move an item from one DB to another atomically. This can be used as a base for locking free algorithms together with the 'RANDOMKEY' commands.<h1><a name="Know more about Redis!">Know more about Redis!</a></h1>To really get a feeling about what Redis is and how it works please try reading <a href="IntroductionToRedisDataTypes.html">A fifteen minutes introduction to Redis data types</a>.<br/><br/>To know a bit more about how Redis works <i>internally</i> continue reading.<h1><a name="Redis Tutorial">Redis Tutorial</a></h1>(note, you can skip this section if you are only interested in "formal" doc.)<br/><br/>Later in this document you can find detailed information about Redis commands,
8fb13ce8	65	the protocol specification, and so on. This kind of documentation is useful
	66	but... if you are new to Redis it is also BORING! The Redis protocol is designed
	67	so that is both pretty efficient to be parsed by computers, but simple enough
	68	to be used by humans just poking around with the 'telnet' command, so this
	69	section will show to the reader how to play a bit with Redis to get an initial
	70	feeling about it, and how it works.<br/><br/>To start just compile redis with 'make' and start it with './redis-server'.
	71	The server will start and log stuff on the standard output, if you want
	72	it to log more edit redis.conf, set the loglevel to debug, and restart it.<br/><br/>You can specify a configuration file as unique parameter:<br/><br/><blockquote>./redis-server /etc/redis.conf</blockquote>
	73	This is NOT required. The server will start even without a configuration file
abe18d0e	74	using a default built-in configuration.<br/><br/>Now let's try to set a key to a given value:<br/><br/><pre class="codeblock python python python" name="code">
8fb13ce8	75	$ telnet localhost 6379
	76	Trying 127.0.0.1...
	77	Connected to localhost.
	78	Escape character is '^]'.
	79	SET foo 3
	80	bar
	81	+OK
	82	</pre>The first line we sent to the server is "set foo 3". This means "set the key
	83	foo with the following three bytes I'll send you". The following line is
	84	the "bar" string, that is, the three bytes. So the effect is to set the
	85	key "foo" to the value "bar". Very simple!<br/><br/>(note that you can send commands in lowercase and it will work anyway,
	86	commands are not case sensitive)<br/><br/>Note that after the first and the second line we sent to the server there
	87	is a newline at the end. The server expects commands terminated by "\r\n"
	88	and sequence of bytes terminated by "\r\n". This is a minimal overhead from
	89	the point of view of both the server and client but allows us to play with
	90	Redis with the telnet command easily.<br/><br/>The last line of the chat between server and client is "+OK". This means
	91	our key was added without problems. Actually SET can never fail but
	92	the "+OK" sent lets us know that the server received everything and
abe18d0e	93	the command was actually executed.<br/><br/>Let's try to get the key content now:<br/><br/><pre class="codeblock python python python python" name="code">
8fb13ce8	94	GET foo
	95	$3
	96	bar
	97	</pre>Ok that's very similar to 'set', just the other way around. We sent "get foo",
	98	the server replied with a first line that is just the $ character follwed by
	99	the number of bytes the value stored at key contained, followed by the actual
abe18d0e	100	bytes. Again "\r\n" are appended both to the bytes count and the actual data. In Redis slang this is called a bulk reply.<br/><br/>What about requesting a non existing key?<br/><br/><pre class="codeblock python python python python python" name="code">
8fb13ce8	101	GET blabla
8fb13ce8	102	$-1
abe18d0e	103	</pre>When the key does not exist instead of the length, just the "$-1" string is sent. Since a -1 length of a bulk reply has no meaning it is used in order to specifiy a 'nil' value and distinguish it from a zero length value. Another way to check if a given key exists or not is indeed the EXISTS command:<br/><br/><pre class="codeblock python python python python python python" name="code">
8fb13ce8	104	EXISTS nokey
	105	:0
	106	EXISTS foo
	107	:1
	108	</pre>As you can see the server replied ':0' the first time since 'nokey' does not
	109	exist, and ':1' for 'foo', a key that actually exists. Replies starting with the colon character are integer reply.<br/><br/>Ok... now you know the basics, read the <a href="CommandReference.html">REDIS COMMAND REFERENCE</a> section to
	110	learn all the commands supported by Redis and the <a href="ProtocolSpecification.html">PROTOCOL SPECIFICATION</a>
	111	section for more details about the protocol used if you plan to implement one
	112	for a language missing a decent client implementation.<h1><a name="License">License</a></h1>Redis is released under the BSD license. See the COPYING file for more information.<h1><a name="Credits">Credits</a></h1>Redis is written and maintained by Salvatore Sanfilippo, Aka 'antirez'.
	113	</div>
	114
	115	</div>
	116	</div>
	117	</body>
	118	</html>
	119