use redis-cli to connect to Tair, use redis-cli to connect to Redis - Tair (Redis® OSS-Compatible)

redis-cli is a command-line utility that comes with Redis. You can use redis-cli to connect to and manage Tair and Redis instances from an Elastic Compute Service (ECS) instance or on-premises device. This topic describes how to install and use redis-cli to connect to a Tair or Redis instance and how to troubleshoot common connection errors.

Free trial

Alibaba Cloud Free Trial is a program that allows eligible new users to try out Alibaba Cloud services for free for a limited time. For more information, go to the free trial page.

Workflow

Step	Description
1. Specify the account used to connect to the instance and the account password.	The following methods are available: Specify a password for the default account of the instance. For more information, see Change or reset the password. Specify a custom account and its password. For more information, see Create and manage database accounts.
2. Configure a whitelist.	Only IP addresses in the whitelist can connect to the instance. The recommended network type varies with device. Choose a network type that suits your device and add the IP address of the device to the whitelist of the instance. ECS instance (recommended): We recommend that you use a virtual private cloud (VPC). Make sure that the ECS instance and the Tair or Redis instance are deployed in the same VPC and that the private IP address of the ECS instance is added to the whitelist of the Tair or Redis instance. Note If the ECS instance and the Tair or Redis instance do not reside in the same VPC, such as when the two instances reside in different regions, add the public IP address of the ECS instance to the whitelist of the Tair or Redis instance and connect the ECS instance to the Tair or Redis instance over the Internet. On-premises device: You can use the Internet. Add the public IP address of the on-premises device to the whitelist of the Tair or Redis instance. For more information, see Configure whitelists.
3. Obtain connection information.	If you use a VPC, obtain the VPC of the instance in the Tair (Redis OSS-compatible) console. If you use the Internet, apply for a public endpoint for the instance and obtain the allocated public endpoint in the Tair (Redis OSS-compatible) console. Note By default, only VPC endpoints are available for Tair or Redis instances. If you want to connect to an instance over the Internet, you must apply for a public endpoint for the instance. For more information, see View endpoints.
4. Use redis-cli to connect to the instance.	Run the following commands based on your needs in the directory to which redis-cli is decompressed: Command syntax used to establish a connection: `redis-cli -h hostname -p port` Sample command: `redis-cli -h r-bp1zxszhcgatnx****.redis.rds.aliyuncs.com -p 6379` Command syntax used to specify a password: `AUTH user:password` Sample command: `AUTH testaccount:Rp829dlwa` For more information, see Connect to a Redis or Tair instance.

Install redis-cli

If you do not have redis-cli installed on your device, refer to the following instructions.

Installation instructions for redis-cli

redis-cli is automatically installed when you install Redis on your ECS instance or on-premises device. If you use redis-cli to connect to a Tair (Redis OSS-compatible) instance, the version of redis-cli does not need to be the same as that of the Tair (Redis OSS-compatible) instance.

Log on to the device on which you want to install redis-cli, such as an ECS instance or an on-premises device.
Download and install redis-cli.
Windows
Only 64-bit Windows operating systems are supported.
1. Download the Redis-x64-3.2.100.zip package.
  Note
  In this example, Redis 3.2 is used to demonstrate the operations. You can install other versions. For more information, visit GitHub.
2. Decompress the Redis-x64-3.2.100.zip package to the directory in which you want to install Redis.
macOS
You can use the Homebrew package manager to install the Redis client on a macOS device. To use Homebrew to install Redis on your device, perform the following steps:
Install Homebrew if it is not installed
1. Launch Terminal.
2. Copy and paste the following command into the Terminal window and press the Enter key. The command downloads and runs the Homebrew installation script.
```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
1. Follow the instructions on the screen. You may need to enter a password.
Use Homebrew to install Redis
In the Terminal window, enter the following command to install the Redis toolkit (including redis-cli):
```
brew install redis
```
The command downloads and installs the latest stable version of Redis on your system. After the installation is successful, you can enter the which redis-cli command in the Terminal window to obtain the location of redis-cli.
Linux
Run the following command to install the GNU Compiler Collection (GCC) compiler and its dependencies:
```
sudo yum -y install gcc
```
Run the following command to download the Redis source code package:
```
wget https://download.redis.io/releases/redis-7.0.0.tar.gz
```
Note
In this example, Redis 7.0.0 is used to demonstrate the operations. You can install other versions. For more information, visit the Redis official website.
Run the following command to decompress the Redis source code package:
```
tar xzf redis-7.0.0.tar.gz
```
Run the following command to go to the directory to which the Redis source code package is decompressed. Then, compile and install Redis.
```
cd redis-7.0.0&&make
```
Note
It takes 2 to 3 minutes to compile and install Redis.

Connect to a Redis or Tair instance

Go to the directory in which redis-cli is installed.
Windows
Open the CLI and go to the directory in which redis-cli is installed.
macOS
Go to the Redis directory that is suffixed with redis-cli. Example: cd /opt/homebrew/bin.
Linux
Go to the Redis directory that is suffixed with src. Example: cd /home/redis-7.0.0/src.

Run the following command to use redis-cli to connect to the Redis or Tair instance:

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

Note

If you want to start redis-cli in Windows PowerShell, run the .\redis-cli -h hostname -p port [-c] command.

Table 1. Parameters

Parameter	Description	Method to obtain the parameter value
hostname	The endpoint of the instance.	If you connect to the instance over a VPC, obtain the VPC endpoint of the instance. If you connect to the instance over the Internet, obtain the public endpoint of the instance. For more information, see View endpoints.
port	The port number of the 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 instance.
-c	Specifies whether to enable the cluster mode.	The cluster mode is available only if the instance is a cluster instance that uses a private endpoint.

Connection examples:

The following sample command is suitable for scenarios in which instances are connected by using default endpoints, such as endpoints of standard instances and proxy endpoints of cluster instances:
```
./redis-cli -h r-bp1zxszhcgatnx****.redis.rds.aliyuncs.com -p 6379
```
The following sample command is suitable for scenarios in which cluster 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>

Table 2. Parameters

Parameter

Description

password

The password of the account.

If you use the default account whose username is default or the same as the instance ID, enter only the password.
If you use a custom account, enter the password in the user:password format. For example, if the username of a custom account is testaccount and the password is Rp829dlwa, enter testaccount:Rp829dlwa as the password.

Note

If you forget your password, reset the password. If you have not set a password, set a password. For more information, see Change or reset the password.
If password-free access is enabled for the instance, password authentication is not required when you connect to the instance over a VPC.

Example:

AUTH testaccount:Rp829dlwa

If OK is displayed, the instance is connected and Redis commands can be run on the instance.

For information about what to do if an error occurs, see Common errors and troubleshooting.
For information about the commands supported by Tair (Redis OSS-compatible) instances, see Command overview.

Common errors and troubleshooting

Note

If the minor version of your instance is outdated, the returned error messages may be inconsistent with those listed in the following table. We recommend that you update your instance to the latest minor version. For more information, see Update the minor version of an instance.

Error message	Cause and solution
`(error) ERR illegal address`	A whitelist is not configured as required. For more information, see the second step mentioned in the Workflow section.
`(error) ERR client ip is not in whitelist`
`(error) ERR invalid password` `(error) WRONGPASS invalid username-password pair`	The password is invalid. Specify the correct password in a valid format. The password format varies with the selected account type. If you use the default account whose username is `default` or the same as the instance ID, enter only the password. If you use a custom account, enter the password in the `user:password` format. For example, if the username of a custom account is `testaccount` and the password is `Rp829dlwa`, enter `testaccount:Rp829dlwa` as the password. Note If you use a third-party database management tool such as Remote Desktop Manager (RDM) to connect to an instance, enter the password in the `user:password` format. If you forget your password, you can reset it. For more information, see Change or reset the password.

Free trial

Workflow

Install redis-cli

Windows

macOS

Linux

Connect to a Redis or Tair instance

Windows

macOS

Linux

Common errors and troubleshooting