Connecting to Your Database

There are multiple ways to connect to your Redis database depending on your networking setup, clustering configuration, and client preferences. This article outlines the supported methods for connecting—whether you're using DNS, a load balancer, Sentinel, the OSS Cluster API, or official Redis tools and client libraries.

Use this guide to select the connection approach that best fits your architecture and operational needs.

For the full list of supported clients and links to their docs, visit the Redis Client Libraries page.

Before You Connect

Now that you’ve created a database on your Redis cluster, you can test the connection using the appropriate endpoint.

The connection URL depends on your deployment configuration.

In most cases, the client connects to the endpoint shown in the Redis UI or is retrieved via the rladmin CLI.

If you're using a load balancer in front of Redis, use the hostname and port of the load balancer instead.

To retrieve database endpoints:

• Use the rladmin status extra all command
• Or review the database configuration in the Redis UI

For details on cluster DNS setup, refer to Cluster DNS Configuration.

Connect using a DNS endpoint

Retrieve the database endpoint from the UI

Retrieve the database endpoint via ‘rladmin’ command line tool.

The tool can be executed on any Redis cluster node.

For the example above, the endpoint is “redis-12863.sallatest.primary.cs.redislabs.com,” and the port is “12863”. The default password for the database can be set in the UI.

Connect using a Load Balancer

If your Redis cluster is fronted by a load balancer, you can connect to a database using the load balancer's hostname and port.

a. Basic Connection

Use the following connection format in your client or tool: redis://<load-balancer-hostname>:<port>

b. Requirements

• The load balancer must be configured to route traffic to the Redis database endpoint(s).
• The Database Proxy Policy must allow external client access through the load balancer.
• The Redis client must support the protocol in use (e.g., TLS if enabled).

Example

If your load balancer is set up at lb.redis.example.com and your database listens on port 12000, your connection string would be: redis://lb.redis.example.com:12000

For TLS-enabled databases, use rediss:// instead of redis://

Connect using Redis Sentinel

Retrieve Sentinel Endpoint Information

Each node in your Redis cluster runs a Sentinel-compatible Discovery Service on port 8001. To obtain the necessary connection details:

• Hostname: Use the fully qualified domain name (FQDN) or IP address of a cluster node.

• Port: Use port 8001, which is designated for the Discovery Service.

For high availability, it's recommended to configure your client with multiple node addresses.

Configure Your Redis Client

Set up your Redis client to use Sentinel mode, providing the following parameters:

• Sentinel Addresses: List of node hostnames/IPs with port 8001.

• Master Name: The name of your Redis Enterprise database.

• Authentication: If your database requires authentication, provide the necessary credentials.

Refer to your specific client's documentation for exact configuration instructions.

Establish the Connection

With the configuration in place, initiate the connection from your client. The client will communicate with the Discovery Service to determine the current master node and establish a connection accordingly.

For more detailed information, consult the Redis Discovery Service.

Connect using the OSS Cluster API

Ensure OSS Cluster API is Enabled

Before connecting, verify that the OSS Cluster API is enabled for your database. This can be done via the Redis Cluster Manager UI or the rladmin command-line tool.

Using Cluster Manager UI:

1. Navigate to the Configuration tab of your database.

2. Click Edit.

3. Expand the Clustering section.

4. Enable Sharding.

5. Enable OSS Cluster API.

6. Click Save

Using rladmin:

Run the following command, replacing <db_name> with your database name:

Note: Enabling OSS Cluster API requires the database to use the standard hashing policy and have the proxy policy set to either all-master-shards or all-nodes. Additionally, certain modules like Redis Search, RedisTimeSeries, or RedisGears shouldn't be enabled. 

Configure Your Client for Cluster Mode

To connect using the OSS Cluster API, your Redis client must support cluster mode. Configure your client with the addresses of all cluster nodes. Here's an example using Python's redis-py library:

from redis.cluster import RedisCluster
startup_nodes = [
   {"host": "node1.example.com", "port": 12000},
   {"host": "node2.example.com", "port": 12000},
   {"host": "node3.example.com", "port": 12000}
]
rc = RedisCluster(startup_nodes=startup_nodes, decode_responses=True)

Replace node1.example.com, node2.example.com, and node3.example.com with the actual hostnames or IP addresses of your cluster nodes, and 12000 with the appropriate port number.

Note: Make sure your client library supports the OSS Cluster API. Libraries like redis-py, Jedis, and go-redis have cluster mode support. 

Connect and Interact with the Database

With the client configured, you can now connect and perform operations:

The client will automatically handle the cluster topology, directing commands to the appropriate node.

Additional Considerations

• Multi-Key Operations: When using the OSS Cluster API, multi-key commands are only allowed if all keys involved are in the same hash slot. Make sure that keys share the same hash tag if you need to perform such operations. 

• IP Address Exposure: By default, the CLUSTER SLOTS and CLUSTER SHARDS commands may expose internal IP addresses. To change this behavior and expose external IPs instead, run:

Replace <db_name> with your database name.

For more detailed information, refer to the OSS Cluster API .

Connect using Redis CLI and tools

Connect with redis-cli

redis-cli is the command-line interface for interacting with Redis databases.

a. Basic Connection

To connect to your Redis database:

• Replace <endpoint> with your database's hostname or IP address.

• Replace <port> with the port number your database is listening on.

• Replace <password> with your database password.

Alternatively, you can set the password using the REDISCLI_AUTH environment variable:

b. Connect Over TLS

If your Redis database is configured to use TLS:

1. Obtain the Server Certificate:

   • For Redis Software, download the proxy_cert.pem from the Cluster Manager UI under Cluster > Security > Certificates > Server authentication, or retrieve it from a cluster node at /etc/opt/redislabs/proxy_cert.pem.

2. Connect using TLS:

   • Without client authentication:

     redis-cli -h <endpoint> -p <port> --tls --cacert proxy_cert.pem

   • With client authentication:

     redis-cli -h <endpoint> -p <port> --tls --cacert proxy_cert.pem --cert client_cert.pem --key client_key.pem

Make sure that your redis-cli is compiled with TLS support.

If you encounter issues, refer to the TLS connection failure guide.

Connect with Redis Insight

Redis Insight is a graphical tool for managing and visualizing Redis data

a. Installation

Download and install Redis Insight for your operating system from the Redis Installation documentation

b. Add a Redis Database

1. Open Redis Insight and click on Add Redis Database.

2. Fill in the following details:

   • Name: A friendly name for your connection.

   • Host: The hostname or IP address of your Redis database.

   • Port: The port number your Redis database is listening on.

   • Username: If applicable, enter your Redis username.

   • Password: Enter your Redis password.

   • Use TLS: Enable this if your database requires TLS.

3. Click Add Redis Database to establish the connection.

For more detailed information, refer to the Redis Insight documentation

Connect using official Redis client libraries

Redis provides official client libraries for Java,.NET, Python, Go, and Node.js, making it easy to connect to Redis databases with optimized performance and seamless integration.

These libraries—Jedis, NRedisStack, redis-py, go-redis, and node-redis—are developed and maintained by Redis, Inc., making sure they stay current with the latest features and best practices. Each client is tuned for Redis Software and Redis Cloud, and built to simplify migration from open-source Redis environments.

Java – Jedis

a. Basic Connection:

import redis.clients.jedis.UnifiedJedis;

public class Main {
    public static void main(String[] args) {
        UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379");

        // Interact with Redis

        jedis.close();
    }
}

b. TLS Connection:

To connect over TLS, ensure your certificates are in the correct format. Convert your PEM files to PKCS12 using OpenSSL

openssl pkcs12 -export \
 -in redis_user.crt \
 -inkey redis_user_private.key \
 -out redis-user-keystore.p12 \
 -name "redis"

Then, configure your Java application to use the redis-user-keystore.p12 for secure connections

c. Cluster Configuration:

Jedis supports Redis Cluster configurations. Use JedisCluster to connect to a cluster-enabled Redis database.

d. Failover Support:

For geo-distributed active-active databases, Jedis provides failover mechanisms to ensure high availability.

Resources:

• Jedis GitHub Repository
• Jedis Documentation 

.NET – NRedisStack

a. Basic Connection:

using StackExchange.Redis;
var options = ConfigurationOptions.Parse("localhost:6379");
var connection = ConnectionMultiplexer.Connect(options);
var db = connection.GetDatabase();

b. TLS Connection:

Convert your PEM files to PFX format

Then, configure your.NET application to use redis.pfx for secure connections

Resources:

• NRedisStack GitHub Repository
• NRedisStack Documentation

Python – redis-py

a. Basic Connection:

import redis
r = redis.Redis(host='localhost', port=6379, decode_responses=True)
r.set('foo', 'bar')
print(r.get('foo'))

b. TLS Connection:

import redis
r = redis.Redis(
   host='my-redis.cloud.redislabs.com',
   port=6379,
   username='default',
   password='secret',
   ssl=True,
   ssl_certfile='./redis_user.crt',
   ssl_keyfile='./redis_user_private.key',
   ssl_ca_certs='./redis_ca.pem'
)

c. Cluster Configuration:

from redis.cluster import RedisCluster
rc = RedisCluster(host='localhost', port=16379)
rc.set('foo', 'bar')
print(rc.get('foo'))

Resources:

• redis-py GitHub Repository
• redis-py Documentation

Go – go-redis

a. Basic Connection:

import (
"http://github.com/redis/go-redis/v9 "
)
var rdb = redis.NewClient(&redis.Options{
Addr: "localhost:6379",
Password: "", // no password set
DB: 0, // use default DB
})

b. TLS Connection:

import (
"crypto/tls"
"github.com/redis/go-redis/v9"
)
var tlsConfig = &tls.Config{
// Configure TLS settings here, e.g., InsecureSkipVerify: true (not recommended for production)
}
var rdb = redis.NewClient(&redis.Options{
Addr: "my-redis.cloud.redislabs.com:6379",
Password: "secret",
TLSConfig: tlsConfig,
})

Resources:

• go-redis GitHub Repository
• go-redis Documentation

Node.js – node-redis

a. Basic Connection:

import { createClient } from 'redis';
const client = createClient();
client.on('error', err => console.log('Redis Client Error', err));
await client.connect();
await client.set('key', 'value');
const value = await client.get('key');
console.log(value);

b. TLS Connection:

import { createClient } from 'redis';
import { readFileSync } from 'fs';
const client = createClient({
   socket: {
       host: 'my-redis.cloud.redislabs.com',
       port: 6379,
       tls: true,
       key: readFileSync('./redis_user_private.key'),
       cert: readFileSync('./redis_user.crt'),
       ca: [readFileSync('./redis_ca.pem')]
   },
   username: 'default',
   password: 'secret'
});
await client.connect();

c. Cluster Configuration:

import { createCluster } from 'redis';
const cluster = createCluster({
   rootNodes: [
       { url: 'redis://127.0.0.1:16379' },
       { url: 'redis://127.0.0.1:16380' },
       // Add more nodes as needed
   ]
});
cluster.on('error', (err) => console.log('Redis Cluster Error', err));
await cluster.connect();
await cluster.set('foo', 'bar');
const value = await cluster.get('foo');
console.log(value);
await cluster.quit();

Additional Resources

• node-redis GitHub Repository
• node-redis Documentation

• Test Client Connection

For more detailed information and advanced configurations, refer to Connect with Redis client API libraries.

Onboarding Progress

Previous: Database Creation
Next: Data Migration Options for Redis

Return to the Redis Software Onboarding Overview to view all steps.