-
Notifications
You must be signed in to change notification settings - Fork 1.7k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'master' of github.com:/antirez/redis-doc
- Loading branch information
Showing
143 changed files
with
2,953 additions
and
2,051 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,84 +1,123 @@ | ||
Redis documentation | ||
=== | ||
# Redis documentation | ||
|
||
## Clients | ||
|
||
Clients | ||
--- | ||
All clients are listed in the `clients.json` file. | ||
Each key in the JSON object represents a single client library. | ||
For example: | ||
|
||
All clients are listed in the `clients.json` file. Each key in the JSON | ||
object represents a single client library. For example: | ||
``` | ||
"Rediska": { | ||
"Rediska": { | ||
# A programming language should be specified. | ||
"language": "PHP", | ||
# A programming language should be specified. | ||
"language": "PHP", | ||
# If the project has a website of its own, put it here. | ||
# Otherwise, lose the "url" key. | ||
"url": "http://rediska.geometria-lab.net", | ||
# If the project has a website of its own, put it here. | ||
# Otherwise, lose the "url" key. | ||
"url": "http://rediska.geometria-lab.net", | ||
# A URL pointing to the repository where users can | ||
# find the code. | ||
"repository": "http://github.com/Shumkov/Rediska", | ||
# A URL pointing to the repository where users can | ||
# find the code. | ||
"repository": "http://github.com/Shumkov/Rediska", | ||
# A short, free-text description of the client. | ||
# Should be objective. The goal is to help users | ||
# choose the correct client they need. | ||
"description": "A PHP client", | ||
# A short, free-text description of the client. | ||
# Should be objective. The goal is to help users | ||
# choose the correct client they need. | ||
"description": "A PHP client", | ||
# An array of Twitter usernames for the authors | ||
# and maintainers of the library. | ||
"authors": ["shumkov"] | ||
# An array of Twitter usernames for the authors | ||
# and maintainers of the library. | ||
"authors": ["shumkov"] | ||
} | ||
``` | ||
|
||
} | ||
|
||
|
||
Commands | ||
--- | ||
## Commands | ||
|
||
Redis commands are described in the `commands.json` file. | ||
|
||
For each command there's a Markdown file with a complete, human-readable | ||
description. We process this Markdown to provide a better experience, so | ||
some things to take into account: | ||
description. | ||
We process this Markdown to provide a better experience, so some things to take | ||
into account: | ||
|
||
* Inside text, all commands should be written in all caps, in between | ||
backticks. | ||
For example: `INCR`. | ||
|
||
* You can use some magic keywords to name common elements in Redis. | ||
For example: `@multi-bulk-reply`. | ||
These keywords will get expanded and auto-linked to relevant parts of the | ||
documentation. | ||
|
||
There should be at least two predefined sections: description and return value. | ||
The return value section is marked using the @return keyword: | ||
|
||
``` | ||
Returns all keys matching the given pattern. | ||
@return | ||
@multi-bulk-reply: all the keys that matched the pattern. | ||
``` | ||
|
||
## Styling guidelines | ||
|
||
Please use the following formatting rules: | ||
|
||
* Wrap lines to 80 characters. | ||
* Start every sentence on a new line. | ||
|
||
Luckily, this repository comes with an automated Markdown formatter. | ||
To only reformat the files you have modified, first stage them using `git add` | ||
(this makes sure that your changes won't be lost in case of an error), then run | ||
the formatter: | ||
|
||
* Inside text, all commands should be written in all caps, in between | ||
backticks. For example: <code>`INCR`</code>. | ||
``` | ||
$ rake format:cached | ||
``` | ||
|
||
* You can use some magic keywords to name common elements in Redis. For | ||
example: `@multi-bulk-reply`. These keywords will get expanded and | ||
auto-linked to relevant parts of the documentation. | ||
The formatter has the following dependencies: | ||
|
||
There should be at least two predefined sections: description and | ||
return value. The return value section is marked using the @return | ||
keyword: | ||
* Redcarpet | ||
* Nokogiri | ||
* The `par` tool | ||
|
||
Returns all keys matching the given pattern. | ||
Installation of the Ruby gems: | ||
|
||
@return | ||
``` | ||
gem install redcarpet nokogiri | ||
``` | ||
|
||
@multi-bulk-reply: all the keys that matched the pattern. | ||
Installation of par (OSX): | ||
|
||
``` | ||
brew install par | ||
``` | ||
|
||
Styling guidelines | ||
--- | ||
Installation of par (Ubuntu): | ||
|
||
Please wrap your text to 80 characters. You can easily accomplish this | ||
using a CLI tool called `par`. | ||
``` | ||
sudo apt-get install par | ||
``` | ||
|
||
## Checking your work | ||
|
||
Checking your work | ||
--- | ||
Once you're done, the very least you should do is make sure that all files | ||
compile properly. | ||
You can do this by running Rake inside your working directory. | ||
|
||
Once you're done, the very least you should do is make sure that all | ||
files compile properly. You can do this by running Rake inside your | ||
working directory. | ||
``` | ||
$ rake parse | ||
``` | ||
|
||
$ rake parse | ||
Additionally, if you have [Aspell][han] installed, you can spell check the | ||
documentation: | ||
|
||
Additionally, if you have [Aspell](http://aspell.net/) installed, you | ||
can spell check the documentation: | ||
[han]: http://aspell.net/ | ||
|
||
$ rake spellcheck | ||
``` | ||
$ rake spellcheck | ||
``` | ||
|
||
Exceptions can be added to `./wordlist`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,43 +1,56 @@ | ||
If `key` already exists and is a string, this command appends the `value` at | ||
the end of the string. If `key` does not exist it is created and set as an | ||
empty string, so `APPEND` will be similar to `SET` in this special case. | ||
If `key` already exists and is a string, this command appends the `value` at the | ||
end of the string. | ||
If `key` does not exist it is created and set as an empty string, so `APPEND` | ||
will be similar to `SET` in this special case. | ||
|
||
@return | ||
|
||
@integer-reply: the length of the string after the append operation. | ||
|
||
@examples | ||
|
||
@cli | ||
EXISTS mykey | ||
APPEND mykey "Hello" | ||
APPEND mykey " World" | ||
GET mykey | ||
```cli | ||
EXISTS mykey | ||
APPEND mykey "Hello" | ||
APPEND mykey " World" | ||
GET mykey | ||
``` | ||
|
||
Pattern: Time series | ||
--- | ||
## Pattern: Time series | ||
|
||
the `APPEND` command can be used to create a very compact representation of | ||
a list of fixed-size samples, usually referred as *time series*. | ||
the `APPEND` command can be used to create a very compact representation of a | ||
list of fixed-size samples, usually referred as _time series_. | ||
Every time a new sample arrives we can store it using the command | ||
|
||
APPEND timeseries "fixed-size sample" | ||
``` | ||
APPEND timeseries "fixed-size sample" | ||
``` | ||
|
||
Accessing to individual elements in the time serie is not hard: | ||
Accessing individual elements in the time series is not hard: | ||
|
||
* `STRLEN` can be used in order to obtain the number of samples. | ||
* `GETRANGE` allows for random access of elements. If our time series have an associated time information we can easily implement a binary search to get range combining `GETRANGE` with the Lua scripting engine available in Redis 2.6. | ||
* `GETRANGE` allows for random access of elements. | ||
If our time series have an associated time information we can easily implement | ||
a binary search to get range combining `GETRANGE` with the Lua scripting | ||
engine available in Redis 2.6. | ||
* `SETRANGE` can be used to overwrite an existing time serie. | ||
|
||
The limitations of this pattern is that we are forced into an append-only mode of operation, there is no way to cut the time series to a given size easily because Redis currently lacks a command able to trim string objects. However the space efficiency of time series stored in this way is remarkable. | ||
|
||
Hint: it is possible to switch to a different key based on the current unix time, in this way it is possible to have just a relatively small amount of samples per key, to avoid dealing with very big keys, and to make this pattern more | ||
firendly to be distributed across many Redis instances. | ||
|
||
An example sampling the temperature of a sensor using fixed-size strings (using a binary format is better in real implementations). | ||
|
||
@cli | ||
APPEND ts "0043" | ||
APPEND ts "0035" | ||
GETRANGE ts 0 3 | ||
GETRANGE ts 4 7 | ||
The limitations of this pattern is that we are forced into an append-only mode | ||
of operation, there is no way to cut the time series to a given size easily | ||
because Redis currently lacks a command able to trim string objects. | ||
However the space efficiency of time series stored in this way is remarkable. | ||
|
||
Hint: it is possible to switch to a different key based on the current Unix | ||
time, in this way it is possible to have just a relatively small amount of | ||
samples per key, to avoid dealing with very big keys, and to make this pattern | ||
more friendly to be distributed across many Redis instances. | ||
|
||
An example sampling the temperature of a sensor using fixed-size strings (using | ||
a binary format is better in real implementations). | ||
|
||
```cli | ||
APPEND ts "0043" | ||
APPEND ts "0035" | ||
GETRANGE ts 0 3 | ||
GETRANGE ts 4 7 | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,17 +1,16 @@ | ||
Request for authentication in a password protected Redis server. | ||
Redis can be instructed to require a password before allowing clients | ||
to execute commands. This is done using the `requirepass` directive in the | ||
configuration file. | ||
Redis can be instructed to require a password before allowing clients to execute | ||
commands. | ||
This is done using the `requirepass` directive in the configuration file. | ||
|
||
If `password` matches the password in the configuration file, the server replies with | ||
the `OK` status code and starts accepting commands. | ||
If `password` matches the password in the configuration file, the server replies | ||
with the `OK` status code and starts accepting commands. | ||
Otherwise, an error is returned and the clients needs to try a new password. | ||
|
||
**Note**: because of the high performance nature of Redis, it is possible to try | ||
a lot of passwords in parallel in very short time, so make sure to generate | ||
a strong and very long password so that this attack is infeasible. | ||
a lot of passwords in parallel in very short time, so make sure to generate a | ||
strong and very long password so that this attack is infeasible. | ||
|
||
@return | ||
|
||
@status-reply | ||
|
Oops, something went wrong.