Yandex Cloud
  • Services
  • Solutions
  • Why Yandex Cloud
  • Blog
  • Pricing
  • Documentation
  • Contact us
Get started
Language / Region
Yandex project
© 2023 Yandex.Cloud LLC
Yandex Managed Service for Redis
  • Getting started
  • Step-by-step instructions
    • All instructions
    • Information about existing clusters
    • Creating clusters
    • Changing cluster and database settings
    • Connecting to a database
      • Preparing for connecting
      • Connecting to a non-sharded cluster
      • Connecting to a sharded cluster
    • Stopping and starting clusters
    • Updating a Redis version
    • Managing hosts in a cluster
    • Managing shards
    • Managing backups
    • Switching the master
    • Monitoring the state of clusters and hosts
    • Viewing cluster logs
    • Deleting clusters
  • Tutorials
    • All use cases
    • Storing PHP sessions in Managed Service for Redis
    • Migrating databases to Managed Service for Redis
  • Concepts
    • Relationships between service resources
    • Host classes
    • Network in Managed Service for Redis
    • Sharding
    • Backups
    • Replication and fault tolerance
    • Supported clients
    • Managing memory in Yandex Managed Service for Redis
    • Supported commands in Yandex Managed Service for Redis
    • Quotas and limits
    • Disk types
    • Maintenance
    • Redis settings
  • Access management
  • Pricing policy
    • Current pricing policy
    • Archive
      • Before February 1, 2020
  • API reference
    • Authentication in the API
    • gRPC
      • Overview
      • BackupService
      • ClusterService
      • ResourcePresetService
      • OperationService
    • REST
      • Overview
      • Backup
        • Overview
        • get
        • list
      • Cluster
        • Overview
        • addHosts
        • addShard
        • backup
        • create
        • delete
        • deleteHosts
        • deleteShard
        • get
        • getShard
        • list
        • listBackups
        • listHosts
        • listLogs
        • listOperations
        • listShards
        • move
        • rebalance
        • rescheduleMaintenance
        • restore
        • start
        • startFailover
        • stop
        • streamLogs
        • update
        • updateHosts
      • ResourcePreset
        • Overview
        • get
        • list
      • Operation
        • Overview
        • get
  • Revision history
  • Questions and answers
    • General questions
  1. Step-by-step instructions
  2. Connecting to a database
  3. Connecting to a sharded cluster

Connecting to a sharded Redis cluster

Written by
Yandex Cloud
  • Connecting to cluster hosts from graphical IDEs
  • Sample connection strings
    • Bash
    • Go
    • Java
    • Node.js
    • PHP
    • Python
    • Ruby

To connect to a sharded Redis cluster, in connection strings, specify the IP addresses or FQDNs of master hosts in each shard.

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.

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.

DBeaver

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: Specify comma-separated FQDNs of master hosts in each shard.
      • 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 the 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

Connecting without using SSL
Connecting via SSL

Before connecting, install the dependencies:

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

Connecting directly to the master host:

Specify the FQDN of the master host in the desired shard:

redis-cli \
    -c \
    -h <FQDN of master host in desired shard> \
    -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:

Specify the FQDN of the master host in the desired shard:

redis-cli \
    -c \
    -h <FQDN of master host in desired shard> \
    -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 GET request returns nil, it means that the entry for the foo key has been moved to another shard. Connect to it and repeat the request: it will return the value bar.

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
Connecting without using SSL
Connecting via SSL

connect.go

package main

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

func main() {
	hostports := []string{
		"<FQDN of the master host in shard 1>:6379",
		...
		"<FQDN of the master host in shard N>:6379",
	}
	options := redis.UniversalOptions{
		Addrs:       hostports,
		DB:          0,
		ReadOnly:    false,
		DialTimeout: 5 * time.Second,
		Password:    "<password>",
	}
	client := redis.NewUniversalClient(&options)

	err := client.Set("foo", "bar", 0).Err()
	if err != nil {
		panic(err)
	}

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

	client.Close()
}

connect.go

package main

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

func main() {
	caCert, err := ioutil.ReadFile("/home/<home directory>/.redis/YandexCA.crt")
	if err != nil {
		panic(err)
	}
	caCertPool := x509.NewCertPool()
	caCertPool.AppendCertsFromPEM(caCert)

	hostports := []string{
		"<FQDN of the master host in shard 1>:6380",
		...
		"<FQDN of the master host in shard N>:6380",
	}
	options := redis.UniversalOptions{
		Addrs:        hostports,
		MaxRedirects: 1,
		Password:     "<password>",
		DB:           0,
		ReadOnly:     false,
		DialTimeout:  5 * time.Second,
		TLSConfig: &tls.Config{
			RootCAs:            caCertPool,
			InsecureSkipVerify: true,
			VerifyPeerCertificate: func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error {
				certs := make([]*x509.Certificate, len(rawCerts))
				for i := 0; i < len(rawCerts); i++ {
					cert, err := x509.ParseCertificate(rawCerts[i])
					if err != nil {
						return fmt.Errorf("error parsing certificate: %+v", err)
					}
					certs[i] = cert
				}

				opts := x509.VerifyOptions{
					Roots:         caCertPool,
					CurrentTime:   time.Now(),
					DNSName:       "",
					Intermediates: x509.NewCertPool(),
				}

				for i := range certs {
					if i == 0 {
						continue
					}
					opts.Intermediates.AddCert(certs[i])
				}
				_, err := certs[0].Verify(opts)
				return err
			},
		},
	}
	options.Dialer = func(ctx context.Context, network, addr string) (net.Conn, error) {
		parts := strings.Split(addr, ":")
		newAddr := addr
		if len(parts) > 1 && !strings.HasPrefix(parts[0], "[") {
			newAddr = "[" + strings.Join(parts[:len(parts)-1], ":") + "]:" + parts[len(parts)-1]
		}

		netDialer := &net.Dialer{
			Timeout:   options.DialTimeout,
			KeepAlive: 5 * time.Minute,
		}
		return tls.DialWithDialer(netDialer, network, newAddr, options.TLSConfig)
	}
	client := redis.NewUniversalClient(&options)
	err = client.Set("foo", "bar", 0).Err()
	if err != nil {
		panic(err)
	}

	get := client.Get("foo")
	if get.Err() != nil {
		panic(err)
	}
	fmt.Println(get.String())
}

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:

    • jedis
    • slf4j-simple
  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
      
Connecting without using SSL
Connecting via SSL

src/java/com/example/App.java

package com.example;

import java.util.HashSet;
import redis.clients.jedis.HostAndPort;
import redis.clients.jedis.JedisCluster;
import redis.clients.jedis.JedisPoolConfig;

public class App {
  public static void main(String[] args) {
    JedisPoolConfig jedisPoolConfig = new JedisPoolConfig();

    HashSet<HostAndPort> jedisClusterNodes = new HashSet<HostAndPort>();
    jedisClusterNodes.add(new HostAndPort("<FQDN of the master host in shard 1>", 6379));
    ...
    jedisClusterNodes.add(new HostAndPort("<FQDN of the master host in shard N>", 6379));

    DefaultJedisClientConfig jedisClientConfig = DefaultJedisClientConfig.builder().
            password("<password>").
            build();

    try {
      JedisCluster jc = new JedisCluster(jedisClusterNodes, jedisClientConfig, 5, jedisPoolConfig);

      jc.set("foo", "bar");
      System.out.println(jc.get("foo"));
      jc.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.JedisCluster;
import redis.clients.jedis.JedisPoolConfig;

import javax.net.ssl.SSLParameters;
import java.util.HashSet;
import java.util.Set;

public class App {
  public static void main(String[] args) {
    System.setProperty("javax.net.ssl.trustStore", "/home/<home directory>/.redis/YATrustStore");
    System.setProperty("javax.net.ssl.trustStorePassword", "<password of secure certificate storage>");

    JedisPoolConfig jedisPoolConfig = new JedisPoolConfig();
    Set<HostAndPort> jedisClusterNodes = new HashSet<HostAndPort>();
    SSLParameters sslParameters = new SSLParameters();
    jedisClusterNodes.add(new HostAndPort("<FQDN of the master host in shard 1>", 6380));
    ...
    jedisClusterNodes.add(new HostAndPort("<FQDN of the master host in shard N>", 6380));

    DefaultJedisClientConfig jedisClientConfig = DefaultJedisClientConfig.builder().
            password("<cluster password>").
            ssl(true).
            sslParameters(sslParameters).
            build();

    try {
      JedisCluster jc = new JedisCluster(jedisClusterNodes, jedisClientConfig, 5, jedisPoolConfig);

      jc.set("foo", "bar");
      System.out.println(jc.get("foo"));
      jc.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
Connecting without using SSL
Connecting via SSL

app.js

"use strict";

const Redis = require("ioredis");

const cluster = new Redis.Cluster(
    [
        {
            host: "<FQDN of the master host in shard 1>",
            port: 6379
        },
        ...
        {
            host: "<FQDN of the master host in shard N>",
            port: 6379
        }
    ],
    {
        redisOptions: {
            password: "<password>"
        }
    }
);

cluster.on("ready", () => {
    Promise.all([
        cluster.set("foo", "bar"),
        cluster.get("foo")
    ]).then(
        (result) => {
            console.log(result[1]); // result == ["OK", "bar"]
            cluster.disconnect();
        },
        (reject) => {
            console.log(reject);
            cluster.disconnect();
        }
    );
});

app.js

"use strict";

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

const cluster = new Redis.Cluster(
    [
        {
            host: "<FQDN of the master host in shard 1>",
            port: 6380
        },
        ...
        {
            host: "<FQDN of the master host in shard N>",
            port: 6380
        },
    ],
    {
        redisOptions: {
            password: "<password>",
            tls: {
                ca: [fs.readFileSync("/home/<home directory>/.redis/YandexCA.crt")],
                checkServerIdentity: () => {
                    return null;
                }
            }
        }
    }
);

cluster.on("ready", () => {
    Promise.all([
        cluster.set("foo", "bar"),
        cluster.get("foo")
    ]).then(
        (result) => {
            console.log(result[1]); // result == [ "OK", "bar"]
            cluster.disconnect();
        },
        (reject) => {
             console.log(reject);
             cluster.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
Connecting without using SSL
Connecting via SSL

connect.php

<?php

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

$hosts = [
    "tcp://<FQDN of the master host in shard 1>:6379",
    ...
    "tcp://<FQDN of the master host in shard N>:6379",
];

$options = [
    "cluster" => "redis",
    "parameters" => [
        "password" => "<password>",
    ],
];

$conn = new Predis\Client($hosts, $options);
$conn->set("foo", "bar");

var_dump($conn->get("foo"));

$conn->disconnect();
?>

connect.php

 <?php

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

 $hosts = [
     'tls://<FQDN of the master host in shard 1>:6380?ssl[cafile]=/home/<home directory>/.redis/YandexCA.crt',
     ...
     'tls://<FQDN of the master host in shard N>:6380?ssl[cafile]=/home/<home directory>/.redis/YandexCA.crt',
 ];

 $options = [
     'cluster' => 'predis',
     'parameters' => [
         'password' => '<password>',
     ],
 ];

 $conn = new Predis\Client($hosts, $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 python3-venv && \
    python3 -m venv env && \
    source env/bin/activate && \
    pip install pip -U && \
    pip install pyopenssl redis-py-cluster setuptools_rust
Connecting without using SSL
Connecting via SSL

connect.py

from rediscluster import RedisCluster

startup_nodes = [
    {"host": "<FQDN of the master host in shard 1>", "port": 6379},
    ...
    {"host": "<FQDN of the master host in shard N>", "port": 6379},
]

rc = RedisCluster(
    startup_nodes=startup_nodes,
    decode_responses=True,
    skip_full_coverage_check=True,
    password="<password>",
)

rc.set("foo", "bar")

print(rc.get("foo"))

connect.py

import OpenSSL
from rediscluster import RedisCluster

startup_nodes = [
    {"host": "<FQDN of the master host in shard 1>", "port": 6380},
    ...
    {"host": "<FQDN of the master host in shard N>", "port": 6380},
]

rc = RedisCluster(
    startup_nodes=startup_nodes,
    decode_responses=True,
    skip_full_coverage_check=True,
    password="<password>",
    ssl=True,
    ssl_ca_certs="/home/<home directory>/.redis/YandexCA.crt",
)

rc.set("foo", "bar")

print(rc.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
Connecting without using SSL
Connecting via SSL

connect.rb

# coding: utf-8

require 'redis'

nodes = [
  { host: '<FQDN of the master host in shard 1>', port: 6379 },
  ...
  { host: '<FQDN of the master host in shard N>', port: 6379 }
]

conn = Redis.new(
   cluster: nodes,
   password: '<password>'
)

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

conn.close

connect.rb

# coding: utf-8

require 'redis'

nodes = [
  { host: '<FQDN of the master host in shard 1>', port: 6380 },
  ...
  { host: '<FQDN of the master host in shard N>', port: 6380 }
]

conn = Redis.new(
  cluster: nodes,
  password: '<password>',
  ssl: true,
  ssl_params: {
    ca_file: '/home/<home directory>/.redis/YandexCA.crt',
    verify_hostname: false
  }
)

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.

Was the article helpful?

Language / Region
Yandex project
© 2023 Yandex.Cloud LLC
In this article:
  • Connecting to cluster hosts from graphical IDEs
  • Sample connection strings
  • Bash
  • Go
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby