By Version

Redis Extension Reference Guide

Redis is an in-memory data store used as a database, cache, streaming engine, and message broker. The Quarkus Redis extension allows integrating Quarkus applications with Redis.

To use this extension, the user must be familiar with Redis, especially understanding the mechanism of commands and how they are organized. Typically, we recommend:

The interactive tutorial introducing Redis.
The command references explains Redis commands and contains links to reference documentation.

This extension provides imperative and reactive APIs and low-level and high-level (type-safe) clients.

1. Installation

If you want to use this extension, you need to add the io.quarkus:quarkus-redis extension first. In your pom.xml file, add:

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-redis-client</artifactId>
</dependency>

build.gradle

implementation("io.quarkus:quarkus-redis-client")

With this dependency, you can then inject Redis clients or datasource (high-level, type-safe API), such as:

import io.quarkus.redis.datasource.RedisDataSource;

// ...
@Inject RedisAPI lowLevelClient;
@Inject RedisDataSource highLevelApi;

More details about the various APIs offered by the quarkus-redis extension are available in the One extension, multiple APIs section.

To use Redis as a cache backend, refer to the Redis Cache Backend reference.

2. One extension, multiple APIs

This extension provides multiple ways to interact with Redis:

the low-level Vert.x client: it’s a fully reactive, non-blocking, and asynchronous client. More details on the Vert.x Redis Client documentation. Two APIs are exposed: io.vertx.redis.client.Redis, and io.vertx.redis.client.RedisAPI. You will generally use the latter, except if you need to manage connections yourself.
the low-level Mutiny variant of the Vert.x API: Unlike the previous one, it exposes a Mutiny API and provides both reactive and imperative methods (suffixed with andAwait()). Two APIs are exposed: io.vertx.mutiny.redis.client.Redis and io.vertx.mutiny.redis.client.RedisAPI. You will generally use the latter, except if you need to manage connections yourself.
a high-level reactive data source: A type-safe, high-level API to interact with Redis. This API is fully reactive and asynchronous. It exposes a Mutiny API. It exposes the io.quarkus.redis.datasource.ReactiveRedisDataSource interface.
a high-level imperative data source: A type-safe, high-level API to interact with Redis. It is the imperative variant of the reactive data source. It exposes the io.quarkus.redis.datasource.RedisDataSource interface.

To help you select the suitable API for you, here are some recommendations:

If you are building an imperative (classic) Quarkus application integrating with Redis: use io.quarkus.redis.datasource.RedisDataSource.
If you are building a reactive Quarkus application integrating with Redis: use io.quarkus.redis.datasource.ReactiveRedisDataSource.
If you need fine-grain control, or execute commands in a generic way: use io.vertx.mutiny.redis.client.RedisAPI
If you have existing Vert.x code, use io.vertx.redis.client.RedisAPI
If you need to emit custom commands, you can either use the data sources (reactive or imperative) or the io.vertx.mutiny.redis.client.Redis.

3. Default and named clients

This extension lets you configure a default Redis client/data sources or named ones. The latter is essential when you need to connect to multiple Redis instances.

The default connection is configured using the quarkus.redis.* properties. For example, to configure the default Redis client, use:

quarkus.redis.hosts=redis://localhost/

When using the default connection, you can inject the various APIS using a plain @Inject:

@ApplicationScoped
public class RedisExample {
    @Inject ReactiveRedisDataSource reactiveDataSource;
    @Inject RedisDataSource redisDataSource;
    @Inject RedisAPI redisAPI;
    // ...
}

In general, you inject a single one; the previous snippet is just an example.

Named clients are configured using the quarkus.redis.<name>.* properties:

quarkus.redis.my-redis-1.hosts=redis://localhost/
quarkus.redis.my-redis-2.hosts=redis://my-other-redis:6379

To access the APIs, you need to use the @RedisClientName qualifier:

@ApplicationScoped
public class RedisExample {
    @Inject @RedisClientName("my-redis-1") ReactiveRedisDataSource reactiveDataSource;
    @Inject @RedisClientName("my-redis-2") RedisDataSource redisDataSource;
    // ...
}

You can omit the @Inject annotation when using @RedisClientName.

4. Connection to Redis

The Redis extension can operate in 4 distinct modes:

Simple client (probably what most users need).
Sentinel (when working with Redis in High Availability mode).
Cluster (when working with Redis in Clustered mode).
Replication (single shard, one node write, multiple read).

The connection url is configured with the quarkus.redis.hosts (or quarkus.redis.<name>.hosts) as follows:

quarkus.redis.hosts=redis://[:password@]host[:port][/db-number]

4.1. Unix Socket

When using unix-socket, you need:

quarkus.redis.hosts=unix://[:password@]/domain/docker.sock[?select=db-number]

4.2. Sentinel Mode

When using Sentinel, you need to pass multiple host urls and configure the client type to sentinel:

quarkus.redis.hosts=redis://localhost:5000,redis://localhost:5001,redis://localhost:5002
quarkus.redis.client-type=sentinel

# Optional
quarkus.redis.master-name=my-sentinel # Default is my-master
quarkus.redis.role=master # master is the default

4.3. Cluster Mode

When using Redis in cluster mode, you need to pass multiple host urls, configure the client type to cluster and configure the replicas mode:

quarkus.redis.hosts=redis://localhost:7000,redis://localhost:7001,redis://localhost:7002
quarkus.redis.client-type=cluster
quarkus.redis.replicas=share

4.4. Replication Mode

When using the replication mode, you need to pass a single host url and configure the type to be replication:

quarkus.redis.hosts=redis://localhost:7000
quarkus.redis.client-type=replication

4.5. Redis Cloud

To connect to redis cloud, you need the following properties:

quarkus.redis.hosts=<the redis cloud url such as redis://redis-12436.c14.us-east-1-3.ec2.cloud.redislabs.com:12436>
quarkus.redis.password=<the password>

4.6. Authentication

The Redis password can be set in the redis:// URL or with the quarkus.redis.password property. We recommend the latter, and if possible, using secrets or an environment variable to configure the password.

The associated environment variable is QUARKUS_REDIS_PASSWORD, or QUARKUS_REDIS_<NAME>_PASSWORD for named clients.

5. Quarkus client API for data sources

Quarkus exposes a high-level API on top of Redis. This API is type-safe and structured around the notion of group, inherited from the Redis command organization. This API lets you execute Redis commands more conveniently and safely.

5.1. Inject data sources

For each configured Redis client, two Redis data sources are exposed:

io.quarkus.redis.datasource.RedisDataSource - an imperative (blocking) Redis data source. Each operation blocks until a response is received or a timeout is reached
io.quarkus.redis.datasource.ReactiveRedisDataSource - a reactive Redis data source returning Uni<X> or Multi<X>.

If you configured the default Redis client, you could inject the data sources using:

@Inject RedisDataSource defaultRedisDataSource;
@Inject ReactiveRedisDataSource defaultReactiveRedisDataSource;

If you configured a named Redis client, you need to use the io.quarkus.redis.RedisClientName qualifier to select the right client:

@RedisClientName("my-redis") RedisDataSource myRedisDataSource;
@RedisClientName("my-redis") ReactiveRedisDataSource myReactiveRedisDataSource;

When using the blocking variant, you can configure the default timeout with:

quarkus.redis.timeout=5s
quarkus.redis.my-redis.timeout=5s

The default timeout is configured to 10s.

All about delegation

The blocking data source (io.quarkus.redis.datasource.RedisDataSource) is implemented on top of the reactive one (io.quarkus.redis.datasource.ReactiveRedisDataSource). The ReactiveRedisDataSource is implemented on top of the io.vertx.mutiny.redis.Redis API.

5.1.1. Data Source groups

As mentioned above, the API is divided into groups:

bitmap - .bitmap()
bitmap - .bitmap()
key (generic) - .key()
geo - .geo(memberType)
hash - .hash(`valueType)
hyperloglog - .hyperloglog(memberType)
list - .list(memberType)
pubsub - pubsub()
set - .set(memberType)
sorted-set - .sortedSet(memberType)
string - .value(valueType)
stream - .stream(`valueType)
transactions - withTransaction
json - .json() (requires the RedisJSON module on the server side)
bloom - .bloom() (requires the RedisBloom module on the server side)
cuckoo - .cuckoo() (requires the rRedisBloom module on the server side, which also provides the cuckoo filter commands)
count-min - .countmin() (requires the RedisBloom module on the server side, which also provides the count-min filter commands)
top-k - .topk() (requires the RedisBloom module on the server side, which also provides the top-k filter commands)
graph - .graph() (requires the RedisGraph module on the server side). These commands are marked as experimental, as we would need feedback before making them stable.
search - .search() (requires the RedisSearch module on the server side).
auto-suggest - .autosuggest() (requires the RedisSearch module on the server side).
time-series - .timeseries() (requires the Redis Time Series module on the server side).

These commands are marked as experimental, as we would need feedback before making them stable.

Each of these methods returns an object that lets you execute the commands related to the group. The following snippet demonstrates how to use the hash group:

@ApplicationScoped
public class MyRedisService {

    private static final String MY_KEY = "my-key";

    private final HashCommands<String, String, Person> commands;

    public MyRedisService(RedisDataSource ds) { (1)
        commands = ds.hash(Person.class); (2)
    }

    public void set(String field, Person value) {
        commands.hset(MY_KEY, field, value);  (3)
    }

    public Person get(String field) {
        return commands.hget(MY_KEY, field);  (4)
    }
}

1	Inject the `RedisDataSource` in the constructor
2	Creates the `HashCommands` object. This object has three type parameters: the type of the key, the type of the field, and the type of the member
3	Use the created `commands` to associate the field `field` with the value `value`
4	Use the created `commands` to retrieve the field `field` value.

5.2. Serialization and Deserialization

The data source APIs handle the serialization and deserialization automatically. When a non-standard type is used, the object is serialized into JSON and deserialized from JSON. In this case, quarkus-jackson is used.

To store binary data, use byte[].

5.3. The `value` group

The value group is used to manipulate Redis Strings. Thus, this group is not limited to Java Strings but can be used for integers (like a counter) or binary content (like images).

5.3.1. Work with cached values

You can use Redis as a cache using the setex command, which stores a given value to a given key for a given duration. The following snippet shows how such a command can be used to store BusinessObject for 1 second.

@ApplicationScoped
public static class MyRedisCache {

    private final ValueCommands<String, BusinessObject> commands;

    public MyRedisCache(RedisDataSource ds) {
        commands = ds.value(BusinessObject.class);
    }

    public BusinessObject get(String key) {
        return commands.get(key);
    }

    public void set(String key, BusinessObject bo) {
        commands.setex(key, 1, bo); // Expires after 1 second
    }
}

You can use the setnx method only to set the value if no value has been stored for the given key.

The key group provides more fine-grain control on expiration and ttl of each key.

The set method can also receive a SetArgs argument that modify the behavior:

ex(seconds) - Set the specified expire time, in seconds.
px(milliseconds) - Set the specified expire time, in milliseconds.
exat(timestamp-seconds) - Set the specified Unix time at which the key will expire, in seconds.
pxat(timestamp-milliseconds) - Set the specified Unix time at which the key will expire, in milliseconds.
nx() - Only set the key if it does not already exist.
xx() - Only set the key if it already exists.
keepttl() - Retain the time to live associated with the key.

5.3.2. Store binary data

Redis strings can be used to store binary data, such as images. In this case, we will use byte[] as value type:

@ApplicationScoped
public static class MyBinaryRepository {

    private final ValueCommands<String, byte[]> commands;

    public MyBinaryRepository(RedisDataSource ds) {
        commands = ds.value(byte[].class);
    }

    public byte[] get(String key) {
        byte[] bytes = commands.get(key);
        if (bytes == null) {
            throw new NoSuchElementException("`" + key + "` not found");
        }
        return bytes;
    }

    public void add(String key, byte[] bytes) {
        commands.set(key, bytes);
    }

    public void addIfAbsent(String key, byte[] bytes) {
        commands.setnx(key, bytes);
    }
}

5.3.3. Store a counter

You can store counters in Redis as demonstrated below:

@ApplicationScoped
public static class MyRedisCounter {

    private final ValueCommands<String, Long> commands;

    public MyRedisCounter(RedisDataSource ds) {
        commands = ds.value(Long.class); (1)
    }

    public long get(String key) {
        Long l = commands.get(key);  (2)
        if (l == null) {
            return 0L;
        }
        return l;
    }

    public void incr(String key) {
        commands.incr(key);  (3)
    }

}

1	Retrieve the commands. This time we will manipulate `Long` values
2	Retrieve the counter associated with the given `key`. Return `0L` when no counter is stored.
3	Increment the value. If there are no counter stored for the key, the `incr` command considers 0 as value (so `incr` sets the value to 1).

There are other methods that can be useful to manipulate counters, such as:

incrby - allows setting the increment value (positive or negative)
incrbyfloat - allows setting the increment value as a float/ double (the stored value will be a double)
set - to set an initial value if needed
decr and decrby - allows decrementing the stored value

5.3.4. Communicate with pub/sub

Redis allows sending messages to channels and listening for these messages. These features are available from the pubsub group.

The following snippets shows how a cache can emit a Notification after every set, and how a subscriber can receive the notification.

public static final class Notification {
    public String key;
    public BusinessObject bo;

    public Notification() {

    }

    public Notification(String key, BusinessObject bo) {
        this.key = key;
        this.bo = bo;
    }
}

@ApplicationScoped
@Startup // We want to create the bean instance on startup to subscribe to the channel.
public static class MySubscriber implements Consumer<Notification> {
    private final PubSubCommands<Notification> pub;
    private final PubSubCommands.RedisSubscriber subscriber;

    public MySubscriber(RedisDataSource ds) {
        pub = ds.pubsub(Notification.class);
        subscriber = pub.subscribe("notifications", this);
    }

    @Override
    public void accept(Notification notification) {
        // Receive the notification
    }

    @PreDestroy
    public void terminate() {
        subscriber.unsubscribe(); // Unsubscribe from all subscribed channels
    }
}

@ApplicationScoped
public static class MyCache {

    private final ValueCommands<String, BusinessObject> commands;
    private final PubSubCommands<Notification> pub;

    public MyCache(RedisDataSource ds) {
        commands = ds.value(BusinessObject.class);
        pub = ds.pubsub(Notification.class);
    }

    public BusinessObject get(String key) {
        return commands.get(key);
    }

    public void set(String key, BusinessObject bo) {
        commands.set(key, bo);
        pub.publish("notifications", new Notification(key, bo));
    }
}

5.3.5. Redis transactions

Redis transactions are slightly different from relational database transactions. Redis transactions are a batch of commands executed altogether.

A Redis transaction can watch a set of keys, which would discard the transaction is one of these keys are updated during the transaction execution.

Commands enqueued in a transaction are not executed before the whole transaction is executed. It means that you cannot retrieve a result during the transaction. Results are accumulated in a TransactionResult object you will access after the completion of the transaction. This object contains whether the transaction succeeded or was discarded, and in the former case the result of each command (indexed by the command order).

To start a transaction, you use the withTransaction method. This method receives a Consumer<TransactionalRedisDataSource>, which follows the same API as the regular RedisDataSource except that the commands return void (Uni<Void> for the reactive variant). When that consumer returns, the transaction is executed.

The following snippet shows how to create a transaction executing two related writes:

@Inject RedisDataSource ds;

// ...

TransactionResult result = ds.withTransaction(tx -> {
        TransactionalHashCommands<String, String, String> hash = tx.hash(String.class);
        hash.hset(KEY, "field-1", "hello");
        hash.hset(KEY, "field-2", "hello");
    });

The received tx object can also be used to discard the transaction, using: tx.discard();. The returned TransactionResult lets you retrieve the result of each command.

When using the reactive variant of the data source, the passed callback is a Function<ReactiveTransactionalRedisDataSource, Uni<Void>>:

@Inject ReactiveRedisDataSource ds;

// ...

Uni<TransactionResult> result = ds.withTransaction(tx -> {
        ReactiveTransactionalHashCommands<String, String, String> hash = tx.hash(String.class);
        return hash.hset(KEY, "field-1", "hello")
            .chain(() -> hash.hset(KEY, "field-2", "hello"));
});

Transaction execution can be conditioned by keys. When a passed key gets modified during the execution of a transaction, the transaction is discarded. The keys are passed as String as a second parameter to the withTransaction method:

TransactionResult result = ds.withTransaction(tx -> {
    TransactionalHashCommands<String, String, String> hash = tx.hash(String.class);
    hash.hset(KEY, "field-1", "hello");
    hash.hset(KEY, "field-2", "hello");
}, KEY);

You cannot use the pub/sub feature from within a transaction.

5.3.6. Optimistic locking

To use optimistic locking, you need to use a variant of the withTransaction method, allowing the execution of code before the transaction starts. In other words, it will be executed as follows:

WATCH key

// Pre-transaction block
// ....
// Produce a result

MULTI
  // In transaction code, receive the result produced by the pre-transaction block.
EXEC

For example, if you need to update a value in a hash only if the field exists, you will use the following API:

OptimisticLockingTransactionResult<Boolean> result = blocking.withTransaction(ds -> {
    // The pre-transaction block:
    HashCommands<String, String, String> hashCommands = ds.hash(String.class);
    return hashCommands.hexists(key, "field"); // Produce a result (boolean in this case)
},
 (exists, tx) -> { // The transactional block, receives the result and the transactional data source
        if (exists) {
            tx.hash(String.class).hset(key, "field", "new value");
        } else {
            tx.discard();
        }
 },
  key); // The watched key

If one of the watched keys is touched before or during the execution of the pre-transaction or transactional blocks, the transaction is aborted. The pre-transactional block produces a result that the transactional block can use. This construct is necessary because, within a transaction, the commands do not produce a result. Results can only be retrieved after the execution of the transaction.

The pre-transaction and transactional blocks are invoked on the same Redis connection. Consequently, the pre-transaction block must use the passed data source to execute commands. Thus, the commands are emitted from that connection. These commands must not modify the watched keys.

The transaction is aborted if the pre-transaction block throws an exception (or produces a failure when using the reactive API).

5.3.7. Execute custom commands

To execute a custom command, or a command not supported by the API, use the following approach:

@Inject ReactiveRedisDataSource ds;

// ...

Response response = ds.execute("my-command", param1, param2, param3);

The execute method sends the command to Redis and retrieves the Response. The command name is passed as first parameters. You can add an arbitrary number of String parameters to your command. The result is wrapped into a Response object.

The reactive variant returns a Uni<Response>.

You can also execute custom command in a transaction.

6. Preload data into Redis

On startup, you can configure the Redis client to preload data into the Redis database.

6.1. Load scripts

Specify the load script you want to load using:

quarkus.redis.load-script=import.redis # import.redis is the default in dev mode, no-file is the default in production mode
quarkus.redis.my-redis.load-script=actors.redis, movies.redis

load-script is a build time property than cannot be overridden at runtime.

Note that each client can have a different script, even a list of scripts. In the case of a list, the data is imported in the list order (for example, first actors.redis, then movies.redis for the my-redis client).

6.2. Load Script format

The .redis file follows a one command per line format:

# Line starting with # and -- are ignored, as well as empty lines

-- One command per line:
HSET foo field1 abc field2 123

-- Parameters with spaces must be wrapped into single or double quotes
HSET bar field1 "abc def" field2 '123 456 '

-- Parameters with double quotes must be wrapped into single quotes and the opposite
SET key1 'A value using "double-quotes"'
SET key2 "A value using 'single-quotes'"

Quarkus batches all the commands from a single file and sends all the commands. The loading process fails if there is any error, but the previous instructions may have been executed. To avoid that, you can wrap your command into a Redis transaction:

-- Run inside a transaction
MULTI
SET key value
SET space:key 'another value'
INCR counter
EXEC

6.3. Configuration

The data is loaded when the application starts. By default, it drops the whole database before importing. You can prevent this using quarkus.redis.flush-before-load=false.

Also, the import process only runs if the database is empty (no key). You can force to import even if there is data using the quarkus.redis.load-only-if-empty=false

6.4. Dev/Test vs. Prod

As mentioned above, in dev and test modes, Quarkus tries to import data by looking for the src/main/resources/import.redis. This behavior is disabled in prod mode, and if you want to import even in production, add:

%prod.quarkus.redis.load-script=import.redis

Before importing in prod mode, make sure you configured quarkus.redis.flush-before-load accordingly.

In dev mode, to reload the content of the .redis load scripts, you need to add: %dev.quarkus.vertx.caching=false

7. Vert.x Redis Client

In addition to the high-level API, you can use the Vertx Redis clients directly in your code. The documentation of the Vert.x Redis Client is available on the Vert.x Web Site.

8. Redis Health Check

If you are using the quarkus-smallrye-health extension, quarkus-redis will automatically add a readiness health check to validate the connection to the Redis server.

So when you access the /q/health/ready endpoint of your application you will have information about the connection validation status.

This behavior can be disabled by setting the quarkus.redis.health.enabled property to false in your application.properties.

9. Programmatic Redis Hosts

The RedisHostsProvider programmatically provides redis hosts. This allows for configuration of properties like redis connection password coming from other sources.

This is useful as it removes the need to store sensitive data in application.properties.

@ApplicationScoped
@Identifier("hosts-provider") // the name of the host provider
public class ExampleRedisHostProvider implements RedisHostsProvider {
    @Override
    public Set<URI> getHosts() {
        // do stuff to get the host
        String host = "redis://localhost:6379/3";
        return Collections.singleton(URI.create(host));
    }
}

The host provider can be used to configure the redis client like shown below

quarkus.redis.hosts-provider-name=hosts-provider

10. Customize the Redis options programmatically

You can expose a bean implementing the io.quarkus.redis.client.RedisOptionsCustomizer interface to customize the Redis client options. The bean is called for each configured Redis client:

@ApplicationScoped
public static class MyExampleCustomizer implements RedisOptionsCustomizer {

    @Override
    public void customize(String clientName, RedisOptions options) {
        if (clientName.equalsIgnoreCase("my-redis")
                || clientName.equalsIgnoreCase(RedisConfig.DEFAULT_CLIENT_NAME)) {
            // modify the given options
        } else {
            throw new IllegalStateException("Unknown client name: " + clientName);
        }
    }
}

10.1. Dev Services

See Redis Dev Service.

11. Redis client metrics

11.1. Enable metrics collection

Redis client metrics are automatically enabled when the application also uses the quarkus-micrometer extension. Micrometer collects the metrics of all the Redis clients implemented by the application.

As an example, if you export the metrics to Prometheus, you will get:

# HELP redis_commands_duration_seconds The duration of the operations (commands of batches
# TYPE redis_commands_duration_seconds summary
redis_commands_duration_seconds_count{client_name="<default>",} 3.0
redis_commands_duration_seconds_sum{client_name="<default>",} 0.047500042
# HELP redis_commands_duration_seconds_max The duration of the operations (commands of batches
# TYPE redis_commands_duration_seconds_max gauge
redis_commands_duration_seconds_max{client_name="<default>",} 0.033273167
# HELP redis_pool_active The number of resources from the pool currently used
# TYPE redis_pool_active gauge
redis_pool_active{pool_name="<default>",pool_type="redis",} 0.0
# HELP redis_pool_ratio Pool usage ratio
# TYPE redis_pool_ratio gauge
redis_pool_ratio{pool_name="<default>",pool_type="redis",} 0.0
# HELP redis_pool_queue_size Number of pending elements in the waiting queue
# TYPE redis_pool_queue_size gauge
redis_pool_queue_size{pool_name="<default>",pool_type="redis",} 0.0
# HELP redis_commands_failure_total The number of operations (commands or batches) that have been failed
# TYPE redis_commands_failure_total counter
redis_commands_failure_total{client_name="<default>",} 0.0
# HELP redis_commands_success_total The number of operations (commands or batches) that have been executed successfully
# TYPE redis_commands_success_total counter
redis_commands_success_total{client_name="<default>",} 3.0
# HELP redis_pool_idle The number of resources from the pool currently used
# TYPE redis_pool_idle gauge
redis_pool_idle{pool_name="<default>",pool_type="redis",} 6.0
# HELP redis_pool_completed_total Number of times resources from the pool have been acquired
# TYPE redis_pool_completed_total counter
redis_pool_completed_total{pool_name="<default>",pool_type="redis",} 3.0
# HELP redis_commands_count_total The number of operations (commands or batches) executed
# TYPE redis_commands_count_total counter
redis_commands_count_total{client_name="<default>",} 3.0
# HELP redis_pool_usage_seconds Time spent using resources from the pool
# TYPE redis_pool_usage_seconds summary
redis_pool_usage_seconds_count{pool_name="<default>",pool_type="redis",} 3.0
redis_pool_usage_seconds_sum{pool_name="<default>",pool_type="redis",} 0.024381375
# HELP redis_pool_usage_seconds_max Time spent using resources from the pool
# TYPE redis_pool_usage_seconds_max gauge
redis_pool_usage_seconds_max{pool_name="<default>",pool_type="redis",} 0.010671542
# HELP redis_pool_queue_delay_seconds Time spent in the waiting queue before being processed
# TYPE redis_pool_queue_delay_seconds summary
redis_pool_queue_delay_seconds_count{pool_name="<default>",pool_type="redis",} 3.0
redis_pool_queue_delay_seconds_sum{pool_name="<default>",pool_type="redis",} 0.022341249
# HELP redis_pool_queue_delay_seconds_max Time spent in the waiting queue before being processed
# TYPE redis_pool_queue_delay_seconds_max gauge
redis_pool_queue_delay_seconds_max{pool_name="<default>",pool_type="redis",} 0.021926083

The Redis client name can be found in the tags.

The metrics contain both the Redis connection pool metrics (redis_pool_*) and the metrics about the command execution (redis_commands_*) such as the number of command, successes, failures, and durations.

11.2. Disable metrics collection

To disable the Redis client metrics when quarkus-micrometer is used, add the following property to the application configuration:

quarkus.micrometer.binder.redis.enabled=false

12. Configuration reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property	Type	Default
`quarkus.redis.load-script` A list of files allowing to pre-load data into the Redis server. The file is formatted as follows: - One instruction per line - Each instruction is a Redis command and its parameter such as `HSET foo field value` - Parameters can be wrapped into double-quotes if they include spaces - Parameters can be wrapped into single-quote if they include spaces - Parameters including double-quotes must be wrapped into single-quotes Environment variable: `QUARKUS_REDIS_LOAD_SCRIPT`	list of string	`import.redis in DEV, TEST ; no-file otherwise`
`quarkus.redis.flush-before-load` When using `redisLoadScript`, indicates if the Redis database must be flushed (erased) before importing. Environment variable: `QUARKUS_REDIS_FLUSH_BEFORE_LOAD`	boolean	`true`
`quarkus.redis.load-only-if-empty` When using `redisLoadScript`, indicates if the import should only happen if the database is empty (no keys). Environment variable: `QUARKUS_REDIS_LOAD_ONLY_IF_EMPTY`	boolean	`true`
`quarkus.redis.health.enabled` Whether a health check is published in case the smallrye-health extension is present. Environment variable: `QUARKUS_REDIS_HEALTH_ENABLED`	boolean	`true`
`quarkus.redis.devservices.enabled` If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running. Environment variable: `QUARKUS_REDIS_DEVSERVICES_ENABLED`	boolean	`true`
`quarkus.redis.devservices.image-name` The container image name to use, for container based DevServices providers. If you want to use Redis Stack modules (bloom, graph, search…), use: `redis/redis-stack-server:latest`. Environment variable: `QUARKUS_REDIS_DEVSERVICES_IMAGE_NAME`	string
`quarkus.redis.devservices.port` Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly. Environment variable: `QUARKUS_REDIS_DEVSERVICES_PORT`	int
`quarkus.redis.devservices.shared` Indicates if the Redis server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Redis starts a new container. The discovery uses the `quarkus-dev-service-redis` label. The value is configured using the `service-name` property. Container sharing is only used in dev mode. Environment variable: `QUARKUS_REDIS_DEVSERVICES_SHARED`	boolean	`true`
`quarkus.redis.devservices.service-name` The value of the `quarkus-dev-service-redis` label attached to the started container. This property is used when `shared` is set to `true`. In this case, before starting a container, Dev Services for Redis looks for a container with the `quarkus-dev-service-redis` label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise, it starts a new container with the `quarkus-dev-service-redis` label set to the specified value. This property is used when you need multiple shared Redis servers. Environment variable: `QUARKUS_REDIS_DEVSERVICES_SERVICE_NAME`	string	`redis`
`quarkus.redis."redis-client-name".load-script` A list of files allowing to pre-load data into the Redis server. The file is formatted as follows: - One instruction per line - Each instruction is a Redis command and its parameter such as `HSET foo field value` - Parameters can be wrapped into double-quotes if they include spaces - Parameters can be wrapped into single-quote if they include spaces - Parameters including double-quotes must be wrapped into single-quotes Environment variable: `QUARKUS_REDIS__REDIS_CLIENT_NAME__LOAD_SCRIPT`	list of string	`import.redis in DEV, TEST ; no-file otherwise`
`quarkus.redis."redis-client-name".flush-before-load` When using `redisLoadScript`, indicates if the Redis database must be flushed (erased) before importing. Environment variable: `QUARKUS_REDIS__REDIS_CLIENT_NAME__FLUSH_BEFORE_LOAD`	boolean	`true`
`quarkus.redis."redis-client-name".load-only-if-empty` When using `redisLoadScript`, indicates if the import should only happen if the database is empty (no keys). Environment variable: `QUARKUS_REDIS__REDIS_CLIENT_NAME__LOAD_ONLY_IF_EMPTY`	boolean	`true`
`quarkus.redis."additional-redis-clients".devservices.enabled` If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running. Environment variable: `QUARKUS_REDIS__ADDITIONAL_REDIS_CLIENTS__DEVSERVICES_ENABLED`	boolean	`true`
`quarkus.redis."additional-redis-clients".devservices.image-name` The container image name to use, for container based DevServices providers. If you want to use Redis Stack modules (bloom, graph, search…), use: `redis/redis-stack-server:latest`. Environment variable: `QUARKUS_REDIS__ADDITIONAL_REDIS_CLIENTS__DEVSERVICES_IMAGE_NAME`	string
`quarkus.redis."additional-redis-clients".devservices.port` Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly. Environment variable: `QUARKUS_REDIS__ADDITIONAL_REDIS_CLIENTS__DEVSERVICES_PORT`	int
`quarkus.redis."additional-redis-clients".devservices.shared` Indicates if the Redis server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Redis starts a new container. The discovery uses the `quarkus-dev-service-redis` label. The value is configured using the `service-name` property. Container sharing is only used in dev mode. Environment variable: `QUARKUS_REDIS__ADDITIONAL_REDIS_CLIENTS__DEVSERVICES_SHARED`	boolean	`true`
`quarkus.redis."additional-redis-clients".devservices.service-name` The value of the `quarkus-dev-service-redis` label attached to the started container. This property is used when `shared` is set to `true`. In this case, before starting a container, Dev Services for Redis looks for a container with the `quarkus-dev-service-redis` label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise, it starts a new container with the `quarkus-dev-service-redis` label set to the specified value. This property is used when you need multiple shared Redis servers. Environment variable: `QUARKUS_REDIS__ADDITIONAL_REDIS_CLIENTS__DEVSERVICES_SERVICE_NAME`	string	`redis`

Configuration property

Type

Default

quarkus.redis.load-script

A list of files allowing to pre-load data into the Redis server. The file is formatted as follows: - One instruction per line - Each instruction is a Redis command and its parameter such as HSET foo field value - Parameters can be wrapped into double-quotes if they include spaces - Parameters can be wrapped into single-quote if they include spaces - Parameters including double-quotes must be wrapped into single-quotes

Environment variable: QUARKUS_REDIS_LOAD_SCRIPT

list of string

import.redis in DEV, TEST ; no-file otherwise

quarkus.redis.flush-before-load

When using redisLoadScript, indicates if the Redis database must be flushed (erased) before importing.

Environment variable: QUARKUS_REDIS_FLUSH_BEFORE_LOAD

boolean

true

quarkus.redis.load-only-if-empty

When using redisLoadScript, indicates if the import should only happen if the database is empty (no keys).

Environment variable: QUARKUS_REDIS_LOAD_ONLY_IF_EMPTY

boolean

true

quarkus.redis.health.enabled

Whether a health check is published in case the smallrye-health extension is present.

Environment variable: QUARKUS_REDIS_HEALTH_ENABLED

boolean

true

quarkus.redis.devservices.enabled

If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running.

Environment variable: QUARKUS_REDIS_DEVSERVICES_ENABLED

boolean

true

quarkus.redis.devservices.image-name

The container image name to use, for container based DevServices providers. If you want to use Redis Stack modules (bloom, graph, search…), use: redis/redis-stack-server:latest.

Environment variable: QUARKUS_REDIS_DEVSERVICES_IMAGE_NAME

string

quarkus.redis.devservices.port

Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly.

Environment variable: QUARKUS_REDIS_DEVSERVICES_PORT

int

quarkus.redis.devservices.shared

Indicates if the Redis server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Redis starts a new container. The discovery uses the quarkus-dev-service-redis label. The value is configured using the service-name property. Container sharing is only used in dev mode.

Environment variable: QUARKUS_REDIS_DEVSERVICES_SHARED

boolean

true

quarkus.redis.devservices.service-name

The value of the quarkus-dev-service-redis label attached to the started container. This property is used when shared is set to true. In this case, before starting a container, Dev Services for Redis looks for a container with the quarkus-dev-service-redis label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise, it starts a new container with the quarkus-dev-service-redis label set to the specified value. This property is used when you need multiple shared Redis servers.

Environment variable: QUARKUS_REDIS_DEVSERVICES_SERVICE_NAME

string

redis

quarkus.redis."redis-client-name".load-script

Environment variable: QUARKUS_REDIS__REDIS_CLIENT_NAME__LOAD_SCRIPT

list of string

import.redis in DEV, TEST ; no-file otherwise

quarkus.redis."redis-client-name".flush-before-load

When using redisLoadScript, indicates if the Redis database must be flushed (erased) before importing.

Environment variable: QUARKUS_REDIS__REDIS_CLIENT_NAME__FLUSH_BEFORE_LOAD

boolean

true

quarkus.redis."redis-client-name".load-only-if-empty

When using redisLoadScript, indicates if the import should only happen if the database is empty (no keys).

Environment variable: QUARKUS_REDIS__REDIS_CLIENT_NAME__LOAD_ONLY_IF_EMPTY

boolean

true

quarkus.redis."additional-redis-clients".devservices.enabled

Environment variable: QUARKUS_REDIS__ADDITIONAL_REDIS_CLIENTS__DEVSERVICES_ENABLED

boolean

true

quarkus.redis."additional-redis-clients".devservices.image-name

The container image name to use, for container based DevServices providers. If you want to use Redis Stack modules (bloom, graph, search…), use: redis/redis-stack-server:latest.

Environment variable: QUARKUS_REDIS__ADDITIONAL_REDIS_CLIENTS__DEVSERVICES_IMAGE_NAME

string

quarkus.redis."additional-redis-clients".devservices.port

Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly.

Environment variable: QUARKUS_REDIS__ADDITIONAL_REDIS_CLIENTS__DEVSERVICES_PORT

int

quarkus.redis."additional-redis-clients".devservices.shared

Environment variable: QUARKUS_REDIS__ADDITIONAL_REDIS_CLIENTS__DEVSERVICES_SHARED

boolean

true

quarkus.redis."additional-redis-clients".devservices.service-name

Environment variable: QUARKUS_REDIS__ADDITIONAL_REDIS_CLIENTS__DEVSERVICES_SERVICE_NAME

string

redis

Redis Extension Reference Guide

1. Installation

2. One extension, multiple APIs

3. Default and named clients

4. Connection to Redis

4.1. Unix Socket

4.2. Sentinel Mode

4.3. Cluster Mode

4.4. Replication Mode

4.5. Redis Cloud

4.6. Authentication

5. Quarkus client API for data sources

5.1. Inject data sources

5.1.1. Data Source groups

5.2. Serialization and Deserialization

5.3. The value group

5.3.1. Work with cached values

5.3.2. Store binary data

5.3.3. Store a counter

5.3.4. Communicate with pub/sub

5.3.5. Redis transactions

5.3.6. Optimistic locking

5.3.7. Execute custom commands

6. Preload data into Redis

6.1. Load scripts

6.2. Load Script format

6.3. Configuration

6.4. Dev/Test vs. Prod

7. Vert.x Redis Client

8. Redis Health Check

9. Programmatic Redis Hosts

10. Customize the Redis options programmatically

10.1. Dev Services

11. Redis client metrics

11.1. Enable metrics collection

11.2. Disable metrics collection

12. Configuration reference

5.3. The `value` group