Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 104 lines (71 sloc) 4.259 kb
c10bef2 Brian Hammond Updated README
fictorial authored
1 # Redis client for Node.js
32b0f9f Initial import
Brian Hammond authored
2
c10bef2 Brian Hammond Updated README
fictorial authored
3 ## In a nutshell
7fc74b6 Big refactor.
Brian Hammond authored
4
c10bef2 Brian Hammond Updated README
fictorial authored
5 - Talk to Redis from Node.js
6 - Fully asynchronous; your code is called back when an operation completes
d073c40 Brian Hammond 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 Brian Hammond Queue commands when not connected; auto-reconnect works; emits events 'c...
fictorial authored
8 - e.g. store a PNG in Redis if you'd like
c10bef2 Brian Hammond 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 Brian Hammond Queue commands when not connected; auto-reconnect works; emits events 'c...
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 Brian Hammond 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 Brian Hammond Note about backwards compatibility
fictorial authored
14
c10bef2 Brian Hammond Updated README
fictorial authored
15 ## Synopsis
aa563d3 Brian Hammond README updated regarding PUBSUB example
fictorial authored
16
bda6ede Brian Hammond Fixes for Kiwi
fictorial authored
17 When working from a git clone:
18
c10bef2 Brian Hammond Updated README
fictorial authored
19 var sys = require("sys");
1f9a3c7 Brian Hammond Queue commands when not connected; auto-reconnect works; emits events 'c...
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 Brian Hammond 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 Brian Hammond Queue commands when not connected; auto-reconnect works; emits events 'c...
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 Brian Hammond Updated README
fictorial authored
39 });
7fc74b6 Big refactor.
Brian Hammond authored
40
827c85c Brian Hammond 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 Brian Hammond 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 Brian Hammond Add package.json
fictorial authored
47
95c5c78 Brian Hammond updated compatibility info
fictorial authored
48 Tested with Node.js `v0.1.93` and Redis `1.3.10`.
ad801c2 Brian Hammond bump version
fictorial authored
49
827c85c Brian Hammond 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 Brian Hammond 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 Brian Hammond Me talk pretty one day
fictorial authored
58 depends on a unreleased version of Node.js.
01f3115 Brian Hammond Note about installation via Kiwi and NPM
fictorial authored
59
adf5a34 Brian Hammond 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 Brian Hammond Kiwi support
fictorial authored
65 Then run `node test/test.js [-v|-q]` where `-v` is for "verbose" and `-q` is for "quiet".
adf5a34 Brian Hammond Note about running tests
fictorial authored
66
827c85c Brian Hammond Kiwi support
fictorial authored
67 $ node test/test.js
deaaa95 Brian Hammond 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 Brian Hammond Updated README
fictorial authored
76 ## Documentation
7fc74b6 Big refactor.
Brian Hammond authored
77
c10bef2 Brian Hammond 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 Brian Hammond 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 Brian Hammond Note about subscribeTo/unsubscribeFrom
fictorial authored
95 Note: for PUBSUB, you should use `subscribeTo` and `unsubscribeFrom` instead of the generated
28ef9d5 Brian Hammond 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 Brian Hammond Note about subscribeTo/unsubscribeFrom
fictorial authored
98
c10bef2 Brian Hammond 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.