Get started
Yandex Managed Service for Redis

Connecting to a non-sharded Redis cluster

Written by

You can connect to a non-sharded Redis cluster:

  • Using Redis Sentinel.

    Redis Sentinel is a Redis host management system that provides monitoring, notification, automatic failover, and reporting of up-to-date host addresses to the clients.

    Unencrypted connection is supported via port 26379 for clusters with any version of Redis.

    If a client application does not support connecting via Sentinel, connect directly to the master host. If there is no need for a direct connection, use Sentinel for more reliable cluster host management.

    For more information about Sentinel, see Replication and fault tolerance and the Redis documentation.

  • Directly to the master host.

    Encrypted connection is supported via port 6380 and unencrypted via port 6379.

    Warning

    When using SSL, you can only connect to clusters with TLS support enabled.

    To always connect to the master host in a non-sharded cluster, use a special FQDN that always points to the master host, or track the roles of all the cluster hosts yourself.

Special FQDNs

Managed Service for Redis provides special FQDNs that can be used instead of regular host FQDNs to connect to non-sharded clusters.

Current master

A FQDN like c-<cluster ID>.rw.mdb.yandexcloud.net in a non-sharded cluster always points to the current master host. The cluster ID can be requested with a list of clusters in the folder.

When connecting to this FQDN, both read and write operations are allowed.

An example an SSL-encrypted connection to a master host for a cluster with c9qash3nb1v9ulc8j9nm as the ID:

redis-cli -h c-c9qash3nb1v9ulc8j9nm.rw.mdb.yandexcloud.net \
  -p 6380 \
  --tls \
  --cacert ~/.redis/YandexCA.crt \
  -a <Redis password>

Connecting to cluster hosts from graphical IDEs

The connection was tested in the following environment:

  • MacOS Big Sur 11.3.
  • DBeaver Enterprise: 21.0.

You can only use graphical IDEs to connect to cluster hosts through an SSL tunnel using a created VM. Before connecting prepare a certificate.

Connections to Redis clusters are only available in commercial versions of DBeaver.

To connect to a cluster:

  1. Create a new DB connection:
    1. In the Database menu, select New connection.
    2. Select the Redis database from the list.
    3. Click Next.
    4. Specify the connection parameters on the Main tab:
      • Host: FQDN of the master host or a special FQDN always pointing to the current master host.
      • Port: 6379 for a regular cluster or 6380 for a cluster with SSL encryption enabled.
      • Under Authentication, specify the cluster password.
    5. On the SSH tab:
      1. Enable the Use SSL tunnel setting.
      2. Specify the SSH tunnel parameters:
        • Host/IP: Public IP address of the VM to connect to.
        • Username: Username for connecting to the VM.
        • Authentication method: Public key.
        • Secret key: Path to the file with the private key used for connecting to the VM.
        • Passphrase: Password of the private key.
    6. On the SSL tab:
      1. Enable the Use SSL and Skip hostname validation settings.
      2. Under Method:
        1. Enable the Set of certificates setting.
        2. In the Root certificate field, specify the path to the file with an SSL certificate for the connection.
  2. Click Test Connection ... to test a DB connection. If the connection is successful, you'll see the connection status and information about the DBMS and driver.
  3. Click Ready to save the database connection settings.

Sample connection strings

The Linux examples were tested in the following environment:

  • Virtual machine in Yandex Cloud running Ubuntu 20.04 LTS.
  • Bash: 5.0.16.
  • Python: 3.8.2; pip3: 20.0.2.
  • PHP: 7.4.3.
  • OpenJDK: 11.0.8; Maven: 3.6.3.
  • Node.JS: 10.19.0, npm: 6.14.4.
  • Go: 1.13.8.
  • Ruby: 2.7.0p0.
  • unixODBC: 2.3.6.

The Windows examples were tested in the following environment:

  • A local machine with Windows 10 Pro build 19042.1052.
  • PowerShell: 5.1.19041.
  • cURL: 7.55.1 WinSSL.

To view an example of the command with the host FQDN filled in, open the cluster page in the management console and click Connect.

Bash

Before connecting, install the dependencies:

sudo apt update && sudo apt install -y redis-tools

Connecting via Sentinel:

  1. Get the address of the master host by using Sentinel and any Redis host:

    redis-cli \
    -h <FQDN of any Redis host> \
    -p 26379 \
    sentinel \
    get-master-addr-by-name <Redis cluster name> | head -n 1

  2. Connect to the host with this address:

    redis-cli \
    -h <Redis master host address> \
    -a <Redis password>

Connecting directly to the master host:

redis-cli \
    -h c-<cluster ID>.rw.mdb.yandexcloud.net \
    -a <password>

Before connecting, install the dependencies:

Build the redis-tools utility with TLS support in one of two ways:

  • From a repository

    1. Connect a repository:

      sudo apt-add-repository ppa:redislabs/redis

      Packages in this repository have already been built with the BUILD_TLS=yes flag.

    2. Install the utility:

      sudo apt update && sudo apt install -y redis-tools

  • Manually

    Go to the directory you want to download the distribution to. Download the stable version of the utility, then build and install it:

    wget https://download.redis.io/redis-stable.tar.gz && \
tar -xzvf redis-stable.tar.gz && \
cd redis-stable && \
make BUILD_TLS=yes && \
sudo make install && \
sudo cp ./src/redis-cli /usr/bin/

Connecting directly to the master host:

redis-cli \
    -h c-<cluster ID>.rw.mdb.yandexcloud.net \
    -a <password> \
    -p 6380 \
    --tls \
    --cacert ~/.redis/YandexCA.crt

When you are connected to the cluster, run the commands:

SET foo bar
GET foo

If the connection to the cluster and the test query are successful, the bar string is output.

Go

Before connecting, install the dependencies:

sudo apt update && sudo apt install -y golang git && \
  go mod init github.com/go-redis/redis && \
  go get github.com/go-redis/redis/v7

Code example for connecting via Sentinel:

connect.go

package main

import (
	"fmt"
	"github.com/go-redis/redis/v7"
)

func main() {
	conn := redis.NewUniversalClient(
		&redis.UniversalOptions{
			Addrs: []string{
				"<FQDN of Redis host 1>:26379",
				...
				"<FQDN of Redis host N>:26379"},
			MasterName: "<Redis cluster name>",
			Password:   "<password>",
			ReadOnly:   false,
		},
	)
	err := conn.Set("foo", "bar", 0).Err()
	if err != nil {
		panic(err)
	}

	result, err := conn.Get("foo").Result()
	if err != nil {
		panic(err)
	}
	fmt.Println(result)

	conn.Close()
}

Code example for connecting directly to the master:

connect.go

package main

import (
	"fmt"
	"github.com/go-redis/redis/v7"
)

func main() {
	conn := redis.NewUniversalClient(
		&redis.UniversalOptions{
			Addrs:    []string{"c-<cluster ID>.rw.mdb.yandexcloud.net:6379"},
			Password: "<password>",
			ReadOnly: false,
		},
	)
	err := conn.Set("foo", "bar", 0).Err()
	if err != nil {
		panic(err)
	}

	result, err := conn.Get("foo").Result()
	if err != nil {
		panic(err)
	}
	fmt.Println(result)

	conn.Close()
}

connect.go

package main

import (
	"crypto/tls"
	"crypto/x509"
	"fmt"
	"github.com/go-redis/redis/v7"
	"io/ioutil"
)

const (
	cert = "/home/<home directory>/.redis/YandexCA.crt"
)

func main() {
	rootCertPool := x509.NewCertPool()
	pem, err := ioutil.ReadFile(cert)
	if err != nil {
		panic(err)
	}

	if ok := rootCertPool.AppendCertsFromPEM(pem); !ok {
		panic("Failed to append PEM.")
	}

	conn := redis.NewUniversalClient(
		&redis.UniversalOptions{
			Addrs:    []string{"c-<cluster ID>.rw.mdb.yandexcloud.net:6380"},
			Password: "<password>",
			ReadOnly: false,
			SSLConfig: &tls.Config{
				RootCAs:            rootCertPool,
				InsecureSkipVerify: true,
			},
		},
	)
	err = conn.Set("foo", "bar", 0).Err()
	if err != nil {
		panic(err)
	}

	result, err := conn.Get("foo").Result()
	if err != nil {
		panic(err)
	}
	fmt.Println(result)

	conn.Close()
}

Connecting:

go run connect.go

If the connection to the cluster and the test query are successful, the bar string is output.

Java

Before connecting:

  1. Install the dependencies:

    sudo apt update && sudo apt install -y default-jdk maven

  2. Create a folder for the Maven project:

    cd ~/ && mkdir -p project/src/java/com/example && cd project/

  3. Create a configuration file for Maven:

    pom.xml
    <?xml version="1.0" encoding="utf-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>app</artifactId>
  <packaging>jar</packaging>
  <version>0.1.0</version>
  <properties>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
  </properties>
  <dependencies>
    <dependency>
      <groupId>redis.clients</groupId>
      <artifactId>jedis</artifactId>
      <version>3.7.0</version>
    </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-simple</artifactId>
      <version>1.7.30</version>
    </dependency>
  </dependencies>
  <build>
    <finalName>${project.artifactId}-${project.version}</finalName>
    <sourceDirectory>src</sourceDirectory>
    <resources>
      <resource>
        <directory>src</directory>
      </resource>
    </resources>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-assembly-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>attached</goal>
            </goals>
            <phase>package</phase>
            <configuration>
              <descriptorRefs>
                <descriptorRef>
                jar-with-dependencies</descriptorRef>
              </descriptorRefs>
              <archive>
                <manifest>
                  <mainClass>com.example.App</mainClass>
                </manifest>
              </archive>
            </configuration>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>3.1.0</version>
        <configuration>
          <archive>
            <manifest>
              <mainClass>com.example.App</mainClass>
            </manifest>
          </archive>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

    Up-to-date versions of dependencies for Maven:

  4. To connect using SSL:

    1. Get an SSL certificate.

    2. Create secure storage for certificates:

      keytool \
    -importcert \
    -alias YARootCrt \
    -file ~/.redis/YandexCA.crt \
    -keystore ~/.redis/YATrustStore \
    -storepass <secure certificate storage password> \
    --noprompt && chmod 0655 ~/.redis/YATrustStore

Code example for connecting via Sentinel:

src/java/com/example/App.java

package com.example;

import java.util.HashSet;
import redis.clients.jedis.Jedis;
import redis.clients.jedis.JedisSentinelPool;

public class App {
  public static void main(String[] args) {
    String redisName = "<Redis cluster name>";
    String redisPass = "<password>";

    HashSet sentinels = new HashSet();
    sentinels.add("<FQDN of Redis host 1>:26379");
    ...
    sentinels.add("<FQDN of Redis host N>:26379");

    try {
      JedisSentinelPool pool = new JedisSentinelPool(redisName, sentinels);
      Jedis conn = pool.getResource();

      conn.auth(redisPass);
      conn.set("foo", "bar");
      System.out.println(conn.get("foo"));

      pool.close();
    } catch (Exception ex) {
      ex.printStackTrace();
    }
  }
}

Code example for connecting directly to the master:

src/java/com/example/App.java

package com.example;

import redis.clients.jedis.Jedis;

public class App {
  public static void main(String[] args) {
    String redisHost = "c-<cluster ID>.rw.mdb.yandexcloud.net";
    String redisPass = "<password>";

    try {
      Jedis conn = new Jedis(redisHost);

      conn.auth(redisPass);
      conn.set("foo", "bar");
      System.out.println(conn.get("foo"));

      conn.close();
    } catch (Exception ex) {
      ex.printStackTrace();
    }
  }
}

src/java/com/example/App.java

package com.example;

import redis.clients.jedis.DefaultJedisClientConfig;
import redis.clients.jedis.HostAndPort;
import redis.clients.jedis.Jedis;

import javax.net.ssl.SSLParameters;

public class App {
  public static void main(String[] args) {
    String redisHost = "c-<cluster ID>.rw.mdb.yandexcloud.net";
    String redisPass = "<cluster password>";

    System.setProperty("javax.net.ssl.trustStore", "/home/<home directory>/.redis/YATrustStore");
    System.setProperty("javax.net.ssl.trustStorePassword", "<password of secure certificate storage>");

    SSLParameters sslParameters = new SSLParameters();
    DefaultJedisClientConfig jedisClientConfig = DefaultJedisClientConfig.builder().
            password(redisPass).
            ssl(true).
            sslParameters(sslParameters).
            build();

    try {
      Jedis conn = new Jedis(new HostAndPort(redisHost, 6380), jedisClientConfig);

      conn.set("foo", "bar");
      System.out.println(conn.get("foo"));
      conn.close();
    } catch (Exception ex) {
      ex.printStackTrace();
    }
  }
}

Connecting:

mvn clean package && \
  java -jar target/app-0.1.0-jar-with-dependencies.jar

If the connection to the cluster and the test query are successful, the bar string is output.

Node.js

Before connecting, install the dependencies:

sudo apt update && sudo apt install -y nodejs npm && \
  npm install ioredis

Code example for connecting via Sentinel:

app.js

"use strict";
const Redis = require("ioredis");

const conn = new Redis({
    sentinels: [
        { host: "<FQDN of Redis host 1>", port: 26379 },
        ...
        { host: "<FQDN of Redis host N>", port: 26379 },
    ],
    name: "<Redis cluster name>",
    password: "<password>"
});

conn.set("foo", "bar", function (err) {
    if (err) {
        console.error(err);
        conn.disconnect();
    }
});

conn.get("foo", function (err, result) {
    if (err) {
        console.error(err);
    } else {
        console.log(result);
    }

    conn.disconnect();
});

Code example for connecting directly to the master:

app.js

"use strict";

const Redis = require("ioredis");

const conn = new Redis({
    host: "c-<cluster ID>.rw.mdb.yandexcloud.net",
    port: 6379,
    password: "<password>"
});

conn.set("foo", "bar", function (err) {
    if (err) {
        console.error(err);
        conn.disconnect();
    }
});

conn.get("foo", function (err, result) {
    if (err) {
        console.error(err);
    } else {
        console.log(result);
    }

    conn.disconnect();
});

app.js

"use strict";

const fs = require("fs");
const Redis = require("ioredis");

const conn = new Redis({
    host: "c-<cluster ID>.rw.mdb.yandexcloud.net",
    port: 6380,
    password: "<password>",
    tls: {
        ca: fs.readFileSync("/home/<home directory>/.redis/YandexCA.crt"),
    }
});

conn.set("foo", "bar", function (err) {
    if (err) {
        console.error(err);
        conn.disconnect();
    }
});

conn.get("foo", function (err, result) {
    if (err) {
        console.error(err);
    } else {
        console.log(result);
    }

    conn.disconnect();
});

Connecting:

node app.js

If the connection to the cluster and the test query are successful, the bar string is output.

PHP

Before connecting, install the dependencies:

sudo apt update && sudo apt install -y php php-dev php-pear && \
    sudo pear channel-discover pear.nrk.io && \
    sudo pear install nrk/Predis

Code example for connecting via Sentinel:

connect.php

<?php
require "Predis/Autoloader.php";
Predis\Autoloader::register();

$sentinels = [
    "<FQDN of Redis host 1>:26379>",
    ...
    "<FQDN of Redis host N>:26379>",
];
$options = [
    "replication" => "sentinel",
    "service" => "<Redis cluster name>",
    "parameters" => [
        "password" => "<password>",
    ],
];

$conn = new Predis\Client($sentinels, $options);

$conn->set("foo", "bar");
var_dump($conn->get("foo"));

$conn->disconnect();
?>

Code example for connecting directly to the master:

connect.php

<?php
require "Predis/Autoloader.php";
Predis\Autoloader::register();

$host = ["c-<cluster ID>.rw.mdb.yandexcloud.net:6379"];
$options = [
    "parameters" => [
        "password" => "<password>",
    ],
];

$conn = new Predis\Client($host, $options);

$conn->set("foo", "bar");
var_dump($conn->get("foo"));

$conn->disconnect();
?>

connect.php

<?php
require "Predis/Autoloader.php";
Predis\Autoloader::register();

$host = ["c-<cluster ID>.rw.mdb.yandexcloud.net:6380"];
$options = [
    "parameters" => [
        "scheme" => "tls",
        "ssl" => [
            "cafile" => "/home/<home directory>/.redis/YandexCA.crt",
            "verify_peer" => true,
            "verify_peer_name" => false,
        ],
        "password" => "<password>",
    ],
];

$conn = new Predis\Client($host, $options);

$conn->set("foo", "bar");
var_dump($conn->get("foo"));

$conn->disconnect();
?>

Connecting:

php connect.php

If the connection to the cluster and the test query are successful, the bar string is output.

Python

Before connecting, install the dependencies:

sudo apt update && sudo apt install -y python3 python3-pip && \
    pip3 install redis

Code example for connecting via Sentinel:

connect.py

from redis.sentinel import Sentinel

sentinels = [
    "<FQDN of Redis host 1>",
    ...
    "<FQDN of Redis host N>"
]
name = "<Redis cluster name>"
pwd = "<password>"

sentinel = Sentinel([(h, 26379) for h in sentinels], socket_timeout=0.1)
master = sentinel.master_for(name, password=pwd)
slave = sentinel.slave_for(name, password=pwd)

master.set("foo", "bar")
print(slave.get("foo"))

Sample code for connecting without an SSL connection directly to the master host:

connect.py

import redis

r = redis.StrictRedis(
    host="c-<cluster ID>.rw.mdb.yandexcloud.net",
    port=6379,
    password="<password>",
)

r.set("foo", "bar")
print(r.get("foo"))

connect.py

import redis

r = redis.StrictRedis(
    host="c-<cluster ID>.rw.mdb.yandexcloud.net",
    port=6380,
    password="<password>",
    ssl=True,
    ssl_ca_certs="/home/<home directory>/.redis/YandexCA.crt",
)

r.set("foo", "bar")
print(r.get("foo"))

Connecting:

python3 connect.py

If the connection to the cluster and the test query are successful, the bar string is output.

Ruby

Before connecting, install the dependencies:

sudo apt update && sudo apt install -y ruby && \
  sudo gem install redis

Code example for connecting via Sentinel:

connect.rb

# coding: utf-8

require 'redis'

SENTINELS = [
  { host: '<FQDN of Redis host 1>', port: 26379 },
  ...
  { host: '<FQDN of Redis host N>', port: 26379 }
]

conn = Redis.new(
  host: '<Redis cluster name>',
  sentinels: SENTINELS,
  role: 'master',
  password: '<password>'
)

conn.set('foo', 'bar')
puts conn.get('foo')

conn.close

Sample code for connecting without an SSL connection directly to the master host:

connect.rb

# coding: utf-8

require 'redis'

conn = Redis.new(
  host: 'c-<cluster ID>.rw.mdb.yandexcloud.net',
  port: 6379,
  password: '<password>'
)

conn.set('foo', 'bar')
puts conn.get('foo')

conn.close

connect.rb

# coding: utf-8

require 'redis'

conn = Redis.new(
  host: 'c-<cluster ID>.rw.mdb.yandexcloud.net',
  port: 6380,
  password: '<password>',
  ssl: true,
  ssl_params: { ca_file: '/home/<home directory>/.redis/YandexCA.crt' },
)

conn.set('foo', 'bar')
puts conn.get('foo')

conn.close

Connecting:

ruby connect.rb

If the connection to the cluster and the test query are successful, the bar string is output.

In this article: