| 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>ProtocolSpecification: Contents</b><br> <a href="#Networking layer">Networking layer</a><br> <a href="#Simple INLINE commands">Simple INLINE commands</a><br> <a href="#Bulk commands">Bulk commands</a><br> <a href="#Bulk replies">Bulk replies</a><br> <a href="#Multi-Bulk replies">Multi-Bulk replies</a><br> <a href="#Nil elements in Multi-Bulk replies">Nil elements in Multi-Bulk replies</a><br> <a href="#Single line reply">Single line reply</a><br> <a href="#Integer reply">Integer reply</a><br> <a href="#Multi bulk commands">Multi bulk commands</a><br> <a href="#Multiple commands and pipelining">Multiple commands and pipelining</a> |
| 20 | </div> |
| 21 | |
| 22 | <h1 class="wikiname">ProtocolSpecification</h1> |
| 23 | |
| 24 | <div class="summary"> |
| 25 | |
| 26 | </div> |
| 27 | |
| 28 | <div class="narrow"> |
| 29 | = Protocol Specification =<br/><br/>The Redis protocol is a compromise between being easy to parse by a computer |
| 30 | and being easy to parse by an human. Before reading this section you are |
| 31 | strongly encouraged to read the "REDIS TUTORIAL" section of this README in order |
| 32 | to get a first feeling of the protocol playing with it by TELNET.<h2><a name="Networking layer">Networking layer</a></h2>A client connects to a Redis server creating a TCP connection to the port 6379. |
| 33 | Every redis command or data transmitted by the client and the server is |
| 34 | terminated by "\r\n" (CRLF).<h2><a name="Simple INLINE commands">Simple INLINE commands</a></h2>The simplest commands are the inline commands. This is an example of a |
| 35 | server/client chat (the server chat starts with S:, the client chat with C:)<br/><br/><pre class="codeblock python" name="code"> |
| 36 | C: PING |
| 37 | S: +PONG |
| 38 | </pre>An inline command is a CRLF-terminated string sent to the client. The server can reply to commands in different ways: |
| 39 | <ul><li> With an error message (the first byte of the reply will be "-")</li><li> With a single line reply (the first byte of the reply will be "+)</li><li> With bulk data (the first byte of the reply will be "$")</li><li> With multi-bulk data, a list of values (the first byte of the reply will be "<code name="code" class="python">*</code>")</li><li> With an integer number (the first byte of the reply will be ":")</li></ul> |
| 40 | The following is another example of an INLINE command returning an integer:<br/><br/><pre class="codeblock python python" name="code"> |
| 41 | C: EXISTS somekey |
| 42 | S: :0 |
| 43 | </pre>Since 'somekey' does not exist the server returned ':0'.<br/><br/>Note that the EXISTS command takes one argument. Arguments are separated |
| 44 | simply by spaces.<h2><a name="Bulk commands">Bulk commands</a></h2>A bulk command is exactly like an inline command, but the last argument |
| 45 | of the command must be a stream of bytes in order to send data to the server. |
| 46 | the "SET" command is a bulk command, see the following example:<br/><br/><pre class="codeblock python python python" name="code"> |
| 47 | C: SET mykey 6 |
| 48 | C: foobar |
| 49 | S: +OK |
| 50 | </pre>The last argument of the commnad is '6'. This specify the number of DATA |
| 51 | bytes that will follow (note that even this bytes are terminated by two |
| 52 | additional bytes of CRLF).<br/><br/>All the bulk commands are in this exact form: instead of the last argument |
| 53 | the number of bytes that will follow is specified, followed by the bytes, |
| 54 | and CRLF. In order to be more clear for the programmer this is the string |
| 55 | sent by the client in the above sample:<br/><br/><blockquote>"SET mykey 6\r\nfoobar\r\n"</blockquote> |
| 56 | <h2><a name="Bulk replies">Bulk replies</a></h2>The server may reply to an inline or bulk command with a bulk reply. See |
| 57 | the following example:<br/><br/><pre class="codeblock python python python python" name="code"> |
| 58 | C: GET mykey |
| 59 | S: $6 |
| 60 | S: foobar |
| 61 | </pre>A bulk reply is very similar to the last argument of a bulk command. The |
| 62 | server sends as the first line a "$" byte followed by the number of bytes |
| 63 | of the actual reply followed by CRLF, then the bytes are sent followed by |
| 64 | additional two bytes for the final CRLF. The exact sequence sent by the |
| 65 | server is:<br/><br/><blockquote>"$6\r\nfoobar\r\n"</blockquote> |
| 66 | If the requested value does not exist the bulk reply will use the special |
| 67 | value -1 as data length, example:<br/><br/><pre class="codeblock python python python python python" name="code"> |
| 68 | C: GET nonexistingkey |
| 69 | S: $-1 |
| 70 | </pre>The client library API should not return an empty string, but a nil object, when the requested object does not exist. |
| 71 | For example a Ruby library should return 'nil' while a C library should return |
| 72 | NULL, and so forth.<h2><a name="Multi-Bulk replies">Multi-Bulk replies</a></h2>Commands similar to LRANGE needs to return multiple values (every element |
| 73 | of the list is a value, and LRANGE needs to return more than a single element). This is accomplished using multiple bulk writes, |
| 74 | prefixed by an initial line indicating how many bulk writes will follow. |
| 75 | The 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" name="code"> |
| 76 | C: LRANGE mylist 0 3 |
| 77 | S: *4 |
| 78 | S: $3 |
| 79 | S: foo |
| 80 | S: $3 |
| 81 | S: bar |
| 82 | S: $5 |
| 83 | S: Hello |
| 84 | S: $5 |
| 85 | S: World |
| 86 | </pre>The first line the server sent is "<b>4\r\n" in order to specify that four bulk |
| 87 | write 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 |
| 88 | list, the special value -1 is sent as count. Example:<br/><br/><pre class="codeblock python python python python python python python" name="code"> |
| 89 | C: LRANGE nokey 0 1 |
| 90 | S: *-1 |
| 91 | </pre>A client library API SHOULD return a nil object and not an empty list when this |
| 92 | happens. This makes possible to distinguish between empty list and non existing ones.<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" name="code"> |
| 93 | S: *3 |
| 94 | S: $3 |
| 95 | S: foo |
| 96 | S: $-1 |
| 97 | S: $3 |
| 98 | S: bar |
| 99 | </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" name="code"> |
| 100 | ["foo",nil,"bar"] |
| 101 | </pre><h2><a name="Single line reply">Single line reply</a></h2>As already seen a single line reply is in the form of a single line string |
| 102 | starting with "+" terminated by "\r\n". For example:<br/><br/><pre class="codeblock python python python python python python python python python python" name="code"> |
| 103 | +OK |
| 104 | </pre>The client library should return everything after the "+", that is, the string "OK" in the example.<br/><br/>The following commands reply with a status code reply: |
| 105 | PING, SET, SELECT, SAVE, BGSAVE, SHUTDOWN, RENAME, LPUSH, RPUSH, LSET, LTRIM<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 ":" byte. For example ":0\r\n", or ":1000\r\n" 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="Multi bulk commands">Multi bulk commands</a></h2>As you can see with the protocol described so far there is no way to |
| 106 | send multiple binary-safe arguments to a command. With bulk commands the |
| 107 | last argument is binary safe, but there are commands where multiple binary-safe |
| 108 | commands are needed, like the MSET command that is able to SET multiple keys |
| 109 | in a single operation.<br/><br/>In order to address this problem Redis 1.1 introduced a new way of seding |
| 110 | commands to a Redis server, that uses exactly the same protocol of the |
| 111 | multi bulk replies. For instance the following is a SET command using the |
| 112 | normal bulk protocol:<br/><br/><pre class="codeblock python python python python python python python python python python python" name="code"> |
| 113 | SET mykey 8 |
| 114 | myvalue |
| 115 | </pre>While the following uses the multi bulk command protocol:<br/><br/><pre class="codeblock python python python python python python python python python python python python" name="code"> |
| 116 | *3 |
| 117 | $3 |
| 118 | SET |
| 119 | $5 |
| 120 | mykey |
| 121 | $8 |
| 122 | myvalue |
| 123 | </pre>Commands sent in this format are longer, so currently they are used only in |
| 124 | order to transmit commands containing multiple binary-safe arguments, but |
| 125 | actually this protocol can be used to send every kind of command, without to |
| 126 | know if it's an inline, bulk or multi-bulk command.<br/><br/>It is possible that in the future Redis will support only this format.<br/><br/>A good client library may implement unknown commands using this |
| 127 | command format in order to support new commands out of the box without |
| 128 | modifications.<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. |
| 129 | Pipelining is supported so multiple commands can be sent with a single |
| 130 | write operation by the client, it is not needed to read the server reply |
| 131 | in 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 |
| 132 | very important to support this feature in a client implementation, still |
| 133 | if an application needs to issue a very large number of commands in short |
| 134 | time to use pipelining can be much faster. |
| 135 | </b> |
| 136 | </div> |
| 137 | |
| 138 | </div> |
| 139 | </div> |
| 140 | </body> |
| 141 | </html> |
| 142 | |
projects / redis.git / blame