Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 104 lines (71 sloc) 4.259 kB
c10bef2 @fictorial Updated README
fictorial authored
1 # Redis client for Node.js
32b0f9f Initial import
Brian Hammond authored
2
c10bef2 @fictorial Updated README
fictorial authored
3 ## In a nutshell
7fc74b6 Big refactor.
Brian Hammond authored
4
c10bef2 @fictorial Updated README
fictorial authored
5 - Talk to Redis from Node.js
6 - Fully asynchronous; your code is called back when an operation completes
d073c40 @fictorial Note about backwards compatibility
fictorial authored
7 - [Binary-safe](http://github.com/fictorial/redis-node-client/blob/master/test/test.js#L353-363); uses Node.js Buffer objects for request serialization and reply parsing
1f9a3c7 @fictorial Queue commands when not connected; auto-reconnect works; emits events…
fictorial authored
8 - e.g. store a PNG in Redis if you'd like
c10bef2 @fictorial Updated README
fictorial authored
9 - Client API directly follows Redis' [command specification](http://code.google.com/p/redis/wiki/CommandReference)
10 - *You have to understand how Redis works and the semantics of its command set to most effectively use this client*
1f9a3c7 @fictorial Queue commands when not connected; auto-reconnect works; emits events…
fictorial authored
11 - Supports Redis' new exciting [PUBSUB](http://code.google.com/p/redis/wiki/PublishSubscribe) commands
12 - Automatically reconnects to Redis (doesn't drop commands sent while waiting to reconnect either) using [exponential backoff](http://en.wikipedia.org/wiki/Exponential_backoff)
aadd6e7 @fictorial Solidify reconnection handling, and associated queueing, etc.
fictorial authored
13 - Be sure to see [this script](http://github.com/fictorial/redis-node-client/blob/master/test/test_shutdown_reconnect.js) for a deeper discussion
d073c40 @fictorial Note about backwards compatibility
fictorial authored
14
c10bef2 @fictorial Updated README
fictorial authored
15 ## Synopsis
aa563d3 @fictorial README updated regarding PUBSUB example
fictorial authored
16
bda6ede @fictorial Fixes for Kiwi
fictorial authored
17 When working from a git clone:
18
c10bef2 @fictorial Updated README
fictorial authored
19 var sys = require("sys");
1f9a3c7 @fictorial Queue commands when not connected; auto-reconnect works; emits events…
fictorial authored
20 var client = require("../lib/redis-client").createClient();
21 client.info(function (err, info) {
22 if (err) throw new Error(err);
23 sys.puts("Redis Version is: " + info.redis_version);
24 client.close();
bda6ede @fictorial Fixes for Kiwi
fictorial authored
25 });
26
27 When working with a Kiwi-based installation:
28
29 // $ kiwi install redis-client
30
31 var sys = require("sys"),
32 kiwi = require("kiwi"),
33 client = kiwi.require("redis-client").createClient();
34
1f9a3c7 @fictorial Queue commands when not connected; auto-reconnect works; emits events…
fictorial authored
35 client.info(function (err, info) {
36 if (err) throw new Error(err);
37 sys.puts("Redis Version is: " + info.redis_version);
38 client.close();
c10bef2 @fictorial Updated README
fictorial authored
39 });
7fc74b6 Big refactor.
Brian Hammond authored
40
827c85c @fictorial Kiwi support
fictorial authored
41 - Refer to the many tests in `test/test.js` for many usage examples.
42 - Refer to the `examples/` directory for focused examples.
43
44 ## Installation
45
abf4c4b @fictorial works with just-released node v0.1.90
fictorial authored
46 This version requires at least `Node.js v0.1.90` and Redis `1.3.8`.
d9d953e @fictorial Add package.json
fictorial authored
47
95c5c78 @fictorial updated compatibility info
fictorial authored
48 Tested with Node.js `v0.1.93` and Redis `1.3.10`.
ad801c2 @fictorial bump version
fictorial authored
49
827c85c @fictorial Kiwi support
fictorial authored
50 You have a number of choices:
51
52 - git clone this repo or download a tarball and simply copy `lib/redis-client.js` into your project
53 - use git submodule
54 - use the [Kiwi](http://github.com/visionmedia/kiwi) package manager for Node.js
7fc74b6 Big refactor.
Brian Hammond authored
55
01f3115 @fictorial Note about installation via Kiwi and NPM
fictorial authored
56 Please let me know if the package manager "seeds" and/or metadata have issues.
57 Installation via Kiwi or NPM at this point isn't really possible since this repo
3c403ee @fictorial Me talk pretty one day
fictorial authored
58 depends on a unreleased version of Node.js.
01f3115 @fictorial Note about installation via Kiwi and NPM
fictorial authored
59
adf5a34 @fictorial Note about running tests
fictorial authored
60 ## Running the tests
61
62 A good way to learn about this client is to read the test code.
63
64 To run the tests, install and run redis on the localhost on port 6379 (defaults).
827c85c @fictorial Kiwi support
fictorial authored
65 Then run `node test/test.js [-v|-q]` where `-v` is for "verbose" and `-q` is for "quiet".
adf5a34 @fictorial Note about running tests
fictorial authored
66
827c85c @fictorial Kiwi support
fictorial authored
67 $ node test/test.js
deaaa95 @fictorial Note about running tests
fictorial authored
68 ..................................................................
69 ...........................++++++++++++++++++++++++++++++++++++
70
71 [INFO] All tests have passed.
72
73 If you see something like "PSUBSCRIBE: unknown command" then it is time to upgrade
74 your Redis installation.
75
c10bef2 @fictorial Updated README
fictorial authored
76 ## Documentation
7fc74b6 Big refactor.
Brian Hammond authored
77
c10bef2 @fictorial Updated README
fictorial authored
78 There is a method per Redis command. E.g. `SETNX` becomes `client.setnx`.
79
80 For example, the Redis command [INCRBY](http://code.google.com/p/redis/wiki/IncrCommand)
81 is specified as `INCRBY key integer`. Also, the INCRBY spec says that the reply will
82 be "... the new value of key after the increment or decrement."
83
84 This translates to the following client code which increments key 'foo' by 42. If
85 the value at key 'foo' was 0 or non-existent, 'newValue' will take value 42 when
86 the callback function is called.
87
88 client.incrby('foo', 42, function (err, newValue) {
89 // ...
90 });
91
4adaf3f @fictorial Note about parameters and command spec
fictorial authored
92 This can get [a little wacky](http://github.com/fictorial/redis-node-client/blob/master/test/test.js#L1093-1097).
93 I'm open to suggestions for improvement here.
94
afd09dc @fictorial Note about subscribeTo/unsubscribeFrom
fictorial authored
95 Note: for PUBSUB, you should use `subscribeTo` and `unsubscribeFrom` instead of the generated
28ef9d5 @fictorial Note about subscribeTo/unsubscribeFrom
fictorial authored
96 methods for Redis' `SUBSCRIBE` and `UNSUBSCRIBE` commands. See [this](http://github.com/fictorial/redis-node-client/blob/master/lib/redis-client.js#L682-694)
97 and [this](http://github.com/fictorial/redis-node-client/blob/master/examples/subscriber.js#L14).
afd09dc @fictorial Note about subscribeTo/unsubscribeFrom
fictorial authored
98
c10bef2 @fictorial Updated README
fictorial authored
99 ## Notes
100
101 All commands/requests use the Redis *multi-bulk request* format which will be
102 the only accepted request protocol come Redis 2.0.
103
Something went wrong with that request. Please try again.