Como conectar ao Orca e gerenciar dados - PolarDB: Central de Documentação do Alibaba Cloud

O recurso Orca do PolarDB for MySQL é compatível com o protocolo Redis, permitindo a conexão ao banco de dados por meio de clientes Redis convencionais. Este guia aborda os pré-requisitos e fornece exemplos de código de conexão para diversas linguagens de programação populares.

Pré-requisitos

Antes de se conectar ao Orca, verifique se você atende aos seguintes pré-requisitos:

O recurso Orca está ativado no seu cluster PolarDB.
Você adicionou o endereço IP ou o bloco CIDR do cliente à lista de permissões do seu cluster PolarDB.
Você criou uma conta dedicada do Orca para acessar o recurso Orca.
Você obteve o endpoint do recurso Orca.

Observações de uso

Mecanismo de autenticação: O Orca e o Redis nativo utilizam mecanismos de autenticação diferentes. O Orca não possui usuário padrão. Todas as conexões exigem autenticação com uma conta Orca criada no console.
Compatibilidade do comando AUTH: Para oferecer suporte a clientes que aceitam apenas autenticação por senha, o comando AUTH do Orca aceita dois formatos.
- AUTH <username> <password>: Formato padrão. Forneça o nome de usuário e a senha separadamente.
- AUTH <username>:<password>: Formato de compatibilidade. Concatene o nome de usuário e a senha com dois pontos (:) e passe a string combinada como um único parâmetro de senha.
Compatibilidade do comando HELLO: Assim como o comando AUTH, a autenticação do comando HELLO também aceita os dois formatos descritos acima.
- HELLO <protover> AUTH <username> <password>
- HELLO <protover> AUTH <username>:<password>

Conexão com redis-cli

Instale o redis-cli: Consulte o Tutorial de instalação do redis-cli para instalá-lo no dispositivo cliente.
Conecte-se ao Orca: Execute o comando a seguir. Substitua o endpoint e a porta pelos detalhes reais de conexão.
```
redis-cli -h pz-****************.rwlb.rds.aliyuncs.com -p 6379
```
Autentique a conexão: Após conectar-se, use o comando AUTH para autenticação. Utilize qualquer um dos formatos abaixo. Substitua os espaços reservados pela conta e senha do 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
```
O valor de retorno OK indica conexão e autenticação bem-sucedidas.

Conexão com bibliotecas cliente

Use os exemplos a seguir para estabelecer a conexão a partir da aplicação.

Java (Jedis)

Adicione a dependência Maven:

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

Exemplo de código: Como o Jedis aceita apenas um único parâmetro de senha, use o 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)

Adicione as dependências 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>

Exemplo de código: O Lettuce aceita parâmetros separados para nome de usuário e senha (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)

Adicione as dependências 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>

Exemplo de código: Escolha um dos métodos a seguir para configurar a conexão com o Orca.

`application.yml`

O Spring Boot 2.x e versões posteriores permitem especificar o nome de usuário e a senha separadamente no arquivo application.yml. Este é o método recomendado.

A estrutura de arquivos do projeto é a seguinte:

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

Configure o application.yml: Crie um arquivo application.yml no diretório src/main/resources/. Esse arquivo armazena todas as informações de configuração.

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

Crie a classe principal da aplicação MainApplication.java. Ela serve como ponto de entrada para a aplicação 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);
    }
}

Crie a classe de execução de testes RedisTestRunner.java. Esta classe executa automaticamente após a inicialização da aplicação Spring Boot, realiza operações de leitura e escrita no Redis e imprime os 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

Caso utilize uma versão mais antiga do Spring ou tenha requisitos personalizados, use uma classe de configuração Java. O exemplo abaixo emprega LettuceConnectionFactory, que permite especificar o nome de usuário e a senha separadamente.

A estrutura de arquivos do projeto é a seguinte:

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.

Crie a classe de configuração principal RedisConfig.java. Nesta classe, crie e configure manualmente um bean RedisConnectionFactory com todos os detalhes de conexão. O Spring Boot detecta esse bean automaticamente e o utiliza para todas as operações relacionadas ao 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;
    }
}

Crie a classe principal da aplicação MainApplication.java. Ela serve como ponto de entrada para a aplicação 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);
    }
}

Crie a classe de execução de testes RedisTestRunner.java. Esta classe executa automaticamente após a inicialização da aplicação Spring Boot, realiza operações de leitura e escrita no Redis e imprime os 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 a dependência:
```
pip install redis
```

Exemplo de código: A versão 4,2+ do redis-py aceita um parâmetro username separado. Em versões anteriores, passe a string username:password como o 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 a dependência:
```
go get github.com/go-redis/redis/v8
```

Exemplo de código: O go-redis aceita um campo Username separado (recomendado). Em versões anteriores, passe a string username:password como o 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 a dependência:
```
npm install redis
```

Exemplo de código: O node-redis permite incluir as informações de autenticação diretamente na URL de conexão.

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 a dependência: Geralmente, instale essa extensão por meio de um gerenciador de pacotes. Por exemplo, no CentOS:
```
sudo yum install php-redis
```

Exemplo de código: O método auth da extensão PhpRedis aceita um array contendo o nome de usuário e a senha.

<?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 a dependência: Compile e instale a partir do código-fonte.

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

Exemplo de código: Use redisCommand para executar o comando AUTH. Use o 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 e execute o 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

Conexão com o DMS

Conectar ao Orca

Acesse o console do Database Management (DMS).
Na barra de navegação superior, escolha Data Assets > Instances.
Clique em Add, selecione Third-party Cloud/Self-managed e escolha Redis na seção NoSQL Database.
Clique em Next para acessar a página de informações básicas. Configure os parâmetros conforme descrito abaixo:
- Em Instance Source, selecione VPC PrivateLine. Em Region, escolha a região onde o cluster PolarDB está localizado ou uma região próxima. Para VPC ID, selecione o ID da VPC na página de detalhes do cluster PolarDB. Em Logon Address, insira o endpoint do Orca.
- Para Access Method, selecione Account + password login. Insira a conta do banco de dados e a senha da conta Orca.
- Após preencher as informações, clique em Test Connectivity. Uma mensagem de sucesso será exibida se a conexão for estabelecida corretamente.
Clique em Next para ir à página Advanced Information e defina as configurações conforme necessário.

Nota
Atualmente, o Orca não oferece suporte à criptografia SSL.
Clique em Submit. Se a operação for bem-sucedida, a instância Orca entrará no modo Secure Management.

Gerenciar dados

Na barra de navegação superior, escolha SQL Console e selecione o cluster Orca gerenciado.
O Orca atualmente aceita apenas um banco de dados lógico Redis, o DB0. Caso não visualize o banco de dados DB0, clique em Refresh / Sync Dictionary.
Agora é possível gerenciar o Orca usando o DMS.

Por exemplo, execute o comando ping key01 no SQL Console. O valor de retorno PONG indica conexão estabelecida com sucesso.