How to connect to Orca and manage data - PolarDB - Alibaba Cloud Documentation Center

The Orca feature of PolarDB for MySQL is compatible with the Redis protocol, allowing you to connect to your database by using mainstream Redis clients. This guide covers the prerequisites and provides client connection code samples for several popular programming languages.

Prerequisites

Before connecting to Orca, ensure you meet the following prerequisites:

The Orca feature is enabled for your PolarDB cluster.
You have added the client's IP address or CIDR block to the whitelist of your PolarDB cluster.
You have created a dedicated Orca account for accessing the Orca feature.
You have obtained the endpoint for the Orca feature.

Usage notes

Authentication mechanism: Orca and native Redis use different authentication mechanisms. Orca does not have a default user. All connections must be authenticated with an Orca account created in the console.
AUTH command compatibility: To support clients that only support password authentication, the Orca AUTH command supports two formats.
- AUTH <username> <password>: Standard format. Provide the username and password separately.
- AUTH <username>:<password>: Compatibility format. Concatenate the username and password with a colon (:) and pass the combined string as a single password parameter.
HELLO command compatibility: Like the AUTH command, the authentication for the HELLO command also supports the two formats described above.
- HELLO <protover> AUTH <username> <password>
- HELLO <protover> AUTH <username>:<password>

Connect with redis-cli

Install redis-cli: See the Install redis-cli tutorial to install it on your client device.
Connect to Orca: Run the following command. Replace the endpoint and port with your actual connection details.
```
redis-cli -h pz-****************.rwlb.rds.aliyuncs.com -p 6379
```
Authenticate your connection: After connecting, use the AUTH command to authenticate. You can use either of the following formats. Replace the placeholders with your Orca account and password.
```
# Format 1: Provide the username and password separately.
AUTH orca_user orca_password
# Format 2: Provide the concatenated username and password as the password.
AUTH orca_user:orca_password
```
A return value of OK indicates a successful connection and authentication.

Connect with client libraries

Use the following examples to connect from your application.

Java (Jedis)

Add the Maven dependency:

<dependency>
    <groupId>redis.clients</groupId>
    <artifactId>jedis</artifactId>
    <version>4.3.0</version>
</dependency>

Code sample: Because Jedis accepts only a single password parameter, you must use the username:password format.

import redis.clients.jedis.Jedis;
import redis.clients.jedis.JedisPool;
import redis.clients.jedis.JedisPoolConfig;
public class JedisExample {
    public static void main(String[] args) {
        JedisPoolConfig poolConfig = new JedisPoolConfig();
        // Orca connection details
        String host = "pz-****************.rwlb.rds.aliyuncs.com"; // Replace with your Orca endpoint
        int port = 6379;
        String username = "orca_user"; // Replace with your Orca username
        String password = "orca_password"; // Replace with your Orca password
        // Jedis authentication requires concatenating the username and password
        String authPassword = username + ":" + password;
        JedisPool pool = new JedisPool(poolConfig, host, port, 3000, authPassword);
        try (Jedis jedis = pool.getResource()) {
            jedis.set("name", "jedis");
            System.out.println(jedis.get("name"));
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            pool.destroy();
        }
    }
}

Java (Lettuce)

Add the Maven dependencies:

<dependency>
    <groupId>io.lettuce</groupId>
    <artifactId>lettuce-core</artifactId>
    <version>6.3.0.RELEASE</version>
</dependency>
<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-transport-native-epoll</artifactId>
    <version>4.1.100.Final</version>
    <classifier>linux-x86_64</classifier>
</dependency>

Code sample: Lettuce supports separate username and password parameters (recommended).

import io.lettuce.core.RedisClient;
import io.lettuce.core.RedisURI;
import io.lettuce.core.api.StatefulRedisConnection;
import io.lettuce.core.api.sync.RedisCommands;
public class LettuceExample {
    public static void main(String[] args) {
        // Orca connection details
        String host = "pz-****************.rwlb.rds.aliyuncs.com"; // Replace with your Orca endpoint
        int port = 6379;
        String username = "orca_user"; // Replace with your Orca username
        String password = "orca_password"; // Replace with your Orca password
        // Lettuce supports separate username and password parameters
        RedisURI uri = RedisURI.Builder
                .redis(host, port)
                .withAuthentication(username, password)
                .build();
        RedisClient redisClient = RedisClient.create(uri);
        StatefulRedisConnection<String, String> connection = redisClient.connect();
        RedisCommands<String, String> syncCommands = connection.sync();
        syncCommands.set("name", "Lettuce");
        String value = syncCommands.get("name");
        // Output: Lettuce
        System.out.println("Get value: " + value); 
        connection.close();
        redisClient.shutdown();
    }
}

Java (Spring Data Redis)

Add the Maven dependencies:

<!-- Spring Boot parent project for version management -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.18</version> <!-- We recommend that you use a recent stable version. -->
    <relativePath/>
</parent>
<!-- Other configurations... -->
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-redis</artifactId>
    </dependency>
    <dependency>
        <groupId>redis.clients</groupId>
        <artifactId>jedis</artifactId>
    </dependency>
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-simple</artifactId>
        <version>1.7.36</version>
    </dependency>
</dependencies>
<build>
    <plugins>
        <!-- Spring Boot Maven plugin for packaging and running the application -->
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

Code sample: You can choose either of the following methods to configure your connection to Orca.

`application.yml`

Spring Boot 2.x and later support specifying the username and password separately in application.yml. This is the recommended method.

The project file structure is as follows:

test_redis/
├── pom.xml
└── src/
    └── main/
        ├── java/
        │   └── com/
        │       └── example/
        │           ├── MainApplication.java
        │           └── RedisTestRunner.java
        └── resources/
            └── application.yml

Configure application.yml: Create an application.yml file in the src/main/resources/ directory. This file stores all configuration information.

spring:
  redis:
    host: pz-****************.rwlb.rds.aliyuncs.com # Replace with your Orca endpoint
    port: 6379
    username: orca_user      # Replace with your Orca username
    password: orca_password  # Replace with your Orca password
    database: 0
    jedis:
      pool:
        max-active: 30
        max-idle: 20
        min-idle: 5
        max-wait: -1ms

Create the main application class MainApplication.java. This is the entry point for the Spring Boot application.

package com.example;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class MainApplication {
    public static void main(String[] args) {
        SpringApplication.run(MainApplication.class, args);
    }
}

Create the test runner class RedisTestRunner.java. This class automatically runs after the Spring Boot application starts, performs Redis read and write operations, and prints the results.

package com.example;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.CommandLineRunner;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Component;
@Component
public class RedisTestRunner implements CommandLineRunner {
    @Autowired
    private StringRedisTemplate stringRedisTemplate;
    @Override
    public void run(String... args) throws Exception {
        System.out.println("=== Starting Redis test with Spring Data Redis ===");
        try {
            // Define a key-value pair.
            String key = "name";
            String value = "spring-data-redis";
            // 1. Run the SET command.
            stringRedisTemplate.opsForValue().set(key, value);
            System.out.println("SET " + key + " = " + value);
            // 2. Run the GET command.
            String retrievedValue = stringRedisTemplate.opsForValue().get(key);
            System.out.println("GET " + key + " = " + retrievedValue);
            // 3. Verify the result.
            if (value.equals(retrievedValue)) {
                System.out.println("Test successful!");
            } else {
                System.out.println("Test failed! Retrieved value does not match.");
            }
        } catch (Exception e) {
            System.err.println("Redis operation failed: " + e.getMessage());
            e.printStackTrace();
        }
        System.out.println("=== Redis test completed ===");
    }
}

Java Config

If you are using an older version of Spring or have custom requirements, you can use a Java configuration class. The following example uses LettuceConnectionFactory, which allows you to specify the username and password separately.

The project file structure is as follows:

test_redis/
├── pom.xml
└── src/
    └── main/
        ├── java/
        │   └── com/
        │       └── example/
        │           ├── config/
        │           │   └── RedisConfig.java   <-- Core configuration class
        │           ├── MainApplication.java
        │           └── RedisTestRunner.java
        └── resources/
            └── application.yml            <-- This file can be deleted or left empty.

Create the core configuration class RedisConfig.java. In this class, you manually create and configure a RedisConnectionFactory bean with all connection details. Spring Boot automatically detects this bean and uses it for all Redis-related operations, such as StringRedisTemplate.

package com.example.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.redis.connection.RedisConnectionFactory;
import org.springframework.data.redis.connection.RedisStandaloneConfiguration;
import org.springframework.data.redis.connection.lettuce.LettuceConnectionFactory;
@Configuration
public class RedisConfig {
    @Bean
    public RedisConnectionFactory redisConnectionFactory() {
        // 1. Create a standalone Redis configuration.
        RedisStandaloneConfiguration redisConfig = new RedisStandaloneConfiguration();
        // 2. Set the Orca connection details.
        // Replace with your Orca endpoint.
        redisConfig.setHostName("pz-****************.rwlb.rds.aliyuncs.com"); 
        // Orca port. The default value is 6379.
        redisConfig.setPort(6379);
        // Replace with your Orca username.
        redisConfig.setUsername("orca_user");
        // Replace with your Orca password.
        redisConfig.setPassword("orca_password");
        // 3. Use Lettuce as the client and apply the configuration.
        LettuceConnectionFactory lettuceFactory = new LettuceConnectionFactory(redisConfig);
        // Optional: If you do not call afterPropertiesSet(), the Spring container calls it automatically when initializing the bean.
        // lettuceFactory.afterPropertiesSet();
        // 4. Return the configured connection factory instance.
        return lettuceFactory;
    }
}

Create the main application class MainApplication.java. This is the entry point for the Spring Boot application.

package com.example;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class MainApplication {
    public static void main(String[] args) {
        SpringApplication.run(MainApplication.class, args);
    }
}

Create the test runner class RedisTestRunner.java. This class automatically runs after the Spring Boot application starts, performs Redis read and write operations, and prints the results.

package com.example;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.CommandLineRunner;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Component;
@Component
public class RedisTestRunner implements CommandLineRunner {
    @Autowired
    private StringRedisTemplate stringRedisTemplate;
    @Override
    public void run(String... args) throws Exception {
        System.out.println("=== Starting Redis test with Spring Data Redis ===");
        try {
            // Define a key-value pair.
            String key = "name";
            String value = "spring-data-redis";
            // 1. Run the SET command.
            stringRedisTemplate.opsForValue().set(key, value);
            System.out.println("SET " + key + " = " + value);
            // 2. Run the GET command.
            String retrievedValue = stringRedisTemplate.opsForValue().get(key);
            System.out.println("GET " + key + " = " + retrievedValue);
            // 3. Verify the result.
            if (value.equals(retrievedValue)) {
                System.out.println("Test successful!");
            } else {
                System.out.println("Test failed! Retrieved value does not match.");
            }
        } catch (Exception e) {
            System.err.println("Redis operation failed: " + e.getMessage());
            e.printStackTrace();
        }
        System.out.println("=== Redis test completed ===");
    }
}

Python (redis-py)

Install the dependency:
```
pip install redis
```

Code sample: redis-py 4.2+ supports a separate username parameter. In older versions, pass the username:password string as the password parameter.

import redis
# Orca connection details
host = 'pz-****************.rwlb.rds.aliyuncs.com'  # Replace with your Orca endpoint
port = 6379
username = 'orca_user'  # Replace with your Orca username
password = 'orca_password'  # Replace with your Orca password
# Recommended method (redis-py >= 4.2)
r = redis.Redis(host=host, port=port, username=username, password=password)
# Compatibility method for older versions
# auth_password = f'{username}:{password}'
# r = redis.Redis(host=host, port=port, password=auth_password)
r.set('name', 'redis-py')
print(r.get('name').decode('utf-8'))
r.close()

Go (go-redis)

Install the dependency:
```
go get github.com/go-redis/redis/v8
```

Code sample: go-redis supports a separate Username field (recommended). In older versions, pass the username:password string as the Password field.

package main
import (
    "context"
    "fmt"
    "github.com/go-redis/redis/v8"
)
var ctx = context.Background()
func main() {
    client := redis.NewClient(&redis.Options{
        Addr:     "pz-****************.rwlb.rds.aliyuncs.com:6379", // Replace with your Orca endpoint and port
        Username: "orca_user",     // Replace with your Orca username
        Password: "orca_password", // Replace with your Orca password
        DB:       0,
    })
    err := client.Set(ctx, "name", "go-redis", 0).Err()
    if err != nil {
        panic(err)
    }
    val, err := client.Get(ctx, "name").Result()
    if err != nil {
        panic(err)
    }
    fmt.Println("Get value:", val)
}

Node.js (node-redis)

Install the dependency:
```
npm install redis
```

Code sample: node-redis supports including authentication information in the connection URL.

import { createClient } from 'redis';
// Orca connection details
const host = 'pz-****************.rwlb.rds.aliyuncs.com'; // Replace with your Orca endpoint
const port = 6379;
const username = 'orca_user'; // Replace with your Orca username
const password = 'orca_password'; // Replace with your Orca password
const client = createClient({
    url: `redis://${username}:${encodeURIComponent(password)}@${host}:${port}/0`
});
client.on('error', (err) => console.error('Redis Client Error:', err));
async function runExample() {
    try {
        await client.connect();
        await client.set('name', 'node-redis');
        const value = await client.get('name');
        console.log('get name:', value);
    } finally {
        await client.disconnect();
    }
}
runExample();

PHP (PhpRedis)

Install the dependency: You can typically install this extension by using a package manager. For example, on CentOS:
```
sudo yum install php-redis
```

Code sample: The auth method of the PhpRedis extension supports passing an array that contains the username and password.

<?php
$redis = new Redis();
// Orca connection details
$host = 'pz-****************.rwlb.rds.aliyuncs.com'; // Replace with your Orca endpoint
$port = 6379;
$user = 'orca_user';     // Replace with your Orca username
$password = 'orca_password'; // Replace with your Orca password
if ($redis->connect($host, $port) === false) {
    die($redis->getLastError());
}
// Authenticate by using an array that contains the username and password.
if ($redis->auth([$user, $password]) === false) {
    die($redis->getLastError());
}
$redis->set("name", "php-redis");
echo $redis->get("name");
$redis->close();
?>

C (Hiredis)

Install the dependency: Compile and install from the source code.

git clone https://github.com/redis/hiredis.git
cd hiredis
make && sudo make install

Code example: Use redisCommand to execute the AUTH command. You can use the username:password format.

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <hiredis.h>
int main() {
    // Orca connection parameters
    const char *hostname = "********.rwlb.rds.aliyuncs.com"; // Replace with your Orca endpoint
    int port = 6379;
    // Define the username and password separately for ease of use.
    const char *username = "orca_user"; // Replace with your Orca username
    const char *password = "orca_password"; // Replace with your Orca password
    redisContext *c;
    redisReply *reply;
    // 1. Connect to Redis. We recommend that you use a connection with a timeout.
    struct timeval timeout = { 2, 0 }; // 2-second timeout
    c = redisConnectWithTimeout(hostname, port, timeout);
    if (c == NULL || c->err) {
        if (c) {
            printf("Connection error: %s\n", c->errstr);
            redisFree(c);
        } else {
            printf("Can't allocate redis context\n");
        }
        exit(1);
    }
    // 2. Authenticate.
    // Use the "AUTH <username> <password>" format.
    reply = redisCommand(c, "AUTH %s %s", username, password);
    if (reply == NULL) {
        // If reply is NULL, an I/O error occurred. Check c->errstr.
        printf("AUTH command failed: %s\n", c->errstr);
        redisFree(c);
        exit(1);
    }
    // Check if the reply itself is an error type.
    if (reply->type == REDIS_REPLY_ERROR) {
        printf("Authentication failed: %s\n", reply->str);
        freeReplyObject(reply);
        redisFree(c);
        exit(1);
    }
    printf("Authenticated successfully\n");
    freeReplyObject(reply); // After successful authentication, do not forget to free the reply.
    // 3. Run the SET command.
    reply = redisCommand(c, "SET mykey %s", "Hello, hiredis!");
    if (reply == NULL) {
        printf("SET command failed: %s\n", c->errstr);
        redisFree(c);
        exit(1);
    }
    // For a successful SET command, hiredis returns a STATUS type reply.
    if (reply->type == REDIS_REPLY_STATUS && strcmp(reply->str, "OK") == 0) {
        printf("SET mykey succeeded\n");
    } else {
        printf("SET failed with reply: %s\n", reply->str);
    }
    freeReplyObject(reply);
    // 4. Run the GET command.
    reply = redisCommand(c, "GET mykey");
    if (reply == NULL) {
        printf("GET command failed: %s\n", c->errstr);
        redisFree(c);
        exit(1);
    }
    if (reply->type == REDIS_REPLY_STRING) {
        printf("GET mykey = %s\n", reply->str);
    } else if (reply->type == REDIS_REPLY_NIL) {
        printf("Key 'mykey' does not exist\n");
    } else {
        printf("GET returned unexpected type: %d, error: %s\n", reply->type, reply->str);
    }
    freeReplyObject(reply);
    // 5. Close the connection.
    redisFree(c);
    printf("Disconnected from Redis\n");
    return 0;
}

Compile and run the program.

# Compile. Adjust the paths after -I and -L based on your installation location.
gcc -o orca orca.c -I/usr/local/include/hiredis -L/usr/local/lib -lhiredis
# Run the program.
./orca

Connect with DMS

Connect to Orca

Log on to the Database Management (DMS) console.
In the top navigation bar, choose Data Assets > Instances.
Click Add, select Third-party Cloud/Self-managed, and then select Redis from the NoSQL Database section.
Click Next to go to the basic information page. Configure the parameters as follows:
- For Instance Source, select VPC PrivateLine. For Region, select the region where your PolarDB cluster is located or a nearby region. For VPC ID, select the VPC ID from the PolarDB cluster details page. For Logon Address, enter the Orca endpoint.
- For Access Method, select Account + password login. Enter the database account and password of your Orca account.
- After you fill in the information, click Test Connectivity. A success message appears if the connection is successful.
Click Next to go to the Advanced Information page and configure the settings as needed.

Note
Orca does not currently support SSL encryption.
Click Submit. If successful, the Orca instance enters Secure Management mode.

Manage data

In the top navigation bar, choose SQL Console and select your managed Orca cluster.
Orca currently supports only one logical Redis database, DB0. If you do not see the DB0 database, click Refresh / Sync Dictionary.
You can now manage Orca by using DMS.

For example, run the ping key01 command in the SQL Console. A return value of PONG indicates a successful connection.