Use redis-cli to connect to an ApsaraDB for Redis instance - User Guide| Alibaba Cloud Documentation Center

redis-cli is a built-in command line interface (CLI) of native Redis. You can use redis-cli to connect to an ApsaraDB for Redis instance from an Elastic Compute Service (ECS) instance or on-premises device and manage data.

Type of network used to connect to an ApsaraDB for Redis instance


Network type	Description
VPC (recommended)	A virtual private cloud (VPC) is a private network dedicated to your Alibaba Cloud account. VPCs are logically isolated from each other at Layer 2 to provide higher security and performance. When redis-cli is deployed on an ECS instance, you can connect to an ApsaraDB for Redis instance over a VPC to gain higher security and reduce network latency. For more information, see What is ECS?
Internet	If you want to test or manage an ApsaraDB for Redis instance from an on-premises device, you can deploy redis-cli on the device and connect to the ApsaraDB for Redis instance over the Internet. Note You are not charged for traffic generated when you connect to the ApsaraDB for Redis instance over the Internet. However, the connection may be exposed to security risks. We recommend that you use a VPC to improve security.

redis-cli

redis-cli is a built-in CLI of native Redis. You can deploy the tool on an ECS instance or an on-premises device by installing Redis.

Note In addition to redis-cli, you can also use Data Management (DMS) to connect to a database of an ApsaraDB for Redis instance without a client program. DMS provides a graphic user interface for database management. For more information about DMS, see Overview. For more information about how to use DMS to connect to a database of an ApsaraDB for Redis instance, see Use DMS.
The redis-cli version can be different from the major version of the ApsaraDB for Redis instance.

Use redis-cli in Linux

Install redis-cli. Skip this step if it is already installed.
1. Log on to the device on which you want to install redis-cli, such as an ECS instance or an on-premises device.
2. Run the following command to download the Redis source code package:
```
wget https://download.redis.io/releases/redis-6.0.9.tar.gz
```
  Note Redis 6.0.9 is used as an example to demonstrate the operations. You can also install other versions. For more information, see Download.
3. Run the following command to decompress the Redis source code package:
```
tar xzf redis-6.0.9.tar.gz
```
4. Run the following command to go to the directory to which the Redis source code package is decompressed. Compile and install Redis source code.
```
cd redis-6.0.9&&make
```
  Note It takes two or three minutes to compile and install Redis.

Perform the following operations based on the redis-cli installation location:


redis-cli installation location	Operation
ECS instance (recommended)	Make sure that the ECS instance and the ApsaraDB for Redis instance belong to the same VPC. In this case, the same VPC ID is displayed in the Basic Information section of the instances. Note If the 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 may be different. For example, the ECS instance belongs to the 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 types of networks, see Connect an ECS instance to an ApsaraDB for Redis instance in different types of networks. Obtain the internal IP address of the ECS instance. For more information, see Network FAQ. Add the internal IP address of the ECS instance to a whitelist of the ApsaraDB for Redis instance. For more information, see Configure whitelists.
On-premises device	By default, only internal endpoints are available for ApsaraDB for Redis instances. 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. Run the curl ipinfo.io \|grep ip command on the on-premises device to obtain its public IP address. The following figure shows a sample result. Add the public IP address of the on-premises device to a whitelist of the ApsaraDB for Redis instance. For more information, see Configure whitelists.

Obtain the connection information and run the following command to connect to the ApsaraDB for Redis instance:

src/redis-cli -h <hostname> -p <port> [-c]

Table 1. Parameters
Parameter	Description	Method to obtain the parameter value
<hostname>	The endpoint of the ApsaraDB for Redis instance.	If you connect an ECS instance to the ApsaraDB for Redis instance over a VPC, obtain the endpoint of the ApsaraDB for Redis instance in the VPC. If you connect an on-premises device to the ApsaraDB for Redis instance over the Internet, obtain the public endpoint of the ApsaraDB for Redis instance. For more information, see View endpoints.
<port>	The port number of the ApsaraDB for Redis instance.	Use the default port number 6379 or specify a custom port number. For more information, see Change the endpoint or port number of an ApsaraDB for Redis instance.
-c	Enable the cluster mode	Add -c only when you connect to an ApsaraDB for Redis cluster instance by using a private endpoint. For more information, see Standard master-replica instances and Enable the direct connection mode.

The following sample command is applicable to scenarios where ApsaraDB for Redis instances are connected by using default endpoints, such as endpoints of standard instances and proxy endpoints of cluster instances:

src/redis-cli -h r-bp1zxszhcgatnx****.redis.rds.aliyuncs.com -p 6379

The following sample command is applicable to scenarios where ApsaraDB for Redis instances are connected by using private endpoints:

src/redis-cli -h r-bp1zxszhcgatnx****.redis.rds.aliyuncs.com -p 6379 -c

Run the following command to verify the password:
```
AUTH <password>
```
Note If password-free access is enabled for an ApsaraDB for Redis instance, you can run Redis commands without performing this step when you connect to the instance over a VPC. For more information, see Enable password-free access.
<password>: the password of a specific account. The password format varies based on the selected account. If you forget your password, you can reset it. For more information about how to reset a password, see Change or reset the password.
- If you use the default account whose username is the same as the instance ID, enter only the password.
- If you use a custom account, enter a password in the format of <user>:<password>. A password in this format can also be used for the default account. For example, if the username of the custom account is testaccount and the password is Rp829dlwa, you must enter testaccount:Rp829dlwa as the database password.
Example:
```
AUTH testaccount:Rp829dlwa
```
If the password verification is successful, the following result is returned:
```
OK
```
Note For more information about what to do if an error occurs, see Common connection errors.
After the verification is complete, run Redis commands. For example, run the DBSIZE command to query the number of keys in the current database.
For more information about Redis commands supported by ApsaraDB for Redis, see Overview. For more information about all Redis commands and their usage, visit the Redis official website.

Use redis-cli in Windows

Note Only the 64-bit Windows operating systems are supported.

Install redis-cli. Skip this step if it is already installed.
1. Log on to the device on which you want to install redis-cli, such as an ECS instance or an on-premises device.
2. Download the Redis-x64-3.2.100.zip package.
  
  Note Redis 3.2 (the latest version) is used as an example to demonstrate the operations. You can also install other versions. For more information, see MicrosoftArchive-Redis.
3. Decompress the Redis-x64-3.2.100.zip package to the directory where you want to install Redis. The D:\Redis-x64-3.2.100 directory is used in this example.

Perform the following operations based on the redis-cli installation location:


redis-cli installation location	Operation
ECS instance (recommended)	Make sure that the ECS instance and the ApsaraDB for Redis instance belong to the same VPC. In this case, the same VPC ID is displayed in the Basic Information section of the instances. Note If the 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. Obtain the internal IP address of the ECS instance. For more information, see Network FAQ. Add the internal IP address of the ECS instance to a whitelist of the ApsaraDB for Redis instance. For more information, see Configure whitelists.
On-premises device	By default, only internal endpoints are available for ApsaraDB for Redis instances. 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. On the on-premises device, visit ipinfo to obtain the public IP address of the on-premises device. Add the public IP address of the on-premises device to a whitelist of the ApsaraDB for Redis instance. For more information, see Configure whitelists.

On the ECS instance or on-premises device where redis-cli is installed, press Win+R to open the Run dialog box. In the Run dialog box, enter cmd, and then click OK.
The Windows CLI is opened.

Figure 1. Windows CLI
Run the following command to access the directory where redis-cli is installed:
```
cd /d <path>
```
<path>: the full path of the directory to which the Redis-x64-3.2.100.zip package is decompressed. D:\Redis-x64-3.2.100 is used in this example.

Example:
```
cd /d D:\Redis-x64-3.2.100
```

Obtain the connection information and run the following command to connect to the ApsaraDB for Redis instance:

redis-cli -h <hostname> -p <port> [-c]

Table 2. Parameters
Parameter	Description	Method to obtain the parameter value
<hostname>	The endpoint of the ApsaraDB for Redis instance.	If you connect an ECS instance to the ApsaraDB for Redis instance over a VPC, obtain the endpoint of the ApsaraDB for Redis instance in the VPC. If you connect an on-premises device to the ApsaraDB for Redis instance over the Internet, obtain the public endpoint of the ApsaraDB for Redis instance. For more information, see View endpoints.
<port>	The port number of the ApsaraDB for Redis instance.	Use the default port number 6379 or specify a custom port number. For more information, see Change the endpoint or port number of an ApsaraDB for Redis instance.
-c	Enable the cluster mode	Add -c only when you connect to an ApsaraDB for Redis cluster instance by using a private endpoint. For more information, see Standard master-replica instances and Enable the direct connection mode.

redis-cli -h r-bp1zxszhcgatnx****.redis.rds.aliyuncs.com -p 6379

The following sample command is applicable to scenarios where ApsaraDB for Redis instances are connected by using private endpoints:

redis-cli -h r-bp1zxszhcgatnx****.redis.rds.aliyuncs.com -p 6379 -c

Run the following command to verify the password:
```
AUTH <password>
```
Note If password-free access is enabled for an ApsaraDB for Redis instance, you can run Redis commands without performing this step when you connect to the instance over a VPC. For more information, see Enable password-free access.
<password>: the password of a specific account. The password format varies based on the selected account. If you forget your password, you can reset it. For more information about how to reset a password, see Change or reset the password.
- If you use the default account whose username is the same as the instance ID, enter only the password.
- If you use a custom account, enter a password in the format of <user>:<password>. For example, if the username of the custom account is testaccount and the password is Rp829dlwa, you must enter testaccount:Rp829dlwa as the database password.
Example:
```
AUTH testaccount:Rp829dlwa
```
If the password verification is successful, the following result is returned:
```
OK
```
Note For more information about what to do if an error occurs, see Common connection errors.
After the verification is complete, run Redis commands. For example, run the DBSIZE command to query the number of keys in the current database.
For more information about Redis commands supported by ApsaraDB for Redis, see Overview. For more information about all Redis commands and their usage, visit the Redis official website.

Common connection errors

Note If the minor version of your instance is earlier than required, the returned error message may be misleading. We recommend that you update your instance to the latest minor version. For more information, see Update the minor version.


Error message	Cause and solution
`(error) ERR illegal address`	A whitelist is not configured as required. For more information, see Step 2 in Use redis-cli in Linux or Use redis-cli in Windows.
`(error) ERR client ip is not in whitelist`
`(error) ERR invalid password`	The password is invalid. Make sure that you use the correct password in a valid format. The password format varies based on the selected account. If you use the default account whose username is the same as the instance ID, enter only the password. If you use a custom account, enter a password in the format of `<user>:<password>`. For example, if the username of the custom account is `testaccount` and the password is `Rp829dlwa`, you must enter `testaccount:Rp829dlwa` as the database password. Note If you use a management tool such as Redis Desktop Manager (RDM) to connect to the ApsaraDB for Redis instance, enter a password in the format of `<user>:<password>`. If you forget your password, you can reset it. For more information about how to reset a password, see Change or reset the password.