You can connect to an ApsaraDB for Redis instance by using clients for different programming languages.

Redis client

The database service of ApsaraDB for Redis is compatible with that of native Redis. Therefore, you can connect to both database services in similar ways. All clients that are compatible with the Redis protocol support connections to ApsaraDB for Redis. You can use any of these clients that are suitable for your applications.

Notice
  • If you enable password-free access for instances in the same Virtual Private Cloud (VPC) network, you can connect to databases of the ApsaraDB for Redis instance without using passwords.
  • For more information about connection issues, see Troubleshooting for connection issues in ApsaraDB for Redis.

For more information about Redis clients, visit https://redis.io/clients.

Prerequisites

  • The internal IP address of the Elastic Compute Service (ECS) instance or the public IP address of the on-premises host is added to an IP address whitelist of the ApsaraDB for Redis instance. For more information, see Set IP address whitelists.
  • If you use a custom account to connect to the ApsaraDB for Redis instance, the connection string must be in the format of <user>:<password>. For example, if the username of the custom account is admin and the password is Rp829dlwa, admin:Rp829dlwa is used to log on to the instance.

Jedis client

You can use a Jedis client to connect to ApsaraDB for Redis in any of the following ways:

  • Single Jedis connection. This method is not recommended because a client cannot automatically reconnect to ApsaraDB for Redis after a connection times out.
  • JedisPool-based connection. This method is recommended.

To use a Jedis client to connect to an ApsaraDB for Redis instance, perform the following steps:

  1. Download and install the Jedis client. For more information, see Jedis.
  2. Example of single Jedis connection
    1. Open the Eclipse client, create a project, and then enter the following code: 
      import redis.clients.jedis.Jedis;
public class jedistest {
public static void main(String[] args) {
try {
     String host = "xx.kvstore.aliyuncs.com";//You can view the connection address of the target instance 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);
     //Set 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();
 }
}
}
    2. Run the project. You have connected to ApsaraDB for Redis if you see the following result in the Eclipse console. 
      Set Key redis Value aliyun-redis
Get Key redis ReturnValue aliyun-redis

      Then, you can use a Jedis client to manage your ApsaraDB for Redis instance. You can also connect to your ApsaraDB for Redis instance by using JedisPool.

  3. Example of JedisPool-based connection
    1. Open 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. Add the following application to the project: 
      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. If your Jedis client version is Jedis-2.7.2, enter the following code in the project: 
      JedisPoolConfig config = new JedisPoolConfig();
//Maximum number of idle connections. You can customize 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 customize 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();
    4. If your Jedis client version is Jedis-2.6 or Jedis-2.5, enter the following code in the project: 
      JedisPoolConfig config = new JedisPoolConfig();
//Maximum number of idle connections. You can customize 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 customize 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);
 }
}
    5. Run the project. You have connected to ApsaraDB for Redis if you see the following result in the Eclipse console. 
      Set Key redis Value aliyun-redis
Get Key redis ReturnValue aliyun-redis

      Then, you can use a Jedis client to manage your ApsaraDB for Redis instance.

Lettuce client

A Lettuce client supports synchronous and asynchronous communication based on comprehensive Redis API operations. A 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 database nodes, connection timeout may occur. This may result in the failure to reconnect to ApsaraDB for Redis. To avoid such risks, we recommend that you use Jedis clients. For more information, see Jedis client.

For more information about Lettuce clients, see Lettuce.

TairJedis client

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

For more information, see TairJedis on GitHub.

PhpRedis client

To use a PhpRedis client to connect to an ApsaraDB for Redis instance, perform the following steps:

  1. Download and install the PhpRedis client. For more information, see PhpRedis.
  2. In an editor that supports PHP editing, enter the following code: 
    <? php
 /* Replace the following parameter values with the host name and port number of the target instance. */
 $host = "localhost";
 $port = 6379;
 /* Replace the following parameter values with the ID and password of the target 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 perform database operations after 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 code. Then, you can use a PhpRedis client to connect to your ApsaraDB for Redis instance. For more information, visit https://github.com/phpredis/phpredis.

Redis-py client

To use a redis-py client to connect to an ApsaraDB for Redis instance, perform the following steps:

  1. Download and install the redis-py client. For more information, see redis-py.
  2. In an editor that supports Python editing, enter the following code. You can use a redis-py client to connect to the ApsaraDB for Redis instance and perform database operations. 
#! /usr/bin/env python
#-*- coding: utf-8 -*-
import redis
#Replace the following parameter values with the host name and port number of the target instance.
host = 'localhost'
port = 6379
#Replace the following parameter value with the password of the target 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')

C or C++ client

To use a C or C++ client to connect to an ApsaraDB for Redis instance, perform the following steps:

  1. Download, compile, and install the C client by using the following code: 
         git clone https://github.com/redis/hiredis.git
     cd hiredis
     make 
     sudo make install
  2. Enter the following code in the C or C++ editor: 
         #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. Run a test. 
     example xxx.kvstore.aliyuncs.com 6379 instance_id password

Now, the C or C++ client is connected to the ApsaraDB for Redis instance.

.NET client

To use a .NET client to connect to an ApsaraDB for Redis instance, perform the following steps:

  1. Download and use the .NET client. 
     git clone https://github.com/ServiceStack/ServiceStack.Redis
  2. Create a .NET project on the .NET client.
  3. Add the reference file stored in the library file directory ServiceStack.Redis/lib/tests to the client.
  4. Enter the following code in the .NET project to connect to the ApsaraDB for Redis instance. For more information about API operations, visit https://github.com/ServiceStack/ServiceStack.Redis. 
    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";/*IP address of the host that you want to connect to*/
         string password = "password";/*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@IP address that you want to connect to:Port*/
 };
 RedisConfig.VerifyMasterConnections = false;//You must set the parameter.
 PooledRedisClientManager redisPoolManager = new PooledRedisClientManager(10/*Number of connections in the pool*/, 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

To use a node-redis client to connect to an ApsaraDB for Redis instance, perform the following steps:

  1. Download and install a node-redis client. 
    npm install hiredis redis
  2. Enter and run the following code on the node-redis client to connect to the ApsaraDB for Redis instance. 
     var redis = require("redis"),
 client = redis.createClient(<port>, <"host">, {detect_buffers: true});
 client.auth("password", redis.print)
    Note In the code, the port field specifies the port of the ApsaraDB for Redis instance. Default value: 6379. The host field specifies the endpoint of the ApsaraDB for Redis instance. The following example shows the settings of the port and host fields: 
    client = redis.createClient(6379, "r-abcdefg.redis.rds.aliyuncs.com", {detect_buffers: true});
  3. Use the ApsaraDB for Redis instance. 
       // Write data to the instance.
 client.set("key", "OK");
 // Query data on the instance. The instance returns data of the String type.
 client.get("key", function (err, reply) {
 console.log(reply.toString()); // print `OK`
 });
 // If a buffer is imported, a buffer is returned.
 client.get(new Buffer("key"), function (err, reply) {
 console.log(reply.toString()); // print `<Buffer 4f 4b>`
 });
 client.quit();

C# client StackExchange.Redis

To use the C# client StackExchange.Redis to connect to an ApsaraDB for Redis instance, perform the following steps:

  1. Download and install StackExchange. Redis.
  2. Add a reference. 
    using StackExchange.Redis;
  3. Initialize ConnectionMultiplexer.

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

     // 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;
 }
    Note

    ConfigurationOptions contains multiple options, such as keepAlive, connectRetry, and name. For more information, see StackExchange.Redis.ConfigurationOptions.

  4. GetDatabase() returns a lightweight object. You can obtain this object from the object of ConnectionMultiplexer. 
     redisConn = getRedisConn();
 var db = redisConn.GetDatabase();
  5. The following examples show five types of data structures, which are strings, hashes, lists, sets, and sorted sets. The API operations used in these examples are different from their usage in the native Redis service.

    • 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();