]> git.saurik.com Git - redis.git/blame - doc/ProtocolSpecification.html
version set to 2.3.0
[redis.git] / doc / ProtocolSpecification.html
CommitLineData
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. -->
b9f7e9e6 19<b>ProtocolSpecification: Contents</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Networking layer">Networking layer</a><br>&nbsp;&nbsp;<a href="#Requests">Requests</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#The new unified request protocol">The new unified request protocol</a><br>&nbsp;&nbsp;<a href="#Replies">Replies</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Single line reply">Single line reply</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Error reply">Error reply</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Integer reply">Integer reply</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Bulk replies">Bulk replies</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Multi-Bulk replies">Multi-Bulk replies</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Nil elements in Multi-Bulk replies">Nil elements in Multi-Bulk replies</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Multiple commands and pipelining">Multiple commands and pipelining</a><br>&nbsp;&nbsp;<a href="#The old protocol for sending commands">The old protocol for sending commands</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Inline Commands">Inline Commands</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Bulk commands">Bulk commands</a>
8fb13ce8 20 </div>
21
22 <h1 class="wikiname">ProtocolSpecification</h1>
23
24 <div class="summary">
25
26 </div>
27
28 <div class="narrow">
b9f7e9e6 29 &iuml;&raquo;&iquest;= Protocol Specification =<br/><br/>The Redis protocol is a compromise between the following things:<br/><br/><ul><li> Simple to implement.</li><li> Fast to parse by a computer.</li><li> Easy enough to parse by a human.</li></ul>
30<h2><a name="Networking layer">Networking layer</a></h2>A client connects to a Redis server creating a TCP connection to the port 6379.
31Every Redis command or data transmitted by the client and the server is
32terminated by &quot;\r\n&quot; (CRLF).<h1><a name="Requests">Requests</a></h1>Redis accepts commands composed of different arguments.
33Once a command is received, it is processed and a reply is sent back to the client.<h2><a name="The new unified request protocol">The new unified request protocol</a></h2>The new unified protocol was introduced in Redis 1.2, but it became the standard way for talking with the Redis server in Redis 2.0.<br/><br/>In the unified protocol all the arguments sent to the Redis server are binary safe. This is the general form:<br/><br/><pre class="codeblock python" name="code">
34*&lt;number of arguments&gt; CR LF
35$&lt;number of bytes of argument 1&gt; CR LF
36&lt;argument data&gt; CR LF
37...
38$&lt;number of bytes of argument N&gt; CR LF
39&lt;argument data&gt; CR LF
40</pre>See the following example:<br/><br/><pre class="codeblock python python" name="code">
41*3
42$3
43SET
44$5
45mykey
46$7
47myvalue
48</pre>This is how the above command looks as a quoted string, so that it is possible to see the exact value of every byte in the query:<br/><br/><pre class="codeblock python python python" name="code">
49&quot;*3\r\n$3\r\nSET\r\n$5\r\nmykey\r\n$8\r\nmyvalue\r\n&quot;
50</pre>As you will see in a moment this format is also used in Redis replies.
51The format used for every argument &quot;$6\r\nmydata\r\n&quot; is called a Bulk Reply.
52While the actual unified request protocol is what Redis uses to return list of items, and is called a Multi Bulk Reply. It is just the sum of N different
53Bulk Replies prefixed by a <code name="code" class="python">*&lt;argc&gt;\r\n</code> string where <code name="code" class="python">&lt;argc&gt;</code> is the number of arguments (Bulk Replies) that will follow.<h1><a name="Replies">Replies</a></h1>Redis will reply to commands with different kinds of replies. It is possible to check the kind of reply from the first byte sent by the server:<br/><br/><ul><li> With a single line reply the first byte of the reply will be &quot;+&quot;</li><li> With an error message the first byte of the reply will be &quot;-&quot;</li><li> With an integer number the first byte of the reply will be &quot;:&quot;</li><li> With bulk reply the first byte of the reply will be &quot;$&quot;</li><li> With multi-bulk reply the first byte of the reply will be &quot;<code name="code" class="python">*</code>&quot;</li></ul>
54<h2><a name="Single line reply">Single line reply</a></h2>A single line reply is in the form of a single line string
55starting with &quot;+&quot; terminated by &quot;\r\n&quot;. For example:<br/><br/><pre class="codeblock python python python python" name="code">
56+OK
57</pre>The client library should return everything after the &quot;+&quot;, that is, the string &quot;OK&quot; in the example.<br/><br/>The following commands reply with a single line reply:
58PING, SET, SELECT, SAVE, BGSAVE, SHUTDOWN, RENAME, LPUSH, RPUSH, LSET, LTRIM<h2><a name="Error reply">Error reply</a></h2>Errors are sent exactly like Single Line Replies. The only difference is that the first byte is &quot;-&quot; instead of &quot;+&quot;.<br/><br/>Error replies are only sent when something strange happened, for instance if you try to perform an operation against the wrong data type, or if the command does not exist and so forth. So an exception should be raised by the library client when an Error Reply is received.<h2><a name="Integer reply">Integer reply</a></h2>This type of reply is just a CRLF terminated string representing an integer, prefixed by a &quot;:&quot; byte. For example &quot;:0\r\n&quot;, or &quot;:1000\r\n&quot; are integer replies.<br/><br/>With commands like INCR or LASTSAVE using the integer reply to actually return a value there is no special meaning for the returned integer. It is just an incremental number for INCR, a UNIX time for LASTSAVE and so on.<br/><br/>Some commands like EXISTS will return 1 for true and 0 for false.<br/><br/>Other commands like SADD, SREM and SETNX will return 1 if the operation was actually done, 0 otherwise.<br/><br/>The following commands will reply with an integer reply: SETNX, DEL, EXISTS, INCR, INCRBY, DECR, DECRBY, DBSIZE, LASTSAVE, RENAMENX, MOVE, LLEN, SADD, SREM, SISMEMBER, SCARD<h2><a name="Bulk replies">Bulk replies</a></h2>Bulk replies are used by the server in order to return a single binary safe string.<br/><br/><pre class="codeblock python python python python python" name="code">
8fb13ce8 59C: GET mykey
60S: $6
61S: foobar
b9f7e9e6 62</pre>The server sends as the first line a &quot;$&quot; byte followed by the number of bytes
63of the actual reply, followed by CRLF, then the actual data bytes are sent,
64followed by additional two bytes for the final CRLF.
65The exact sequence sent by the server is:<br/><br/><pre class="codeblock python python python python python python" name="code">
66&quot;$6\r\nfoobar\r\n&quot;
67</pre>If the requested value does not exist the bulk reply will use the special
68value -1 as data length, example:<br/><br/><pre class="codeblock python python python python python python python" name="code">
8fb13ce8 69C: GET nonexistingkey
70S: $-1
71</pre>The client library API should not return an empty string, but a nil object, when the requested object does not exist.
72For example a Ruby library should return 'nil' while a C library should return
b9f7e9e6 73NULL (or set a special flag in the reply object), and so forth.<h2><a name="Multi-Bulk replies">Multi-Bulk replies</a></h2>Commands like LRANGE need to return multiple values (every element
8fb13ce8 74of the list is a value, and LRANGE needs to return more than a single element). This is accomplished using multiple bulk writes,
75prefixed by an initial line indicating how many bulk writes will follow.
b9f7e9e6 76The first byte of a multi bulk reply is always <code name="code" class="python">*</code>. Example:<br/><br/><pre class="codeblock python python python python python python python python" name="code">
8fb13ce8 77C: LRANGE mylist 0 3
78S: *4
79S: $3
80S: foo
81S: $3
82S: bar
83S: $5
84S: Hello
85S: $5
86S: World
b9f7e9e6 87</pre>As you can see the multi bulk reply is exactly the same format used in order
88to send commands to the Redis server unsing the unified protocol.<br/><br/>The first line the server sent is &quot;<b>4\r\n&quot; in order to specify that four bulk
89replies will follow. Then every bulk write is transmitted.<br/><br/>If the specified key does not exist, instead of the number of elements in the
90list the special value -1 is sent as count. Example:<br/><br/><pre class="codeblock python python python python python python python python python" name="code">
8fb13ce8 91C: LRANGE nokey 0 1
92S: *-1
93</pre>A client library API SHOULD return a nil object and not an empty list when this
b9f7e9e6 94happens. This makes possible to distinguish between empty list and other error conditions (for instance a timeout condition in the BLPOP command).<h2><a name="Nil elements in Multi-Bulk replies">Nil elements in Multi-Bulk replies</a></h2>Single elements of a multi bulk reply may have -1 length, in order to signal that this elements are missing and not empty strings. This can happen with the SORT command when used with the GET <i>pattern</i> option when the specified key is missing. Example of a multi bulk reply containing an empty element:<br/><br/><pre class="codeblock python python python python python python python python python python" name="code">
8fb13ce8 95S: *3
96S: $3
97S: foo
98S: $-1
99S: $3
100S: bar
b9f7e9e6 101</pre>The second element is nul. The client library should return something like this:<br/><br/><pre class="codeblock python python python python python python python python python python python" name="code">
8fb13ce8 102[&quot;foo&quot;,nil,&quot;bar&quot;]
b9f7e9e6 103</pre><h2><a name="Multiple commands and pipelining">Multiple commands and pipelining</a></h2>A client can use the same connection in order to issue multiple commands.
8fb13ce8 104Pipelining is supported so multiple commands can be sent with a single
105write operation by the client, it is not needed to read the server reply
106in order to issue the next command. All the replies can be read at the end.<br/><br/>Usually Redis server and client will have a very fast link so this is not
107very important to support this feature in a client implementation, still
108if an application needs to issue a very large number of commands in short
b9f7e9e6 109time to use pipelining can be much faster.<h1><a name="The old protocol for sending commands">The old protocol for sending commands</a></h1>Before of the Unified Request Protocol Redis used a different protocol to send
110commands, that is still supported since it is simpler to type by hand via telnet. In this protocol there are two kind of commands:<br/><br/><blockquote>* Inline commands: simple commands where argumnets are just space separated strings. No binary safeness is possible.* Bulk commands: bulk commands are exactly like inline commands, but the last argument is handled in a special way in order to allow for a binary-safe last argument.</blockquote>
111<h2><a name="Inline Commands">Inline Commands</a></h2>The simplest way to send Redis a command is via </b>Inline Commands.
112The following is an example of a server/client chat using an inline command (the server chat starts with S:, the client chat with C:)<br/><br/><pre class="codeblock python python python python python python python python python python python python" name="code">
113C: PING
114S: +PONG
115</pre>The following is another example of an INLINE command returning an integer:<br/><br/><pre class="codeblock python python python python python python python python python python python python python" name="code">
116C: EXISTS somekey
117S: :0
118</pre>Since 'somekey' does not exist the server returned ':0'.<br/><br/>Note that the EXISTS command takes one argument. Arguments are separated
119by spaces.<h2><a name="Bulk commands">Bulk commands</a></h2>Some commands when sent as inline commands require a special form in order
120to support a binary safe last argument. This commands will use the last argument
121for a &quot;byte count&quot;, then the bulk data is sent (that can be binary safe since
122the server knows how many bytes to read).<br/><br/>See for instance the following example:<br/><br/><pre class="codeblock python python python python python python python python python python python python python python" name="code">
123C: SET mykey 6
124C: foobar
125S: +OK
126</pre>The last argument of the commnad is '6'. This specify the number of DATA
127bytes that will follow, that is, the string &quot;foobar&quot;. Note that even this bytes are terminated by two additional bytes of CRLF.<br/><br/>All the bulk commands are in this exact form: instead of the last argument
128the number of bytes that will follow is specified, followed by the bytes
129composing the argument itself, and CRLF. In order to be more clear for the programmer this is the string sent by the client in the above sample:<br/><br/><blockquote>&quot;SET mykey 6\r\nfoobar\r\n&quot;</blockquote>
130Redis has an internal list of what command is inline and what command is bulk, so you have to send this commands accordingly. It is strongly suggested to use the new Unified Request Protocol instead.
8fb13ce8 131 </div>
132
133 </div>
134 </div>
135 </body>
136</html>
137