ApsaraDB for Redis is compatible with open source Redis. You can connect to ApsaraDB for Redis and open source Redis in similar ways. Therefore, you can use a client that is compatible with the Redis protocols to connect to ApsaraDB for Redis. You can connect to an ApsaraDB for Redis instance by using clients of different programming languages.

Prerequisites

Perform the following operations based on the type of host on which the client is deployed.
Host on which the client is deployed Operation
ECS instance (recommended)
  1. Make sure that the ECS instance and the ApsaraDB for Redis instance belong to the same virtual private cloud (VPC). The instances display the same VPC ID in the Basic Information section.
    Note
    • If the ECS instances are deployed in different VPCs, you can change the VPC to which the ECS instance belongs. For more information, see Change the VPC of an ECS instance.
    • The network types of the ECS instance and the ApsaraDB for Redis instance are different. For example, the ECS instance belongs to a classic network and the ApsaraDB for Redis instance belongs to a VPC. For more information about how to connect to an ApsaraDB for Redis instance from an ECS instance when the instances are deployed in different network types, see Connect an ECS instance to an ApsaraDB for Redis instance in different types of networks.
  2. Obtain the internal IP address of the ECS instance. For more information, see How do I query the IP addresses of ECS instances?
  3. Add the internal IP address of the ECS instance to the whitelist of the ApsaraDB for Redis instance. For more information, see Configure an IP whitelist.
On-premises machine
  1. By default, an ApsaraDB for Redis instance provides only an internal endpoint. If you want to connect to an ApsaraDB for Redis instance over the Internet, you must apply for a public endpoint. For more information, see Apply for a public endpoint.
  2. Run the curl ipinfo.io |grep ip command on the on-premises machine on which the client is deployed to obtain the public IP address of the on-premises machine. The returned result is shown in the following figure.View the public IP address of the on-premises machine
    Note If the on-premises machine runs a Windows operating system, go to ipinfo to obtain the public IP address.
  3. Add the public IP address of the on-premises machine to the whitelist of the ApsaraDB for Redis instance. For more information, see Configure an IP whitelist.

Precautions

  • By default, cluster or read/write splitting instances use the proxy mode. In this mode, you can access ApsaraDB for Redis instances by using the endpoint of the proxy server in the same way that you access standard instances of ApsaraDB for Redis.
    Note If you use a private endpoint to connect to an ApsaraDB for Redis instance, you can connect to the instance in the same way that you connect to an open source Redis cluster.
  • If password-free access for VPCs is enabled for an instance, the client in the same VPC can connect to the ApsaraDB for Redis instance without the password.

Obtain connection information

When you use a client to connect to an ApsaraDB for Redis instance, you must obtain the following information and specify the information in the code:

Information Description
Instance endpoint ApsaraDB for Redis instances support multiple types of endpoints. We recommend that you use internal endpoints in a VPC for higher security and lower network latency. For more information, see View endpoints.
Port number The default port number is 6379. You can use a custom port number. For more information, see Modify endpoints.
The account of the instance. This parameter is not required by some clients. By default, an ApsaraDB for Redis instance contains a database account that is named after the instance ID, for example, r-bp10noxlhcoim2****. You can create an account and grant required permissions. For more information, see Create and manage database accounts.
The password of the account.

The password format varies based on the selected account:

  • Default account (the account named after the instance ID): Enter only the password.
  • New account: The format of the password must be <user>:<password>. For example, if the username of a custom account is testaccount and the password is Rp829dlwa, you must enter testaccount:Rp829dlwa.
Note If you forget your password, see Change or reset the password.

Commonly used clients

For the list of clients supported by Redis, see Redis clients.

Jedis client

  1. Download and install the Jedis client. For more information, see Jedis.
  2. Select a connection method based on your business requirements.
    • JedisPool-based connection. This connection method is recommended.
      1. Launch the Eclipse client, create a project, and then configure the following pom file:
        <dependency>
        <groupId>redis.clients</groupId>
        <artifactId>jedis</artifactId>
        <version>2.7.2</version>
        <type>jar</type>
        <scope>compile</scope>
        </dependency>
      2. Enter the following code in the project to add the related applications:
        import org.apache.commons.pool2.PooledObject;
        import org.apache.commons.pool2.PooledObjectFactory;
        import org.apache.commons.pool2.impl.DefaultPooledObject;
        import org.apache.commons.pool2.impl.GenericObjectPoolConfig;
        import redis.clients.jedis.HostAndPort;
        import redis.clients.jedis.Jedis;
        import redis.clients.jedis.JedisPool;
        import redis.clients.jedis.JedisPoolConfig;
      3. Enter the following code in the project based on the Jedis client version, and then modify the code based on the comments.
        Note For more information about how to obtain the connection endpoint and password of the ApsaraDB for Redis instance, see Obtain connection information.
        • Jedis 2.7.2
          JedisPoolConfig config = new JedisPoolConfig();
          //Maximum number of idle connections. You can set this parameter. Make sure that the specified maximum number of idle connections does not exceed the maximum number of connections that the ApsaraDB for Redis instance supports.
          config.setMaxIdle(200);
          //Maximum number of connections. You can set this parameter. Make sure that the specified maximum number of connections does not exceed the maximum number of connections that the ApsaraDB for Redis instance supports.
          config.setMaxTotal(300);
          config.setTestOnBorrow(false);
          config.setTestOnReturn(false);
          String host = "*.aliyuncs.com";
          String password = "Password";
          JedisPool pool = new JedisPool(config, host, 6379, 3000, password);
          Jedis jedis = null;
          try {
          jedis = pool.getResource();
          /// ... do stuff here ... for example
          jedis.set("foo", "bar");
          String foobar = jedis.get("foo");
          jedis.zadd("sose", 0, "car");
          jedis.zadd("sose", 0, "bike");
          Set<String> sose = jedis.zrange("sose", 0, -1);
          } finally {
          if (jedis != null) {
          jedis.close();
          }
          }
          /// ... when closing your application:
          pool.destroy();
        • Jedis 2.6 or Jedis 2.5
          JedisPoolConfig config = new JedisPoolConfig();
          //Maximum number of idle connections. You can set this parameter. Make sure that the specified maximum number of idle connections does not exceed the maximum number of connections that the ApsaraDB for Redis instance supports.
          config.setMaxIdle(200);
          //Maximum number of connections. You can set this parameter. Make sure that the specified maximum number of connections does not exceed the maximum number of connections that the ApsaraDB for Redis instance supports.
          config.setMaxTotal(300);
          config.setTestOnBorrow(false);
          config.setTestOnReturn(false);
          String host = "*.aliyuncs.com";
          String password = "Password";
          JedisPool pool = new JedisPool(config, host, 6379, 3000, password);
          Jedis jedis = null;
          boolean broken = false;
          try {
               jedis = pool.getResource();
               /// ... do stuff here ... for example
               jedis.set("foo", "bar");
               String foobar = jedis.get("foo");
               jedis.zadd("sose", 0, "car");
               jedis.zadd("sose", 0, "bike");
               Set<String> sose = jedis.zrange("sose", 0, -1);
          } 
          catch(Exception e)
          {
               broken = true;
          } finally {
          if (broken) {
               pool.returnBrokenResource(jedis);
          } else if (jedis != null) {
               pool.returnResource(jedis);
           }
          }
    • Single Jedis connection. This connection method is not recommended because a client cannot automatically reconnect to the ApsaraDB for Redis instance after a connection times out.

      Launch the Eclipse client, create a project, enter the following code, and then modify the code based on the comments.

      Note For more information about how to obtain the connection endpoint and password of the ApsaraDB for Redis instance, see Obtain connection information.
      import redis.clients.jedis.Jedis;
      public class jedistest {
      public static void main(String[] args) {
      try {
           String host = "xx.kvstore.aliyuncs.com";//You can find the connection address in the console.
           int port = 6379;
           Jedis jedis = new Jedis(host, port);
           //Authentication information.
           jedis.auth("password");//password
           String key = "redis";
           String value = "aliyun-redis";
           //Select a database. Default value: 0.
           jedis.select(1);
           //Specify a key.
           jedis.set(key, value);
           System.out.println("Set Key " + key + " Value: " + value);
           //Obtain the configured key and value.
           String getvalue = jedis.get(key);
           System.out.println("Get Key " + key + " ReturnValue: " + getvalue);
           jedis.quit();
           jedis.close();
      } 
      catch (Exception e) {
       e.printStackTrace();
       }
      }
      }
  3. Run the project. If Eclipse returns the following result, it indicates that the client is connected to the ApsaraDB for Redis instance.
    Set Key redis Value aliyun-redis
    Get Key redis ReturnValue aliyun-redis
Warning If some invalid parameters are set or some features are not properly used, errors may occur. For more information about how to troubleshoot errors, see Jedis common exceptions.

Lettuce client

The Lettuce client supports synchronous and asynchronous communication based on comprehensive Redis API operations. The Lettuce client does not automatically reconnect to an instance after multiple requests time out. If failures occur in ApsaraDB for Redis and cause failovers for proxy servers or data nodes, a connection timeout may occur. This may result in the failure to reconnect to ApsaraDB for Redis. To avoid these risks, we recommend that you use Jedis client.

Note For more information about how to obtain the connection endpoint and password of the ApsaraDB for Redis instance, see Obtain connection information.

For more information, see Lettuce.

TairJedis client

TairJedis is an ApsaraDB for Redis client that is developed by Alibaba Cloud. TairJedis supports the features of Jedis and ApsaraDB for Redis Enhanced Edition (Tair). For example, TairJedis supports the Tair structures and Tair commands.

Note For more information about how to obtain the connection endpoint and password of the ApsaraDB for Redis instance, see Obtain connection information.

For more information, see tairjedis-sdk.

PhpRedis client

  1. Download and install the PhpRedis client. For more information, see PhpRedis.
  2. Enter the following code in a PHP editor and modify the code based on the comments.
    Note For more information about how to obtain the connection address, account, and password of the ApsaraDB for Redis instance, see Obtain connection information.
    <?php
     /* Replace the parameter values with the endpoint and port number of the instance. */
     $host = "r-bp10noxlhcoim2****.redis.rds.aliyuncs.com";
     $port = 6379;
     /* Replace the following parameter values with the ID and password of the instance. */
     $user = "test_username";
     $pwd = "test_password";
     $redis = new Redis();
     if ($redis->connect($host, $port) == false) {
             die($redis->getLastError());
       }
     if ($redis->auth($pwd) == false) {
             die($redis->getLastError());
      }
      /* You can manage the database after you pass the authentication. For more information, visit https://github.com/phpRedis/phpredis. */
     if ($redis->set("foo", "bar") == false) {
             die($redis->getLastError());
     }
     $value = $redis->get("foo");
     echo $value;
     ?>
  3. Run the preceding code to connect to the ApsaraDB for Redis instance.
    For more information, see PhpRedis.
Note If the client program prompts the Cannot assign requested address error message, see The "Cannot assign requested address" error occurs when short-lived connections are used to access ApsaraDB for Redis to locate causes and find solutions to the issue.

Redis-py client

  1. Download and install the redis-py client. For more information, see redis-py.
  2. Enter the following code in a Python editor and modify the code based on the comments (Python 2).
    Note For more information about how to obtain the connection endpoint and password of the ApsaraDB for Redis instance, see Obtain connection information.
    #!/usr/bin/env python
    #-*- coding: utf-8 -*-
    import redis
    #Replace the value of the host parameter with the endpoint of the instance, and replace the value of the port parameter with the port number.
    host = 'localhost'
    port = 6379
    #Replace the following parameter value with the password of the instance.
    pwd = 'test_password'
    r = redis.StrictRedis(host=host, port=port, password=pwd)
    #You can perform database operations after you establish a connection. For more information, visit https://github.com/andymccurdy/redis-py.
    r.set('foo', 'bar');
    print r.get('foo')
  3. Run the preceding code to connect to the ApsaraDB for Redis instance.

C or C++ client

  1. Run the following commands to download, compile, and install the C client:
    git clone https://github.com/redis/hiredis.git
    cd hiredis
    make
    sudo make install
  2. Enter the following code in a C or C ++ editor and modify the code based on the comments.
    Note For more information about how to obtain the connection endpoint and password of the ApsaraDB for Redis instance, see Obtain connection information.
    #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 xxx.kvstore.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 ApsaraDB for Redis instance.
     example xxx.kvstore.aliyuncs.com 6379 instance_id password

.NET client

Warning If you need to switch or select a database from multiple databases in a cluster instance or read/write splitting instance, you must set the cluster_compat_enable parameter to 0 and restart the client application. This disables the support for the cluster syntax of open source Redis. Otherwise, the system sends the following error message: Multiple databases are not supported on this server; cannot switch to database. For more information, see Parameters overview.
  1. Run the following command to download the .NET client.
     git clone https://github.com/ServiceStack/ServiceStack.Redis
  2. Create a .NET project on the .NET client.
  3. Add a reference. The reference file is stored in the library file directory ServiceStack.Redis/lib/tests.
  4. Enter the following code in the .NET project and modify the code based on the comments. For more information, see ServiceStack.Redis.
    Note For more information about how to obtain the connection endpoint and password of the ApsaraDB for Redis instance, see Obtain connection information.
    using System;
     using System.Collections.Generic;
     using System.Linq;
     using System.Text;
     using System.Threading.Tasks;
     using ServiceStack.Redis;
     namespace ServiceStack.Redis.Tests
     {
             class Program
     {
     public static void RedisClientTest()
     {
             string host = "127.0.0.1";/*The endpoint of the host.*/
             string password = "password";/*The password*/
             RedisClient redisClient = new RedisClient(host, 6379, password);
             string key = "test-aliyun";
             string value = "test-aliyun-value";
             redisClient.Set(key, value);
             string listKey = "test-aliyun-list";
             System.Console.WriteLine("set key " + key + " value " + value);
             string getValue = System.Text.Encoding.Default.GetString(redisClient.Get(key));
             System.Console.WriteLine("get key " + getValue);
             System.Console.Read();
     }
     public static void RedisPoolClientTest()
     {
             string[] testReadWriteHosts = new[] {
             "redis://password@127.0.0.1:6379"/* redis://password@endpoint:port */
     };
     RedisConfig.VerifyMasterConnections = false;//Required.
     PooledRedisClientManager redisPoolManager = new PooledRedisClientManager(10/*Number of connection pools*/, 10/*Connection pool timeout value*/, testReadWriteHosts);
     for (int i = 0; i < 100; i++){
             IRedisClient redisClient = redisPoolManager.GetClient();//Obtain the connection.
             RedisNativeClient redisNativeClient = (RedisNativeClient)redisClient;
             redisNativeClient.Client = null;//ApsaraDB for Redis does not support the CLIENT SETNAME command. Set Client to null.
     try
     {
             string key = "test-aliyun1111";
             string value = "test-aliyun-value1111";
             redisClient.Set(key, value);
             string listKey = "test-aliyun-list";
             redisClient.AddItemToList(listKey, value);
             System.Console.WriteLine("set key " + key + " value " + value);
             string getValue = redisClient.GetValue(key);
             System.Console.WriteLine("get key " + getValue);
             redisClient.Dispose();//
     }catch (Exception e)
     {
             System.Console.WriteLine(e.Message);
     }
     }
             System.Console.Read();
     }
     static void Main(string[] args)
     {
             //Single-connection mode.
             RedisClientTest();
             //Connection-pool mode.
             RedisPoolClientTest();
     }
     }
     }

Node-redis client

  1. Download and install the node-redis client.
    npm install hiredis redis
  2. Enter the following code in the node-redis client and modify the code based on the comments.
    Note For more information about how to obtain the connection endpoint and password of the ApsaraDB for Redis instance, see Obtain connection information.
     var redis = require("redis"),
     client = redis.createClient(<port>, <"host">, {detect_buffers: true});
     client.auth("password", redis.print)

    Parameters:

    • <port>: the service port number of the ApsaraDB for Redis database. The default port number is 6379.
    • <"host">: the endpoint of the ApsaraDB for Redis instance.

    Configuration examples:

    var redis = require("redis"),
    client = redis.createClient(6379, "r-abcdefg.redis.rds.aliyuncs.com", {detect_buffers: true});
    client.auth("password", redis.print)
  3. Run the preceding code to connect to the ApsaraDB for Redis instance.
  4. Use ApsaraDB for Redis.
    // Write data to the instance.
     client.set("key", "OK");
     // Query data on the ApsaraDB for Redis instance. The returned data is of the STRING type.
     client.get("key", function (err, reply) {
     console.log(reply.toString()); // print `OK`
     });
     // If the input parameter is a buffer, the returned value is also a buffer.
     client.get(new Buffer("key"), function (err, reply) {
     console.log(reply.toString()); // print `<Buffer 4f 4b>`
     });
     client.quit();

C# client StackExchange.Redis

Warning If you need to switch or select a database from multiple databases in a cluster instance or read/write splitting instance, you must set the cluster_compat_enable parameter to 0 and restart the client application. This disables the support for the cluster syntax of open source Redis. Otherwise, the system sends the following error message: RedisCommandException: Multiple databases are not supported on this server; cannot switch to database: 1. For more information, see Parameters overview.
  1. Download and install the StackExchange.Redis client.
  2. Add a reference.
    using StackExchange.Redis;
  3. Initialize ConnectionMultiplexer.

    ConnectionMultiplexer is the core of StackExchange.Redis and is shared and reused in the entire application. You must use ConnectionMultiplexer as a singleton. ConnectionMultiplexer is initialized in the following method:

    Note
    • For more information about how to obtain the connection endpoint and password of the ApsaraDB for Redis instance, see .
    • ConfigurationOptions contains multiple options, such as keepAlive, connectRetry, and name. For more information, see ConfigurationOptions.
     // redis config
     private static ConfigurationOptions configurationOptions = ConfigurationOptions.Parse("127.0.0.1:6379,password=xxx,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;
     }
  4. GetDatabase() returns a lightweight object. You can obtain this object from the object of ConnectionMultiplexer.
     redisConn = getRedisConn();
     var db = redisConn.GetDatabase();
  5. You can use the client to perform database operations.
    Note The following examples describe the commands for common data types, which are slightly different from the Redis-native commands.
    • String
      //set get
      string strKey = "hello";
      string strValue = "world";
      bool setResult = db.StringSet(strKey, strValue);
      Console.WriteLine("set " + strKey + " " + strValue + ", result is " + setResult);
      //incr
      string counterKey = "counter";
      long counterValue = db.StringIncrement(counterKey);
      Console.WriteLine("incr " + counterKey + ", result is " + counterValue);
      //expire
      db.KeyExpire(strKey, new TimeSpan(0, 0, 5));
      Thread.Sleep(5 * 1000);
      Console.WriteLine("expire " + strKey + ", after 5 seconds, value is " + db.StringGet(strKey));
      //mset mget
      KeyValuePair<RedisKey, RedisValue> kv1 = new KeyValuePair<RedisKey, RedisValue>("key1", "value1");
      KeyValuePair<RedisKey, RedisValue> kv2 = new KeyValuePair<RedisKey, RedisValue>("key2", "value2");
      db.StringSet(new KeyValuePair<RedisKey, RedisValue>[] {kv1,kv2});            
      RedisValue[] values = db.StringGet(new RedisKey[] {kv1.Key, kv2.Key});
      Console.WriteLine("mget " + kv1.Key.ToString() + " " + kv2.Key.ToString() + ", result is " + values[0] + "&&" + values[1]);
    • Hash
      string hashKey = "myhash";
      //hset
      db.HashSet(hashKey,"f1","v1");
      db.HashSet(hashKey,"f2", "v2");
      HashEntry[] values = db.HashGetAll(hashKey);
      //hgetall
      Console.Write("hgetall " + hashKey + ", result is");
      for (int i = 0; i < values.Length;i++) 
      {
        HashEntry hashEntry = values[i];
        Console.Write(" " + hashEntry.Name.ToString() + " " + hashEntry.Value.ToString());
      }
      Console.WriteLine();
    • List
      //list key
      string listKey = "myList";
      //rpush
      db.ListRightPush(listKey, "a");
      db.ListRightPush(listKey, "b");
      db.ListRightPush(listKey, "c");
      //lrange
      RedisValue[] values = db.ListRange(listKey, 0, -1);
      Console.Write("lrange " + listKey + " 0 -1, result is ");
      for (int i = 0; i < values.Length; i++)
      {
       Console.Write(values[i] + " ");
      }
      Console.WriteLine();
    • Set
      //set key
      string setKey = "mySet";
      //sadd
      db.SetAdd(setKey, "a");
      db.SetAdd(setKey, "b");
      db.SetAdd(setKey, "c");
      //sismember
      bool isContains = db.SetContains(setKey, "a");
      Console.WriteLine("set " + setKey + " contains a is " + isContains );
    • Sorted Set
      string sortedSetKey = "myZset";
      //sadd
      db.SortedSetAdd(sortedSetKey, "xiaoming", 85);
      db.SortedSetAdd(sortedSetKey, "xiaohong", 100);
      db.SortedSetAdd(sortedSetKey, "xiaofei", 62);
      db.SortedSetAdd(sortedSetKey, "xiaotang", 73);
      //zrevrangebyscore
      RedisValue[] names = db.SortedSetRangeByRank(sortedSetKey, 0, 2, Order.Ascending);
      Console.Write("zrevrangebyscore " + sortedSetKey + " 0 2, result is ");
      for (int i = 0; i < names.Length; i++)
      {
        Console.Write(names[i] + " ");
      }
      Console.WriteLine();