All Products
Search
Document Center

ApsaraDB for Redis:Use redis-cli to connect to an ApsaraDB for Redis instance

Last Updated:Feb 07, 2024

redis-cli is a built-in CLI of open source Redis. You can use redis-cli to connect to and manage an ApsaraDB for Redis 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 an ApsaraDB for Redis instance, and how to troubleshoot common connection errors.

Workflow

Workflow for connecting to an ApsaraDB for Redis instance

Step

Description

1. Specify the account used to connect to the ApsaraDB for Redis instance and the account password.

The following methods are available:

2. Configure a whitelist.

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 ApsaraDB for Redis instance.

  • ECS instance (recommended): VPC is recommended.

    Make sure that the ECS instance and the ApsaraDB for Redis instance are deployed in the same VPC and that a whitelist of the ApsaraDB for Redis instance contains the private IP address of the ECS instance.

    Note

    If the ECS instance and the ApsaraDB for Redis instance are located in different regions, these two instances are deployed in different VPCs. In this case, add the public IP address of the ECS instance to a whitelist of the ApsaraDB for Redis instance and connect to the ApsaraDB for Redis instance over the Internet.

  • On-premises device: Internet can be used.

    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.

3. Obtain connection information.

  • If you use a VPC, obtain the endpoint of the ApsaraDB for Redis instance in the VPC in the ApsaraDB for Redis console.

  • If you use the Internet, apply for a public endpoint for the ApsaraDB for Redis instance and obtain the allocated public endpoint in the ApsaraDB for Redis console. For more information, see Apply for a public endpoint for an ApsaraDB for Redis instance.

    Note

    By default, only VPC 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 View endpoints.

4. Use redis-cli to connect to the ApsaraDB for Redis 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 the Step 2: Use redis-cli to connect to the ApsaraDB for Redis instance section of this topic.

Step 1: Install redis-cli

Procedure for installing 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 an ApsaraDB for Redis instance, the version of redis-cli does not need to be the same as that of the ApsaraDB for Redis instance.

  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 and install redis-cli.

    • Linux

      1. Run the following command to install the GNU Compiler Collection (GCC) compiler and its dependencies:

        sudo yum -y install gcc
      2. 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.

      3. Run the following command to decompress the Redis source code package:

        tar xzf redis-7.0.0.tar.gz
      4. 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 generally takes 2 to 3 minutes to compile and install Redis.

    • 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.

Step 2: Use redis-cli to connect to the ApsaraDB for Redis instance

  1. 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.

    • Linux: Go to the Redis directory that is suffixed with src. Example: cd /home/redis-7.0.0/src.

  2. Run the following command to use redis-cli to connect to the ApsaraDB for Redis 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 ApsaraDB for Redis instance.

    • If you connect to the ApsaraDB for Redis instance over a VPC, obtain the VPC endpoint of the ApsaraDB for Redis instance.

    • If you connect 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 instance.

    -c

    Specifies whether to enable the cluster mode.

    The cluster mode is available only if the ApsaraDB for Redis instance is a cluster instance that uses a private endpoint. For more information, see Cluster master-replica instances and Enable the direct connection mode.

    Connection examples:

    • The following sample command is suitable for scenarios in which ApsaraDB for Redis 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 ApsaraDB for Redis cluster instances are connected by using private endpoints:

      ./redis-cli -h r-bp1zxszhcgatnx****.redis.rds.aliyuncs.com -p 6379 -c
  3. 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 the same as the instance ID, enter the password.

    • If you use a custom account, enter the password in the user:password format. For example, if the username of the 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 the password, set the password. For more information, see Change or reset the password.

    • If password-free access is enabled for the 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.

    Example:

    AUTH testaccount:Rp829dlwa

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

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 Workflow section of this topic.

(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 based on the selected account.

  • If you use the default account whose username is the same as the instance ID, enter the password.

  • If you use a custom account, enter the password in the user:password format. For example, if the username of the 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 ApsaraDB for Redis 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.