Skip to content

Commit 0fca107

Browse files
oleiadeoleiade
committed
Amend redis Client's documentation to fit API changes
1 parent 80545c3 commit 0fca107

File tree

1 file changed

+202
-29
lines changed
  • docs/sources/next/javascript-api/k6-experimental/redis/client

1 file changed

+202
-29
lines changed

‎docs/sources/next/javascript-api/k6-experimental/redis/client/_index.md‎

Lines changed: 202 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,198 @@
11
---
22
title: 'Client'
3-
excerpt: 'Client is a Redis client to interact with a Redis server or cluster.'
3+
excerpt: 'Client is a Redis client to interact with a Redis server, cluster, or sentinel.'
44
weight: 10
55
weight: 10
66
---
77

88
# Client
99

10-
`Client` is a Redis client to interact with a Redis server or cluster. It exposes a promise-based API, which users can interact with in an asynchronous manner.
10+
`Client` is a [Redis](https://redis.io) client to interact with a Redis server, sentinel or cluster. It exposes a promise-based API, which users can interact with in an asynchronous manner.
1111

12-
Though the API intends to be thorough and extensive, it does not expose the whole Redis API.
13-
Instead, the intent is to expose Redis for use cases most appropriate to k6.
12+
Though the API intends to be thorough and extensive, it does not expose the whole Redis API. Instead, the intent is to expose Redis for use cases most appropriate to k6.
1413

15-
Note that the `Client` is configured through the [`Options`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/redis-options) object.
14+
## Usage
1615

17-
## Example
16+
### Single-node server
17+
18+
As shown in the above example, the simplest way to create a new `Client` instance that connects to a single Redis server is by passing a URL string.
19+
It must be in the format:
20+
21+
`redis[s]://[[username][:password]@][host][:port][/db-number]`
22+
23+
Here's an example of a URL string that connects to a Redis server running on localhost, on the default port (6379), and using the default database (0):
24+
25+
{{< code >}}
26+
27+
```javascript
28+
import redis from 'k6/experimental/redis';
29+
30+
const client = new redis.Client('redis://localhost:6379');
31+
```
32+
33+
{{< /code >}}
34+
35+
A client can also be instantiated using an [options](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/redis-options) object to support more complex use cases, and for more flexibility:
36+
37+
{{< code >}}
38+
39+
```javascript
40+
import redis from 'k6/experimental/redis';
41+
42+
const client = new redis.Client({
43+
socket: {
44+
host: 'localhost',
45+
port: 6379,
46+
},
47+
username: 'someusername',
48+
password: 'somepassword',
49+
});
50+
```
51+
52+
{{< /code >}}
53+
54+
### TLS
55+
56+
A TLS connection can be established in a couple of ways.
57+
58+
If the server has a certificate signed by a public Certificate Authority, you can use the `rediss` URL scheme:
59+
60+
{{< code >}}
61+
62+
```javascript
63+
import redis from 'k6/experimental/redis';
64+
65+
const client = new redis.Client('rediss://example.com');
66+
```
67+
68+
{{< /code >}}
69+
70+
Otherwise, you can supply your own self-signed certificate in PEM format using the [socket.tls](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/redis-options#tls-configuration-options-tlsoptions) object:
71+
72+
{{< code >}}
73+
74+
```javascript
75+
import redis from 'k6/experimental/redis';
76+
77+
const client = new redis.Client({
78+
socket: {
79+
host: 'localhost',
80+
port: 6379,
81+
tls: {
82+
ca: [open('ca.crt')],
83+
},
84+
},
85+
});
86+
```
87+
88+
{{< /code >}}
89+
90+
Note that for self-signed certificates, k6's [**insecureSkipTLSVerify**](https://grafana.com/docs/k6/<K6_VERSION>/using-k6/k6-options/reference/#insecure-skip-tls-verify) option must be enabled (set to `true`).
91+
92+
#### TLS client authentication (mTLS)
93+
94+
You can also enable mTLS by setting two additional properties in the [socket.tls](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/redis-options#tls-configuration-options-tlsoptions) object:
95+
96+
{{< code >}}
97+
98+
```javascript
99+
import redis from 'k6/experimental/redis';
100+
101+
const client = new redis.Client({
102+
socket: {
103+
host: 'localhost',
104+
port: 6379,
105+
tls: {
106+
ca: [open('ca.crt')],
107+
cert: open('client.crt'), // client certificate
108+
key: open('client.key'), // client private key
109+
},
110+
},
111+
});
112+
```
113+
114+
{{< /code >}}
115+
116+
### Cluster client
117+
118+
You can connect to a cluster of Redis servers by using the [cluster](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/redis-options#redis-cluster-options-clusteroptions) configuration property, and passing 2 or more node URLs:
119+
120+
{{< code >}}
121+
122+
```javascript
123+
import redis from 'k6/experimental/redis';
124+
125+
const client = new redis.Client({
126+
cluster: {
127+
// Cluster options
128+
maxRedirects: 3,
129+
readOnly: true,
130+
routeByLatency: true,
131+
routeRandomly: true,
132+
nodes: ['redis://host1:6379', 'redis://host2:6379'],
133+
},
134+
});
135+
```
136+
137+
{{< /code >}}
138+
139+
Or the same as above, but passing [socket](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/redis-options#socket-connection-options-socketoptions) objects to the nodes array instead of URLs:
140+
141+
{{< code >}}
142+
143+
```javascript
144+
import redis from 'k6/experimental/redis';
145+
146+
const client = new redis.Client({
147+
cluster: {
148+
nodes: [
149+
{
150+
socket: {
151+
host: 'host1',
152+
port: 6379,
153+
},
154+
},
155+
{
156+
socket: {
157+
host: 'host2',
158+
port: 6379,
159+
},
160+
},
161+
],
162+
},
163+
});
164+
```
165+
166+
{{< /code >}}
167+
168+
### Sentinel client
169+
170+
A [Redis Sentinel](https://redis.io/docs/management/sentinel/) provides high availability features, as an alternative to a Redis cluster.
171+
172+
You can connect to a sentinel instance by setting additional [options](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/redis-options) in the object passed to the `Client` constructor:
173+
174+
{{< code >}}
175+
176+
```javascript
177+
import redis from 'k6/experimental/redis';
178+
179+
const client = new redis.Client({
180+
username: 'someusername',
181+
password: 'somepassword',
182+
socket: {
183+
host: 'localhost',
184+
port: 6379,
185+
},
186+
// Sentinel options
187+
masterName: 'masterhost',
188+
sentinelUsername: 'sentineluser',
189+
sentinelPassword: 'sentinelpass',
190+
});
191+
```
192+
193+
{{< /code >}}
194+
195+
## Real world example
18196

19197
{{< code >}}
20198

@@ -42,15 +220,8 @@ export const options = {
42220
},
43221
};
44222

45-
// Get the redis instance(s) address and password from the environment
46-
const redis_addrs = __ENV.REDIS_ADDRS || '';
47-
const redis_password = __ENV.REDIS_PASSWORD || '';
48-
49223
// Instantiate a new redis client
50-
const redisClient = new redis.Client({
51-
addrs: redis_addrs.split(',') || new Array('localhost:6379'), // in the form of 'host:port', separated by commas
52-
password: redis_password,
53-
});
224+
const redisClient = new redis.Client(`redis://localhost:6379`);
54225

55226
// Prepare an array of crocodile ids for later use
56227
// in the context of the measureUsingRedisData function.
@@ -111,10 +282,12 @@ export function handleSummary(data) {
111282

112283
{{< /code >}}
113284

114-
## key/value methods
285+
## API
286+
287+
### Key value methods
115288

116-
| Method | Redis command | Description |
117-
| :----------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- | :-------------------------------------------------------------------------- |
289+
| Method | Redis command | Description |
290+
| :-------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- | :-------------------------------------------------------------------------- |
118291
| [`Client.set(key, value, expiration)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-set) | **[SET](https://redis.io/commands/set)** | Set `key` to hold `value`, with a time to live equal to `expiration`. |
119292
| [`Client.get(key)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-get) | **[GET](https://redis.io/commands/get)** | Get the value of `key`. |
120293
| [`Client.getSet(key, value)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-getset) | **[GETSET](https://redis.io/commands/getset)** | Atomically sets `key` to `value` and returns the old value stored at `key`. |
@@ -131,10 +304,10 @@ export function handleSummary(data) {
131304
| [`Client.ttl(key)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-ttl) | **[TTL](https://redis.io/commands/ttl)** | Returns the remaining time to live of a key that has a timeout. |
132305
| [`Client.persist(key)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-persist) | **[PERSIST](https://redis.io/commands/persist)** | Removes the existing timeout on key. |
133306

134-
## List methods
307+
### List methods
135308

136-
| Method | Redis command | Description |
137-
| :----------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------- | :------------------------------------------------------------------------------ |
309+
| Method | Redis command | Description |
310+
| :-------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------- | :------------------------------------------------------------------------------ |
138311
| [`Client.lpush(key, values)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-lpush) | **[LPSUH](https://redis.io/commands/lpush)** | Inserts all the specified values at the head of the list stored at `key`. |
139312
| [`Client.rpush(key, values)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-rpush) | **[RPUSH](https://redis.io/commands/rpush)** | Inserts all the specified values at the tail of the list stored at `key`. |
140313
| [`Client.lpop(key)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-lpop) | **[LPOP](https://redis.io/commands/lpop)** | Removes and returns the first element of the list stored at `key`. |
@@ -145,10 +318,10 @@ export function handleSummary(data) {
145318
| [`Client.lrem(key, count, value)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-lrem) | **[LREM](https://redis.io/commands/lrem)** | Removes the first `count` occurrences of `value` from the list stored at `key`. |
146319
| [`Client.llen(key)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-llen) | **[LLEN](https://redis.io/commands/llen)** | Returns the length of the list stored at `key`. |
147320

148-
## Hash methods
321+
### Hash methods
149322

150-
| Method | Redis command | Description |
151-
| :------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------- | :--------------------------------------------------------------------------------------------------- |
323+
| Method | Redis command | Description |
324+
| :--------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------- | :--------------------------------------------------------------------------------------------------- |
152325
| [`Client.hset(key, field, value)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-hset) | **[HSET](https://redis.io/commands/hset)** | Sets the specified field in the hash stored at `key` to `value`. |
153326
| [`Client.hsetnx(key, field, value)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-hsetnx) | **[HSETNX](https://redis.io/commands/hsetnx)** | Sets the specified field in the hash stored at `key` to `value`, only if `field` does not yet exist. |
154327
| [`Client.hget(key, field)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-hget) | **[HGET](https://redis.io/commands/hget)** | Returns the value associated with `field` in the hash stored at `key`. |
@@ -159,19 +332,19 @@ export function handleSummary(data) {
159332
| [`Client.hlen(key)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-hlen) | **[HLEN](https://redis.io/commands/hlen)** | Returns the number of fields in the hash stored at `key`. |
160333
| [`Client.hincrby(key, field, increment)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-hincrby) | **[HINCRBY](https://redis.io/commands/hincrby)** | Increments the integer value of `field` in the hash stored at `key` by `increment`. |
161334

162-
## Set methods
335+
### Set methods
163336

164-
| Method | Redis command | Description |
165-
| :------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------- | :----------------------------------------------------------------------- |
337+
| Method | Redis command | Description |
338+
| :--------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------- | :----------------------------------------------------------------------- |
166339
| [`Client.sadd(key, members)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-sadd) | **[SADD](https://redis.io/commands/sadd)** | Adds the specified members to the set stored at `key`. |
167340
| [`Client.srem(key, members)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-srem) | **[SREM](https://redis.io/commands/srem)** | Removes the specified members from the set stored at `key`. |
168341
| [`Client.sismember(key, member)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-sismember) | **[SISMEMBER](https://redis.io/commands/sismember)** | Returns if member is a member of the set stored at `key`. |
169342
| [`Client.smembers(key)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-smembers) | **[SMEMBERS](https://redis.io/commands/smembers)** | Returns all the members of the set values stored at `keys`. |
170343
| [`Client.srandmember(key)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-srandmember) | **[SRANDMEMBER](https://redis.io/commands/srandmember)** | Returns a random element from the set value stored at `key`. |
171344
| [`Client.spop(key)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-spop) | **[SPOP](https://redis.io/commands/spop)** | Removes and returns a random element from the set value stored at `key`. |
172345

173-
## miscellaneous
346+
### Miscellaneous
174347

175-
| Method | Description |
176-
| :------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------- |
348+
| Method | Description |
349+
| :--------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------- |
177350
| [`Client.sendCommand(command, args)`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-experimental/redis/client/client-sendcommand) | Send a command to the Redis server. |

0 commit comments

Comments
 (0)