Skip to content

Commit 4ec8ba7

Browse files
pintsizedpintsized
committed
API documentation
1 parent 1a9e0d5 commit 4ec8ba7

File tree

1 file changed

+120
-56
lines changed

1 file changed

+120
-56
lines changed

‎README.md‎

Lines changed: 120 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,82 +1,146 @@
11
# lua-resty-redis-connector
22

3-
Connection utilities for lua-resty-redis
3+
Connection utilities for [lua-resty-redis](https://github.com/openresty/lua-resty-redis), making
4+
it easy and reliable to connect to Redis hosts, either directly or via
5+
[Redis Sentinel](http://redis.io/topics/sentinel).
6+
47

58
## Synopsis
69

710
```lua
811
local redis_connector = require "resty.redis.connector"
912
local rc = redis_connector.new()
10-
rc:set_connect_timeout(1000)
11-
rc:set_read_timeout(200)
12-
rc:set_connect_options(...)
1313

14-
-- Simple redis connection, to database 1
15-
local redis, err = rc:connect{
16-
host = "127.0.0.1",
17-
port = 6379,
18-
db = 1,
19-
password = "mysecret",
20-
}
14+
local redis, err = rc:connect{ url = "redis://[email protected]:6379/2" }
15+
if not redis then
16+
ngx.log(ngx.ERR, err)
17+
end
18+
```
2119

22-
-- Connect using a Unix socket.
23-
local redis, err = rc:connect{
24-
path = "/tmp/redis.sock",
25-
db = 2,
26-
}
20+
## DSN format
2721

28-
-- Connect via Sentinel, to the master
29-
local redis, err = rc:connect{
30-
mastername = "mymaster",
31-
role = "master",
32-
db = 3,
33-
password = "mysecret",
34-
sentinels = {
35-
{ host = "127.0.0.1", 26379 },
36-
{ host = "192.168.1.1", 26379 },
37-
},
38-
}
22+
The [connect](#connect) method accepts a single table of named arguments. If the `url` field is
23+
present then it will be parsed, overriding values supplied in the parameters table.
3924

25+
The format for connecting directly to Redis is:
4026

41-
-- Simple connection using a connection string.
42-
local redis, err = rc:connect{ url = "redis://[email protected]:6379/1" }
27+
`redis://PASSWORD@HOST:PORT/DB`
4328

44-
-- Connect via Sentinel to the master with the mastername "mymaster", and select database 3.
45-
local redis, err = rc:connect{
46-
url = "sentinel://PASSWORD@mymaster:m/3",
47-
sentinels = {
48-
{ host = "127.0.0.1", 26379 },
49-
{ host = "192.168.1.1", 26379 },
50-
}
51-
}
29+
The `PASSWORD` and `DB` fields are optional, all other components are required.
5230

31+
When connecting via Redis Sentinel, the format is as follows:
5332

54-
-- Connect to a slave with the mastername "mymaster", and selecte database 2.
55-
local redis, err = rc:connect{
56-
url = "redis://PASSWORD@mymaster:s/2",
57-
sentinels = {
58-
{ host = "127.0.0.1", 26379 },
59-
{ host = "192.168.1.1", 26379 },
60-
}
61-
}
33+
`sentinel://PASSWORD@MASTER_NAME:ROLE/DB`
6234

63-
rc:connect{ url = "redis://PASSWORD@mymaster:s/2", sentinels = { host = "127.0.0.1", port = 26379 } }
35+
Again, `PASSWORD` and `DB` are optional. `ROLE` must be any of `m`, `s` or `a`, meaning:
6436

65-
rc:connect{
66-
cluster_startup_nodes = {
67-
{ host = "127.0.0.1", port = 6379 },
68-
}
37+
`m`: master
38+
`s`: slave
39+
`a`: any (first tries the master, but will failover to a slave if required)
40+
41+
42+
## Parameters
43+
44+
The [connect](#connect) method expects the following field values, either by falling back to
45+
defaults, populating the fields by parsing the DSN, or being specified directly.
46+
47+
The defaults are as follows:
48+
49+
50+
```lua
51+
{
52+
host = "127.0.0.1",
53+
port = "6379",
54+
path = nil, -- unix socket path, e.g. /tmp/redis.sock
55+
password = "",
56+
db = 0,
57+
master_name = "mymaster",
58+
role = "master",
59+
sentinels = nil,
6960
}
61+
```
7062

71-
-- Attempt connection to the master with the mastername "mymaster". If it
72-
-- cannot be reached, try each slave until one connects. Then select database 2.
63+
Note that if `sentinel://` is supplied as the `url` parameter, a table of `sentinels` must also
64+
be supplied. e.g.
65+
66+
``lua
7367
local redis, err = rc:connect{
74-
url = "sentinel://PASSWORD@mymaster:ms/2",
68+
url = "sentinel://mymaster:a/2",
7569
sentinels = {
76-
{ host = "127.0.0.1", port = 26379 },
77-
{ host = "192.168.1.1", port = 26379 },
70+
{ host = "127.0.0.1", port = 26379" },
7871
}
7972
}
73+
```
8074
8175
82-
```
76+
## API
77+
78+
* [new](#new)
79+
* [set_connect_timeout](#set_connect_timeout)
80+
* [set_read_timeout](#set_read_timeout)
81+
* [set_connection_options](#set_connection_options)
82+
* [connect](#connect)
83+
84+
85+
### new
86+
87+
`syntax: rc = redis_connector.new()`
88+
89+
Creates the Redis Connector object. In case of failures, returns `nil` and a string describing the error.
90+
91+
92+
### set_connect_timeout
93+
94+
`syntax: rc:set_connect_timeout(100)`
95+
96+
Sets the cosocket connection timeout, in ms.
97+
98+
99+
100+
### set_read_timeout
101+
102+
`syntax: rc:set_read_timeout(500)`
103+
104+
Sets the cosocket read timeout, in ms.
105+
106+
107+
### set_connection_options
108+
109+
`syntax: rc:set_connection_options({ pool = params.host .. ":" .. params.port .. "/" .. params.db })`
110+
111+
Sets the connection options table, as supplied to [tcpsock:connect](https://github.com/openresty/lua-nginx-module#tcpsockconnect)
112+
method.
113+
114+
115+
### connect
116+
117+
`syntax: redis, err = rc:connect(params)`
118+
119+
Attempts to create a connection, according to the [params](#parameters) supplied.
120+
121+
122+
## TODO
123+
124+
* Redis Cluster support.
125+
126+
127+
# Author
128+
129+
James Hurst <[email protected]>
130+
131+
132+
# Licence
133+
134+
This module is licensed under the 2-clause BSD license.
135+
136+
Copyright (c) 2013, James Hurst <[email protected]>
137+
138+
All rights reserved.
139+
140+
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
141+
142+
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
143+
144+
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
145+
146+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

0 commit comments

Comments
 (0)