Connection guide

Spring Data Redis

This example uses Maven for the build. You can also manually download the Lettuce or Jedis client.

1. Create a project in your IDE.

2. Add the following pom file to download Lettuce or Jedis.

   Important

   If you use Lettuce, we recommend that you use 6.3.0.RELEASE or later and configure the TCP_USER_TIMEOUT parameter to prevent blackhole filtering.

   <?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>
       <parent>
           <groupId>org.springframework.boot</groupId>
           <artifactId>spring-boot-starter-parent</artifactId>
           <version>2.4.2</version>
           <relativePath/> <!-- lookup parent from repository -->
       </parent>
       <groupId>com.aliyun.tair</groupId>
       <artifactId>spring-boot-example</artifactId>
       <version>0.0.1-SNAPSHOT</version>
       <name>spring-boot-example</name>
       <description>Demo project for Spring Boot</description>
       <properties>
           <java.version>1.8</java.version>
       </properties>
       <dependencies>
           <dependency>
               <groupId>org.springframework.boot</groupId>
               <artifactId>spring-boot-starter-web</artifactId>
           </dependency>
           <dependency>
               <groupId>org.springframework.boot</groupId>
               <artifactId>spring-boot-starter-test</artifactId>
               <scope>test</scope>
           </dependency>
           <dependency>
               <groupId>org.springframework.boot</groupId>
               <artifactId>spring-boot-starter-data-redis</artifactId>
           </dependency>
           <dependency>
               <groupId>redis.clients</groupId>
               <artifactId>jedis</artifactId>
           </dependency>
           <dependency>
               <groupId>io.lettuce</groupId>
               <artifactId>lettuce-core</artifactId>
               <version>6.3.0.RELEASE</version>
           </dependency>
           <dependency>
               <groupId>io.netty</groupId>
               <artifactId>netty-transport-native-epoll</artifactId>
               <version>4.1.100.Final</version>
               <classifier>linux-x86_64</classifier>
           </dependency>
       </dependencies>
       <build>
           <plugins>
               <plugin>
                   <groupId>org.springframework.boot</groupId>
                   <artifactId>spring-boot-maven-plugin</artifactId>
               </plugin>
           </plugins>
       </build>
   </project>

3. Add the following code and update the values as indicated in the comments.

   In this example, Spring Data Redis 2.4.2 is used.

   • Spring Data Redis with Jedis

     @Configuration
     public class RedisConfig {
         
         @Bean
         JedisConnectionFactory redisConnectionFactory() {
             //This example is only for testing connections. In production environments, we recommend that you store connection information in configuration files and retrieve the information using the @Value annotation.
             //You can obtain the endpoint (hostName) and port number (port) from the Connection Information section of the Instance Information page. Select a VPC or public connection based on your client network environment.
             RedisStandaloneConfiguration config = new RedisStandaloneConfiguration("r-8vbwds91ie1rdl****.redis.zhangbei.rds.aliyuncs.com", 6379);
             //Enter the password in the format of username:password. For example, if the username is testaccount and the password is Rp829dlwa, enter testaccount:Rp829dlwa as the password.
             //If you forget your username or password, click Account Management in the navigation pane on the left of the instance details page to reset the password or create an account.
             config.setPassword(RedisPassword.of("username:password"));
             JedisPoolConfig jedisPoolConfig = new JedisPoolConfig();
             // Specify the maximum number of connections as needed. This value cannot exceed the maximum number of connections supported by the instance type.
             jedisPoolConfig.setMaxTotal(30);
             // Specify the maximum number of idle connections as needed. This value cannot exceed the maximum number of connections supported by the instance type.
             jedisPoolConfig.setMaxIdle(20);
             // Disable testOn[Borrow|Return] to prevent additional PING commands from being generated.
             jedisPoolConfig.setTestOnBorrow(false);
             jedisPoolConfig.setTestOnReturn(false);
     
             JedisClientConfiguration jedisClientConfiguration = JedisClientConfiguration.builder().usePooling().poolConfig(
                     jedisPoolConfig).build();
     
             return new JedisConnectionFactory(config, jedisClientConfiguration);
         }
         @Bean
         public RedisTemplate<String, Object> redisTemplate() {
             RedisTemplate<String, Object> template = new RedisTemplate<>();
             template.setConnectionFactory(redisConnectionFactory());
             template.setKeySerializer(new StringRedisSerializer());
             template.setValueSerializer(new GenericJackson2JsonRedisSerializer());
             return template;
         }
     }

   • Spring Data Redis with Lettuce (including the configuration of the TCP_USER_TIMEOUT parameter)

     @Configuration
     public class BeanConfig {
         /**
          * Enable TCP keepalive and configure the following three parameters:
          * TCP_KEEPIDLE = 30
          * TCP_KEEPINTVL = 10
          * TCP_KEEPCNT = 3
          */
         private static final int TCP_KEEPALIVE_IDLE = 30;
     
         /**
          * The TCP_USER_TIMEOUT parameter can prevent Lettuce from continuously timing out in case of a failure or breakdown.
          * Reference: https://github.com/lettuce-io/lettuce-core/issues/2082
          */
         private static final int TCP_USER_TIMEOUT = 30;
     
         @Bean
         LettuceConnectionFactory redisConnectionFactory() {
             RedisStandaloneConfiguration config = new RedisStandaloneConfiguration();
             config.setHostName("r-bp1y4is8svonly****pd.redis.rds.aliyuncs.com");
             config.setPort(6379);
             config.setUsername("r-bp1y4is8svonly****");
             config.setPassword("Da****3");
     
             // Config TCP KeepAlive
             SocketOptions socketOptions = SocketOptions.builder()
                 .keepAlive(KeepAliveOptions.builder()
                     .enable()
                     .idle(Duration.ofSeconds(TCP_KEEPALIVE_IDLE))
                     .interval(Duration.ofSeconds(TCP_KEEPALIVE_IDLE / 3))
                     .count(3)
                     .build())
                 .tcpUserTimeout(TcpUserTimeoutOptions.builder()
                     .enable()
                     .tcpUserTimeout(Duration.ofSeconds(TCP_USER_TIMEOUT))
                     .build())
                 .build();
             LettuceClientConfiguration lettuceClientConfiguration = LettuceClientConfiguration.builder().clientOptions(
                 ClientOptions.builder().socketOptions(socketOptions).build()).build();
             return new LettuceConnectionFactory(config, lettuceClientConfiguration);
         }
     
         @Bean
         RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory connectionFactory) {
             RedisTemplate<String, Object> template = new RedisTemplate<>();
             template.setConnectionFactory(connectionFactory);
             return template;
         }
     }

Jedis

This example uses Maven for the build. You can also manually download the Jedis client.

1. Create a project in your IDE.

2. Add the following code to the pom.xml file.

   In this example, Jedis 4.3.0 is used.

   <dependency>
       <groupId>redis.clients</groupId>
       <artifactId>jedis</artifactId>
       <version>4.3.0</version>
   </dependency>

3. Add the following code and update the values as indicated in the comments:

   import redis.clients.jedis.Jedis;
   import redis.clients.jedis.JedisPool;
   import redis.clients.jedis.JedisPoolConfig;
   
   public class JedisExample {
       public static void main(String[] args) {
           JedisPoolConfig config = new JedisPoolConfig();
           // Specify the maximum number of idle connections based on your requirements. The value cannot exceed the maximum number of connections supported by the Redis instance.
           config.setMaxIdle(200);
           // Specify the maximum number of connections based on your requirements. The value cannot exceed the maximum number of connections supported by the Redis instance.
           config.setMaxTotal(300);
           config.setTestOnBorrow(false);
           config.setTestOnReturn(false);
           // Replace the values of hostname and password with the endpoint and password of the instance.
           String hostname = "r-bp1s1bt2tlq3p1****pd.redis.rds.aliyuncs.com";
           // For a default account, you can directly enter the password. For a new account, enter the password in the format of user:password. For example, if the new account is testaccount and the password is Rp829dlwa, enter testaccount:Rp829dlwa.
           String password = "r-bp1s1bt2tlq3p1****:Database123";
           JedisPool pool = new JedisPool(config, hostname, 6379, 3000, password);
           Jedis jedis = null;
           try {
               jedis = pool.getResource();
               // Perform related operations. The following code provides an example.
               jedis.set("foo10", "bar");
               System.out.println(jedis.get("foo10"));
               jedis.zadd("sose", 0, "car");
               jedis.zadd("sose", 0, "bike");
               System.out.println(jedis.zrange("sose", 0, -1));
           }
           catch (Exception e) {
               // Handle timeouts or other exceptions.
               e.printStackTrace();
           }
           finally {
               if (jedis != null) {
                   jedis.close();
               }
           }
           pool.destroy();    // When the application exits and resources need to be destroyed, call this method. This method disconnects the connection and releases the resources.
       }
   }

4. Expected output:

   bar
   [bike, car]

redis-py

1. Download and install the redis-py client.

2. Add the following code and update the values as indicated in the comments.

   In this example, Python 3.9 and redis-py 4.4.1 are used.

   #!/usr/bin/env python
   #-*- coding: utf-8 -*-
   import redis
   # Replace the values of hostname and port with the endpoint and port number of the instance.
   hostname = 'r-bp10noxlhcoim2****.redis.rds.aliyuncs.com'
   port = 6379
   # Replace the value of pwd with the password of the instance.
   # For a default account, you can directly enter the password. For a new account, enter the password in the format of user:password. For example, if the new account is testaccount and the password is Rp829dlwa, enter testaccount:Rp829dlwa.
   password = 'testaccount:Rp829dlwa'
   r = redis.Redis(host=hostname, port=port, password=password)
   # After the connection is established, you can perform database operations. The following code provides an example on how to use SET and GET.
   r.set('foo', 'bar')
   print(r.get('foo'))

3. Expected output:

   b'bar'

PhpRedis

1. Download and install the PhpRedis client.

2. Add the following code and update the values as indicated in the comments.

   In this example, PHP 8.2.1 and PhpRedis 5.3.7 are used.

   <?php
    /* Replace the values of hostname and port with the endpoint and port number of the instance. */
    $hostname = "r-bp10noxlhcoim2****.redis.rds.aliyuncs.com";
    $port = 6379;
    /* Replace the values of user and password with the account and password of the instance. */
    $user = "testaccount";
    $password = "Rp829dlwa";
    $redis = new Redis();
    if ($redis->connect($hostname, $port) == false) {
            die($redis->getLastError());
      }
    if ($redis->auth([$user, $password]) == false) {
            die($redis->getLastError());
     }
     /* After authentication, you can perform database operations. The following code provides an example on how to use SET and GET. */
    if ($redis->set("foo", "bar") == false) {
            die($redis->getLastError());
    }
    $value = $redis->get("foo");
    echo $value;
    ?>

3. Run the preceding code.

   Note

   Common errors and solutions:

   • Cannot assign requested address: For information about the cause of and solution to the error, see What do I do if the "Cannot assign requested address" error is returned.

   • redis protocol error, got ' ' as reply type byte: Update the version of your PhpRedis client. For more information, visit GitHub.

C or C++

1. Download and install the C client.

2. Add the following code and update the values as indicated in the comments.

   In this example, hiredis 1.1.0 is used.

   #include <stdio.h>
   #include <stdlib.h>
   #include <string.h>
   #include <hiredis.h>
   int main(int argc, char **argv) {
       unsigned int j;
       redisContext *c;
       redisReply *reply;
       if (argc < 4) {
               printf("Usage: example r-bp10noxlhcoim2****.redis.rds.aliyuncs.com 6379 instance_id password\n");
               exit(0);
       }
       const char *hostname = argv[1];
       const int port = atoi(argv[2]);
       const char *instance_id = argv[3];
       const char *password = argv[4];
       struct timeval timeout = { 1, 500000 }; // 1.5 seconds
       c = redisConnectWithTimeout(hostname, port, timeout);
       if (c == NULL || c->err) {
       if (c) {
               printf("Connection error: %s\n", c->errstr);
               redisFree(c);
       } else {
           printf("Connection error: can't allocate redis context\n");
       }
       exit(1);
       }
       /* AUTH */
       reply = redisCommand(c, "AUTH %s", password);
       printf("AUTH: %s\n", reply->str);
       freeReplyObject(reply);
       /* PING server */
       reply = redisCommand(c,"PING");
       printf("PING: %s\n", reply->str);
       freeReplyObject(reply);
       /* Set a key */
       reply = redisCommand(c,"SET %s %s", "foo", "hello world");
       printf("SET: %s\n", reply->str);
       freeReplyObject(reply);
       /* Set a key using binary safe API */
       reply = redisCommand(c,"SET %b %b", "bar", (size_t) 3, "hello", (size_t) 5);
       printf("SET (binary API): %s\n", reply->str);
       freeReplyObject(reply);
       /* Try a GET and two INCR */
       reply = redisCommand(c,"GET foo");
       printf("GET foo: %s\n", reply->str);
       freeReplyObject(reply);
       reply = redisCommand(c,"INCR counter");
       printf("INCR counter: %lld\n", reply->integer);
       freeReplyObject(reply);
       /* again ... */
       reply = redisCommand(c,"INCR counter");
       printf("INCR counter: %lld\n", reply->integer);
       freeReplyObject(reply);
       /* Create a list of numbers, from 0 to 9 */
       reply = redisCommand(c,"DEL mylist");
       freeReplyObject(reply);
       for (j = 0; j < 10; j++) {
               char buf[64];
               snprintf(buf,64,"%d",j);
               reply = redisCommand(c,"LPUSH mylist element-%s", buf);
               freeReplyObject(reply);
           }
       /* Let's check what we have inside the list */
       reply = redisCommand(c,"LRANGE mylist 0 -1");
       if (reply->type == REDIS_REPLY_ARRAY) {
               for (j = 0; j < reply->elements; j++) {
               printf("%u) %s\n", j, reply->element[j]->str);
       }
       }
       freeReplyObject(reply);
       /* Disconnects and frees the context */
       redisFree(c);
       return 0;
   }

3. Compile the code.

   gcc -o example -g example.c -I /usr/local/include/hiredis -lhiredis

4. Perform a test run and connect to the instance.

    ./example r-bp10noxlhcoim2****.redis.rds.aliyuncs.com 6379 r-bp10noxlhcoim2**** password

.NET

1. Download and install StackExchange.Redis 2.7.20 or later. For more information, see Upgrade StackExchange.Redis to version 2.7.20 or later.

   Important

   We recommend that you do not use the ServiceStack Redis or CSRedis client.

   • If you use ServiceStack Redis and run into issues related to the client, you must purchase technical support from ServiceStack.

   • The support for the CSRedis client has been ended.

2. Add the following code and update the values as indicated in the comments.

   In this example, StackExchange.Redis 2.7.20 is used.

   using StackExchange.Redis;
    // Set the endpoint, port number, and password of the instance.
    private static ConfigurationOptions configurationOptions = ConfigurationOptions.Parse("r-bp10noxlhcoim2****.redis.rds.aliyuncs.com:6379,password=testaccount:Rp829dlwa,connectTimeout=2000");
     //the lock for singleton
    private static readonly object Locker = new object();
     //singleton
    private static ConnectionMultiplexer redisConn;
    //singleton
    public static ConnectionMultiplexer getRedisConn()
    {
        if (redisConn == null)
        {
            lock (Locker)
            {
                if (redisConn == null || !redisConn.IsConnected)
                {
                    redisConn = ConnectionMultiplexer.Connect(configurationOptions);
                }
            }
        }
        return redisConn;
    }

   Note

   • ConfigurationOptions is the core of StackExchange.Redis and should be a singleton shared across the application. For more information about parameter settings, see ConfigurationOptions.

   • The GetDatabase() object is lightweight. Obtain it from ConnectionMultiplexer each time you need it.

      redisConn = getRedisConn();
      var db = redisConn.GetDatabase();

node-redis

1. Download and install the node-redis client.

2. Add the following code and update the values as indicated in the comments.

   In this example, Node.js 19.4.0 and node-redis 4.5.1 are used.

   import { createClient } from 'redis';
   
   // Set the port number, endpoint, account, and password of the instance.
   const hostname = 'r-bp10noxlhcoim2****.redis.rds.aliyuncs.com';
   const port = 6379;
   const username = 'testaccount';
   // If the password contains special characters (!@#$%^&*()+-=_), we recommend that you encode the password using encodeURIComponent: password = encodeURIComponent(password)
   const password = 'Rp829dlwa';
   const client = createClient({
     // redis://[[username]:[password]@[hostname][:port]/[db-number]
     url: `redis://${username}:${password}@${hostname}:${port}/0`
   });
   
   client.on('error', (err) => console.log('Redis Client Error', err));
   
   await client.connect();
   
   await client.set('foo', 'bar');
   const value = await client.get('foo');
   console.log("get foo: %s", value);
   await client.disconnect();

   Note

   If you get a SyntaxError: Cannot use import statement outside a module error, rename the .js file to .mjs and add --experimental-modules when running it. Example: node --experimental-modules redis.mjs.

Go-redis

1. Download and install the Go-Redis client.

2. Add the following code and update the values as indicated in the comments.

   In this example, Go 1.18.5 and Go-redis 8.11.5 are used.

   package main
   
   import (
   	"github.com/go-redis/redis"
   	"fmt"
   )
   
   func ExampleClient() {
   	client := redis.NewClient(&redis.Options{
           // Replace with the endpoint and port of the instance.
   		Addr:     "r-bp10noxlhcoim2****.redis.rds.aliyuncs.com:6379",
           // Replace with the password of the instance.
   		Password: "testaccount:Rp829dlwa",
   		DB:       0,  // use default DB
   	})
       // The following code provides an example on how to use SET and GET.
   	err := client.Set("foo", "bar", 0).Err()
   	if err != nil {
   		panic(err)
   	}
   
   	val, err := client.Get("foo").Result()
   	if err != nil {
   		panic(err)
   	}
   	fmt.Println("set : foo -> ", val)
   }
   
   func main() {
   	ExampleClient()
   }

Lettuce