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. This compatibility enables you to connect to the database using mainstream Redis clients. This topic describes the connection prerequisites and provides code examples for clients in several common programming languages.

Preparations

Before you connect to the Orca feature, complete the following prerequisites:

Your PolarDB cluster has the Orca feature enabled.
You have added the IP address or CIDR block of the client to the whitelist of the PolarDB cluster.
You have created a dedicated Orca account to access the Orca feature.
You have obtained the connection address for the Orca feature.

Notes

Authentication mechanism differences: The authentication mechanism for the Orca feature differs from that of native Redis. Orca does not have a default user. You must authenticate all connections using an Orca account that you create in the console.
AUTH command compatibility: To ensure compatibility with some clients that only support password authentication, the Orca AUTH command supports two formats. When you configure a client, select the appropriate authentication method based on the capabilities of the client.
- 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 entire string as the password parameter.
HELLO command compatibility: Similar to the AUTH command, the authentication part of the HELLO command also supports the two formats mentioned above.
- HELLO <protover> AUTH <username> <password>
- HELLO <protover> AUTH <username>:<password>

Connect using redis-cli

Install redis-cli: Install redis-cli on your client device. For more information, see the redis-cli installation tutorial.
Connect to the Orca feature: Run the following command. Replace the connection address and port with the actual values.
```
redis-cli -h pz-****************.rwlb.rds.aliyuncs.com -p 6379
```
Authenticate the connection: After a successful connection, use the AUTH command to authenticate. Both of the following formats are supported. Replace the placeholders with your Orca username and password.
```
# Format 1: Provide the username and password separately
AUTH orca_user orca_password

# Format 2: Concatenate the username and password and provide the result as the password
AUTH orca_user:orca_password
```
If OK is returned, the connection and authentication are successful.

Connect using clients for different languages

See the following examples to connect based on the programming language of your application.

Java (Jedis)

Add the dependency configuration (Maven):

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

Code example: To be compatible with Jedis, which accepts only one password parameter, 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 information
        String host = "pz-****************.rwlb.rds.aliyuncs.com"; // Replace with your Orca connection address
        int port = 6379;
        String username = "orca_user"; // Replace with your Orca username
        String password = "orca_password"; // Replace with your Orca password

        // Jedis authentication requires you to concatenate 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 dependency configuration (Maven):

<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 example: Lettuce supports setting the username and password separately. This method is 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 information
        String host = "pz-****************.rwlb.rds.aliyuncs.com"; // Replace with your Orca connection address
        int port = 6379;
        String username = "orca_user"; // Replace with your Orca username
        String password = "orca_password"; // Replace with your Orca password

        // Lettuce supports setting the username and password separately
        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 dependency configuration (Maven):

<!-- Spring Boot parent project for unified version management -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.18</version> <!-- A recent stable version is recommended -->
    <relativePath/>
</parent>

<!-- Other configuration items... -->

<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 -->
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

Code example: Choose one of the following methods to configure the settings and connect to Orca.

Configuration via `application.yml`

Spring Boot 2.x and later supports 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 the 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 connection address
    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 startup 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 class RedisTestRunner.java: This class runs automatically after the Spring Boot application starts. It 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 ===");
    }
}

Configure using Java Config

If you are using an earlier version of Spring or have custom requirements, you can use a Java configuration class. Because Jedis is used at the underlying layer, you still need to concatenate the username and password for authentication.

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 can manually create a bean of RedisConnectionFactory and specify all connection details. Spring Boot automatically detects this bean and uses it to configure 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 information
        // Replace with your Orca connection address
        redisConfig.setHostName("pz-****************.rwlb.rds.aliyuncs.com"); 
        // Orca port, which is 6379 by default
        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 above configuration
        LettuceConnectionFactory lettuceFactory = new LettuceConnectionFactory(redisConfig);
        
        // Optional: If you do not call afterPropertiesSet, the Spring container automatically calls it when initializing the bean.
        // lettuceFactory.afterPropertiesSet();

        // 4. Return the configured connection factory instance
        return lettuceFactory;
    }
}

Create the main startup 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 class RedisTestRunner.java: This class runs automatically after the Spring Boot application starts. It 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 example: redis-py version 4.2 and later supports a separate username parameter. If you use an earlier version, use the username:password format for the password parameter.

import redis

# Orca connection information
host = 'pz-****************.rwlb.rds.aliyuncs.com'  # Replace with your Orca connection address
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)

# Method for compatibility with earlier 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 example: go-redis supports a separate Username field. This method is recommended. If you use an earlier client version, use username:password as the value for 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 address 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 example: node-redis supports including authentication information in the connection URL.

import { createClient } from 'redis';

// Orca connection information
const host = 'pz-****************.rwlb.rds.aliyuncs.com'; // Replace with your Orca connection address
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 it using a package manager. For example, on CentOS:
```
sudo yum install php-redis
```

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

<?php
$redis = new Redis();

// Orca connection information
$host = 'pz-****************.rwlb.rds.aliyuncs.com'; // Replace with your Orca connection address
$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 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 run the AUTH command. You can use the concatenated 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 connection address
    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 (a connection with a timeout is recommended)
    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. Authentication
    // 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 reply of the STATUS type
    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.

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

# Run
./orca

Connect using DMS

Connect to Orca

Log on to Data Management (DMS).
In the top menu bar, choose Data Assets > Instance Management.
Click Add, select Other Cloud/Self-managed, and then select Redis from the NoSQL Databases section.
Click Next to go to the Basic Information page. Configure the parameters as described below.
- Set Instance Source to VPC Leased Line. Set Instance Region to the region where the PolarDB cluster is located or a nearby region. Set VPC ID to the VPC of the PolarDB cluster. You can find the VPC ID on the product page. For Logon Address, enter the Orca connection address.
- Set Access Mode to Security Hosting + Manual. In the Database Account and Password fields, enter the credentials for the Orca account.
- After you enter the information, click Test Connection. If the test is successful, a success message is displayed.
Click Next to go to the Advanced Information page. Configure the settings as needed.
Note
Note that Orca does not currently support enabling SSL.
Click Submit. If the submission is successful, the Orca instance enters the security hosting state.

Data management

In the top menu bar, click SQL Window and select the Orca cluster that is in the security hosting state.
Orca currently supports only one logical Redis database, DB0. If you do not see the current database DB0, click Refresh / Sync Dictionary.
If no abnormalities are found, you can use DMS to manage Orca.

Preparations

Notes

Connect using redis-cli

Connect using clients for different languages

Java (Jedis)

Java (Lettuce)

Java (Spring Data Redis)

Configuration via application.yml

Configure using Java Config

Python (redis-py)

Go (go-redis)

Node.js (node-redis)

PHP (PhpRedis)

C (Hiredis)

Connect using DMS

Connect to Orca

Data management

Configuration via `application.yml`