Tair (Redis® OSS-Compatible):Use redis-cli to connect to an instance
Last Updated:Nov 06, 2024
redis-cli is a built-in CLI provided by Redis. You can use redis-cli to connect to and manage a Tair (Redis OSS-compatible) instance 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 instance. This topic also describes 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
Workflow for connecting to an instance
Step
Description
1. Specify the account used to connect to the Tair instance and the account password.
The following methods are available:
Specify a password for the default account of the Tair instance. For more information, see Change or reset the password.
The recommended network type varies with device. Choose a network type that suits your device and add the IP address of the device to a whitelist of the Tair instance.
ECS instance (recommended): We recommend that you use a virtual private cloud (VPC).
Make sure that the ECS instance and the Tair (Redis OSS-compatible) instance are deployed in the same VPC and that the private IP address of the ECS instance is added to a whitelist of the Tair instance.
Note
If the ECS instance and the Tair 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 a whitelist of the Tair instance and connect the ECS instance to the Tair instance over the Internet.
On-premises device: You can use the Internet.
Add the public IP address of the on-premises device to a whitelist of the Tair instance.
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 Tair instance and obtain the allocated public endpoint in the Tair (Redis OSS-compatible) console. For more information, see Apply for a public endpoint for an instance.
Note
By default, only VPC are available for Tair instances. If you want to connect to an instance over the Internet, you must apply for a public endpoint for the instance.
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 the Tair (Redis OSS-compatible) instance, the version of redis-cli does not need to be the same as that of the Tair 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.
In this example, Redis 3.2 is used to demonstrate the operations. You can install other versions. For more information, visit GitHub.
Decompress the Redis-x64-3.2.100.zip package to the directory in which you want to install Redis.
macOS
Homebrew is a common and convenient way to install Redis on macOS. Homebrew is a package manager for macOS. To use Homebrew to install Redis on your device, perform the following steps:
Install Homebrew if it is not installed
Launch Terminal.
Copy and paste the following command into the Terminal window and press the Enter key. The command downloads and runs the Homebrew installation script.
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 Redis:
brew install redis
The command downloads the latest stable version of Redis and installs it 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:
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.
Procedure
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 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 Tair instance.
If you connect to the Tair instance over a VPC, obtain the VPC endpoint of the Tair instance.
If you connect to the Tair instance over the Internet, obtain the public endpoint of the Tair instance.
The following sample command is suitable for scenarios in which Tair instances are connected by using default endpoints, such as endpoints of standard instances and proxy endpoints of cluster instances:
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 Tair 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.
Example:
AUTH testaccount:Rp829dlwa
If OK is displayed, the Tair instance is connected and Redis commands can be run on the instance.
For information about commands supported by Tair (Redis OSS-compatible), see 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 a Tair instance, enter the password in the user:password format.