Client

Mon, 21 Sep 2026 15:16:28 +0000

Client

Client is a Redis 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.

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.

Usage

Single-node server

You can create a new Client instance that connects to a single Redis server by passing a URL string. It must be in the format:

redis[s]://[[username][:password]@][host][:port][/db-number]

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):

import redis from 'k6/x/redis';

const client = new redis.Client('redis://localhost:6379');

A client can also be instantiated using an options object to support more complex use cases, and for more flexibility:

import redis from 'k6/x/redis';

const client = new redis.Client({
  socket: {
    host: 'localhost',
    port: 6379,
  },
  username: 'someusername',
  password: 'somepassword',
});

TLS

You can configure a TLS connection in a couple of ways.

If the server has a certificate signed by a public Certificate Authority, you can use the rediss URL scheme:

import redis from 'k6/x/redis';

const client = new redis.Client('rediss://example.com');

Otherwise, you can supply your own self-signed certificate in PEM format using the socket.tls object:

import redis from 'k6/x/redis';

const client = new redis.Client({
  socket: {
    host: 'localhost',
    port: 6379,
    tls: {
      ca: [open('ca.crt')],
    },
  },
});

Note that for self-signed certificates, k6’s insecureSkipTLSVerify option must be enabled (set to true).

TLS client authentication (mTLS)

You can also enable mTLS by setting two additional properties in the socket.tls object:

import redis from 'k6/x/redis';

const client = new redis.Client({
  socket: {
    host: 'localhost',
    port: 6379,
    tls: {
      ca: [open('ca.crt')],
      cert: open('client.crt'), // client certificate
      key: open('client.key'), // client private key
    },
  },
});

Cluster client

You can connect to a cluster of Redis servers by using the cluster configuration property, and passing 2 or more node URLs:

import redis from 'k6/x/redis';

const client = new redis.Client({
  cluster: {
    // Cluster options
    maxRedirects: 3,
    readOnly: true,
    routeByLatency: true,
    routeRandomly: true,
    nodes: ['redis://host1:6379', 'redis://host2:6379'],
  },
});

Or the same as above, but passing socket objects to the nodes array instead of URLs:

import redis from 'k6/x/redis';

const client = new redis.Client({
  cluster: {
    nodes: [
      {
        socket: {
          host: 'host1',
          port: 6379,
        },
      },
      {
        socket: {
          host: 'host2',
          port: 6379,
        },
      },
    ],
  },
});

Sentinel client

A Redis Sentinel provides high availability features, as an alternative to a Redis cluster.

You can connect to a sentinel instance by setting additional options in the object passed to the Client constructor:

import redis from 'k6/x/redis';

const client = new redis.Client({
  username: 'someusername',
  password: 'somepassword',
  socket: {
    host: 'localhost',
    port: 6379,
  },
  // Sentinel options
  masterName: 'masterhost',
  sentinelUsername: 'sentineluser',
  sentinelPassword: 'sentinelpass',
});

Real world example

import { check } from 'k6';
import http from 'k6/http';
import redis from 'k6/x/redis';
import exec from 'k6/execution';
import { textSummary } from 'https://jslib.k6.io/k6-summary/0.0.2/index.js';

export const options = {
  scenarios: {
    redisPerformance: {
      executor: 'shared-iterations',
      vus: 10,
      iterations: 200,
      exec: 'measureRedisPerformance',
    },
    usingRedisData: {
      executor: 'shared-iterations',
      vus: 10,
      iterations: 200,
      exec: 'measureUsingRedisData',
    },
  },
};

// Instantiate a new redis client
const redisClient = new redis.Client(`redis://localhost:6379`);

// Prepare an array of rating ids for later use
// in the context of the measureUsingRedisData function.
const ratingIDs = new Array(0, 1, 2, 3, 4, 5, 6, 7, 8, 9);

export async function measureRedisPerformance() {
  // VUs are executed in a parallel fashion,
  // thus, to ensure that parallel VUs are not
  // modifying the same key at the same time,
  // we use keys indexed by the VU id.
  const key = `foo-${exec.vu.idInTest}`;

  await redisClient.set(key, 1);
  await redisClient.incrBy(key, 10);
  const value = await redisClient.get(key);
  if (value !== '11') {
    throw new Error('foo should have been incremented to 11');
  }

  await redisClient.del(key);
  if ((await redisClient.exists(key)) !== 0) {
    throw new Error('foo should have been deleted');
  }
}

export async function setup() {
  await redisClient.sadd('rating_ids', ...ratingIDs);
}

export async function measureUsingRedisData() {
  // Pick a random rating id from the dedicated redis set,
  // we have filled in setup().
  const randomID = await redisClient.srandmember('rating_ids');
  const url = `https://quickpizza.grafana.com/api/ratings/${randomID}`;
  const res = await http.asyncRequest('GET', url, {
    headers: { Authorization: 'token abcdef0123456789' },
  });

  check(res, { 'status is 200': (r) => r.status === 200 });

  await redisClient.hincrby('k6_rating_fetched', url, 1);
}

export async function teardown() {
  await redisClient.del('rating_ids');
}

export function handleSummary(data) {
  redisClient
    .hgetall('k6_rating_fetched')
    .then((fetched) => Object.assign(data, { k6_rating_fetched: fetched }))
    .then((data) => redisClient.set(`k6_report_${Date.now()}`, JSON.stringify(data)))
    .then(() => redisClient.del('k6_rating_fetched'));

  return {
    stdout: textSummary(data, { indent: '  ', enableColors: true }),
  };
}

API

Key value methods

Method	Redis command	Description
`Client.set(key, value, expiration)`	SET	Set `key` to hold `value`, with a time to live equal to `expiration`.
`Client.get(key)`	GET	Get the value of `key`.
`Client.getSet(key, value)`	GETSET	Atomically sets `key` to `value` and returns the old value stored at `key`.
`Client.del(keys)`	DEL	Removes the specified keys.
`Client.getDel(key)`	GETDEL	Get the value of `key` and delete the key.
`Client.exists(keys)`	EXISTS	Returns the number of `key` arguments that exist.
`Client.incr(key)`	INCR	Increments the number stored at `key` by one.
`Client.incrBy(key, increment)`	INCRBY	Increments the number stored at `key` by `increment`.
`Client.decr(key)`	DECR	Decrements the number stored at `key` by one.
`Client.decrBy(key, decrement)`	DECRBY	Decrements the number stored at `key` by `decrement`.
`Client.randomKey()`	RANDOMKEY	Returns a random key’s value.
`Client.mget(keys)`	MGET	Returns the values of all specified keys.
`Client.expire(key, seconds)`	EXPIRE	Sets a timeout on key, after which the key will automatically be deleted.
`Client.ttl(key)`	TTL	Returns the remaining time to live of a key that has a timeout.
`Client.persist(key)`	PERSIST	Removes the existing timeout on key.

List methods

Method	Redis command	Description
`Client.lpush(key, values)`	LPSUH	Inserts all the specified values at the head of the list stored at `key`.
`Client.rpush(key, values)`	RPUSH	Inserts all the specified values at the tail of the list stored at `key`.
`Client.lpop(key)`	LPOP	Removes and returns the first element of the list stored at `key`.
`Client.rpop(key)`	RPOP	Removes and returns the last element of the list stored at `key`.
`Client.lrange(key, start, stop)`	LRANGE	Returns the specified elements of the list stored at `key`.
`Client.lindex(key, start, stop)`	LINDEX	Returns the specified element of the list stored at `key`.
`Client.lset(key, index, element)`	LSET	Sets the list element at `index` to `element`.
`Client.lrem(key, count, value)`	LREM	Removes the first `count` occurrences of `value` from the list stored at `key`.
`Client.llen(key)`	LLEN	Returns the length of the list stored at `key`.

Hash methods

Method	Redis command	Description
`Client.hset(key, field, value)`	HSET	Sets the specified field in the hash stored at `key` to `value`.
`Client.hsetnx(key, field, value)`	HSETNX	Sets the specified field in the hash stored at `key` to `value`, only if `field` does not yet exist.
`Client.hget(key, field)`	HGET	Returns the value associated with `field` in the hash stored at `key`.
`Client.hdel(key, fields)`	HDEL	Deletes the specified fields from the hash stored at `key`.
`Client.hgetall(key)`	HGETALL	Returns all fields and values of the hash stored at `key`.
`Client.hkeys(key)`	HKEYS	Returns all fields of the hash stored at `key`.
`Client.hvals(key)`	HVALS	Returns all values of the hash stored at `key`.
`Client.hlen(key)`	HLEN	Returns the number of fields in the hash stored at `key`.
`Client.hincrby(key, field, increment)`	HINCRBY	Increments the integer value of `field` in the hash stored at `key` by `increment`.

Set methods

Method	Redis command	Description
`Client.sadd(key, members)`	SADD	Adds the specified members to the set stored at `key`.
`Client.srem(key, members)`	SREM	Removes the specified members from the set stored at `key`.
`Client.sismember(key, member)`	SISMEMBER	Returns if member is a member of the set stored at `key`.
`Client.smembers(key)`	SMEMBERS	Returns all the members of the set values stored at `keys`.
`Client.srandmember(key)`	SRANDMEMBER	Returns a random element from the set value stored at `key`.
`Client.spop(key)`	SPOP	Removes and returns a random element from the set value stored at `key`.

Miscellaneous

Method	Description
`Client.sendCommand(command, args)`	Send a command to the Redis server.

Options

Mon, 21 Sep 2026 15:16:28 +0000

Redis options

You can configure the Redis Client by using a Redis connection URL as demonstrated in the client documentation, or by using an Options object to access more advanced configuration.

Options

The configuration for the overall Redis client, including authentication and connection settings.

Option Name	Type	Description
socket	SocketOptions	The configuration of the connection socket used to connect to the Redis server.
username	String (optional)	Username for client authentication.
password	String (optional)	Password for client authentication.
clientName	String (optional)	Name for the client connection.
database	Number (optional)	Database ID to select after connecting.
masterName	String (optional)	Master instance name for Sentinel.
sentinelUsername	String (optional)	Username for Sentinel authentication.
sentinelPassword	String (optional)	Password for Sentinel authentication.
cluster	ClusterOptions (optional)	The configuration for Redis Cluster connections.

Socket Connection Options

Socket-level settings for connecting to a Redis server.

Option Name	Type	Description
host	String	IP address or hostname of the Redis server.
port	Number (optional)	Port number of the Redis server.
tls	TLSOptions (optional)	The configuration for TLS/SSL.
dialTimeout	Number (optional, default is 5 (seconds))	Timeout for establishing a connection, in seconds.
readTimeout	Number (optional, default is 3 (seconds))	Timeout for socket reads, in seconds. A value of `-1` disables the timeout.
writeTimeout	Number (optional, default is `readTimeout`)	Timeout for socket writes, in seconds. A value of `-1` disables the timeout.
poolSize	Number (optional, default is 10 (per CPU))	Number of socket connections in the pool per CPU.
minIdleConns	Number (optional, default is 0 (idle connections are not closed by default))	Minimum number of idle connections in the pool.
maxConnAge	Number (optional, default is 0 (no maximum idle time))	Maximum time before closing a connection.
poolTimeout	Number (optional, `readTimeout + 1`)	Timeout for acquiring a connection from the pool.
idleTimeout	Number (optional, `readTimeout + 1`)	Timeout for idle connections in the pool.
idleCheckFrequency	Number (optional, default is 1 (minute))	Frequency of idle connection checks, in minutes. A value of `-1` disables the checks.

TLS Configuration Options

Options for establishing a secure TLS connection.

Option Name	Type	Description
ca	ArrayBuffer[]	Array of CA certificates.
cert	ArrayBuffer (optional)	Client certificate for mutual TLS.
key	ArrayBuffer (optional)	Private key associated with the client certificate.

Redis Cluster Options

Options for behavior in a Redis Cluster setup.

Option Name	Type	Description
maxRedirects	Number (optional, default is 3 retries)	Maximum number of command redirects.
readOnly	Boolean (optional)	Enables read-only mode for replicas.
routeByLatency	Boolean (optional)	Route read commands by latency.
routeRandomly	Boolean (optional)	Random routing for read commands.
nodes	String[] or SocketOptions[]	List of cluster nodes as URLs or SocketOptions.

k6/x/redis on Grafana Labs

Client

Client

Usage

Single-node server

TLS

TLS client authentication (mTLS)

Cluster client

Sentinel client

Real world example

API

Key value methods

List methods

Hash methods

Set methods

Miscellaneous

Options

Redis options

Options

Socket Connection Options

TLS Configuration Options

Redis Cluster Options