How to connect to Orca and manage data - PolarDB - Centro de documentación de Alibaba Cloud

La función Orca de PolarDB for MySQL es compatible con el protocolo Redis, lo que le permite conectarse a su base de datos mediante clientes de Redis de uso extendido. Esta guía describe los requisitos previos y proporciona ejemplos de código de conexión del cliente para varios lenguajes de programación populares.

Requisitos previos

Antes de conectarse a Orca, asegúrese de cumplir los requisitos previos que se indican a continuación:

Orca feature is enabled de su clúster de PolarDB.
Ha agregado la dirección IP o el bloque CIDR del cliente a whitelist de su clúster de PolarDB.
Cuenta con created a dedicated Orca account para acceder a la función Orca.
Ha obtenido endpoint para la función Orca.

Notas de uso

Mecanismo de autenticación: Orca y Redis nativo usan mecanismos de autenticación diferentes. Orca no tiene un usuario predeterminado. Todas las conexiones deben autenticarse con una cuenta de Orca creada en la consola.
Compatibilidad del comando AUTH: Para ser compatible con los clientes que solo admiten autenticación con contraseña, el comando AUTH de Orca admite dos formatos.
- AUTH <username> <password>: Formato estándar. Proporcione el nombre de usuario y la contraseña por separado.
- AUTH <username>:<password>: Formato de compatibilidad. Concatene el nombre de usuario y la contraseña con dos puntos (:) y pase la cadena combinada como un único parámetro de contraseña.
Compatibilidad del comando HELLO: Al igual que con el comando AUTH, la autenticación del comando HELLO también admite los dos formatos descritos anteriormente.
- HELLO <protover> AUTH <username> <password>
- HELLO <protover> AUTH <username>:<password>

Conectarse con redis-cli

Instale redis-cli: Consulte Install redis-cli tutorial para instalarlo en su equipo cliente.
Conéctese a Orca: Ejecute el comando que se muestra a continuación. Reemplace el endpoint y el puerto con sus detalles de conexión reales.
```
redis-cli -h pz-****************.rwlb.rds.aliyuncs.com -p 6379
```
Autentique su conexión: Después de conectarse, use el comando AUTH para autenticarse. Puede usar cualquiera de los formatos que se indican a continuación. Reemplace los marcadores de posición con su cuenta y contraseña de Orca.
```
# 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
```
Un valor de retorno de OK indica que la conexión y la autenticación se completaron correctamente.

Conectarse con bibliotecas de cliente

Utilice los ejemplos que se muestran a continuación para conectarse desde su aplicación.

Java (Jedis)

Agregue la dependencia de Maven:

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

Ejemplo de código: Dado que Jedis solo acepta un único parámetro de contraseña, debe usar el formato username:password.

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)

Agregue las dependencias de 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>

Ejemplo de código: Lettuce admite parámetros separados de nombre de usuario y contraseña (recomendado).

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)

Agregue las dependencias de Maven:

<!-- 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>

Ejemplo de código: Puede elegir cualquiera de los métodos que se indican a continuación para configurar su conexión a Orca.

`application.yml`

Spring Boot 2.x y versiones posteriores admiten especificar el nombre de usuario y la contraseña por separado en application.yml. Este es el método recomendado.

La estructura de archivos del proyecto se muestra a continuación:

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

Configure application.yml: Cree un archivo application.yml en el directorio src/main/resources/. Este archivo almacena toda la información de configuración.

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

Cree la clase principal de la aplicación MainApplication.java. Esta clase es el punto de entrada de la aplicación Spring Boot.

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);
    }
}

Cree la clase de ejecución de prueba RedisTestRunner.java. Esta clase se ejecuta automáticamente después de que se inicia la aplicación Spring Boot, realiza operaciones de lectura y escritura en Redis y muestra los resultados.

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

Si usa una versión anterior de Spring o tiene requisitos personalizados, puede usar una clase de configuración de Java. El ejemplo que se muestra a continuación usa LettuceConnectionFactory, lo que permite especificar el nombre de usuario y la contraseña por separado.

La estructura de archivos del proyecto se muestra a continuación:

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.

Cree la clase de configuración principal RedisConfig.java. En esta clase, cree y configure manualmente un bean RedisConnectionFactory con todos los detalles de conexión. Spring Boot detecta automáticamente este bean y lo usa para todas las operaciones relacionadas con Redis, como 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;
    }
}

Cree la clase principal de la aplicación MainApplication.java. Esta clase es el punto de entrada de la aplicación Spring Boot.

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);
    }
}

Cree la clase de ejecución de prueba RedisTestRunner.java. Esta clase se ejecuta automáticamente después de que se inicia la aplicación Spring Boot, realiza operaciones de lectura y escritura en Redis y muestra los resultados.

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)

Instale la dependencia:
```
pip install redis
```

Ejemplo de código: redis-py 4.2+ admite un parámetro username separado. En versiones anteriores, pase la cadena username:password como el parámetro password.

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)

Instale la dependencia:
```
go get github.com/go-redis/redis/v8
```

Ejemplo de código: go-redis admite un campo Username separado (recomendado). En versiones anteriores, pase la cadena username:password como el campo Password.

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)

Instale la dependencia:
```
npm install redis
```

Ejemplo de código: node-redis admite incluir información de autenticación en la URL de conexión.

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)

Instale la dependencia: Por lo general, puede instalar esta extensión mediante un administrador de paquetes. Por ejemplo, en CentOS:
```
sudo yum install php-redis
```

Ejemplo de código: El método auth de la extensión PhpRedis admite pasar un arreglo que contiene el nombre de usuario y la contraseña.

<?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)

Instale la dependencia: Compile e instale desde el código fuente.

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

Ejemplo de código: Use redisCommand para ejecutar el comando AUTH. Puede usar el formato username:password.

#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 y ejecute el programa.

# 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

Conectarse con DMS

Conectarse a Orca

Inicie sesión en la consola de Database Management (DMS).
En la barra de navegación superior, elija Data Assets > Instances.
Haga clic en Add, seleccione Third-party Cloud/Self-managed y, a continuación, seleccione Redis en la sección NoSQL Database.
Haga clic en Next para ir a la página de información básica. Configure los parámetros como se indica a continuación:
- Para Instance Source, seleccione VPC PrivateLine. Para Region, seleccione la región donde se encuentra su clúster de PolarDB o una región cercana. Para VPC ID, seleccione el ID de VPC de la página de detalles del clúster de PolarDB. Para Logon Address, introduzca Orca endpoint.
- Para Access Method, seleccione Account + password login. Introduzca la cuenta de la base de datos y la contraseña de su cuenta de Orca.
- Después de completar la información, haga clic en Test Connectivity. Si la conexión es correcta, aparece un mensaje de éxito.
Haga clic en Next para ir a la página Advanced Information y configure los ajustes según sea necesario.

Nota
Por el momento, Orca no admite cifrado SSL.
Haga clic en Submit. Si la operación es correcta, la instancia de Orca entra en el modo Secure Management.

Gestionar datos

En la barra de navegación superior, elija SQL Console y seleccione su clúster de Orca gestionado.
Orca actualmente solo admite una base de datos lógica de Redis, DB0. Si no ve la base de datos DB0, haga clic en Refresh / Sync Dictionary.
Ahora puede gestionar Orca mediante DMS.

Por ejemplo, ejecute el comando ping key01 en SQL Console. Un valor de retorno de PONG indica una conexión correcta.