Connect to Orca and manage data - PolarDB: Central de Documentação do Alibaba Cloud

PolarDB for MySQL oferece o recurso Orca, compatível com o protocolo Redis, que permite a conexão ao banco de dados por meio dos principais clientes Redis. Este tópico orienta sobre os preparativos para a conexão e fornece exemplos de código de conexão do cliente para várias linguagens de programação populares.

Preparativos

Antes de se conectar ao recurso Orca, verifique se concluiu os seguintes preparativos:

Ative o recurso Orca no seu cluster PolarDB: ativou o recurso Orca.
Adicione o endereço IP ou o bloco CIDR do cliente à lista de permissões do cluster PolarDB.
crie uma conta Orca separada para acessar o recurso Orca.
Obtenha o endpoint do recurso Orca.

Notas de uso

Diferenças no mecanismo de autenticação: o Orca e o Redis nativo usam mecanismos de autenticação diferentes. O Orca não tem um usuário padrão. Todas as conexões exigem autenticação com uma conta do Orca criada no console.
Compatibilidade do comando AUTH: para garantir a compatibilidade com clientes que aceitam apenas autenticação baseada em senha, o comando AUTH do Orca aceita dois formatos. Ao configurar um cliente, escolha o método de autenticação compatível com ele.
- AUTH <username> <password>: o formato padrão. Forneça o nome de usuário e a senha separadamente.
- AUTH <username>:<password>: o formato de compatibilidade. Concatene o nome de usuário e a senha com dois pontos : e forneça a string combinada como o valor do parâmetro de senha.
Compatibilidade do comando HELLO: assim como o comando AUTH, a parte de autenticação do comando HELLO também aceita os dois formatos descritos acima.
- HELLO <protover> AUTH <username> <password>
- HELLO <protover> AUTH <username>:<password>

Conectar usando o redis-cli

instale o redis-cli: para instalar o redis-cli no seu dispositivo cliente, consulte tutorial de instalação do redis-cli.
Conecte-se ao recurso Orca: execute o comando a seguir. Substitua o endpoint e a porta no comando pelas suas informações reais.
```
redis-cli -h pz-****************.rwlb.rds.aliyuncs.com -p 6379
```
Autentique a conexão: depois que a conexão for estabelecida, use o comando AUTH para autenticação. Os dois formatos a seguir são aceitos. Substitua os espaços reservados pela sua 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
```
Se o resultado for OK, a conexão e a autenticação foram bem-sucedidas.

Conectar usando bibliotecas de cliente

Conecte-se a partir da sua aplicação consultando os exemplos a seguir, de acordo com a linguagem de programação utilizada.

Java (Jedis)

Adicione as dependências (Maven):

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

Exemplo de código: para garantir a compatibilidade com a configuração do Jedis, que aceita apenas um 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 information
        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 permite definir o nome de usuário e a senha separadamente. Recomendamos este método.

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

Adicione as dependências (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> <!-- 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 -->
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

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

Configuração com o `application.yml`

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

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: no diretório src/main/resources/, crie um arquivo application.yml. Este 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. Este é o ponto de entrada da 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 teste, RedisTestRunner.java. Essa classe é executada 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 ===");
    }
}

Configuração com Java Config

Se usar uma versão anterior do Spring ou tiver requisitos personalizados, use uma classe de configuração Java. Como o Jedis atua como cliente subjacente, ainda é necessário concatenar o nome de usuário e a senha para a autenticação.

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. Nessa classe, crie manualmente uma instância (bean) de RedisConnectionFactory e forneça todos os detalhes de conexão. O Spring Boot detecta automaticamente esse bean e o utiliza para configurar todas as operações relacionadas ao Redis, como o 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 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 preceding configuration
        LettuceConnectionFactory lettuceFactory = new LettuceConnectionFactory(redisConfig);
        // Optional: If you do not call afterPropertiesSet, the Spring container calls it automatically when the bean is initialized.
        // lettuceFactory.afterPropertiesSet();
        // 4. Return the configured connection factory instance
        return lettuceFactory;
    }
}

crie a classe principal da aplicação, MainApplication.java. Este é o ponto de entrada da 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 teste, RedisTestRunner.java. Essa classe é executada 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: o redis-py 4.2 e versões posteriores aceitam um parâmetro username separado. Se usar uma versão anterior, use o formato username:password como valor do parâmetro password.

import redis
# Orca connection information
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 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)

instale a dependência:
```
go get github.com/go-redis/redis/v8
```

Exemplo de código: o go-redis aceita um campo Username separado, método que recomendamos. Se a versão do cliente for anterior, use username:password como valor do 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 na URL de conexão.

import { createClient } from 'redis';
// Orca connection information
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: a extensão costuma ser instalada por meio de um gerenciador de pacotes. Por exemplo, no CentOS:
```
sudo yum install php-redis
```

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

<?php
$redis = new Redis();
// Orca connection information
$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 source.

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

Exemplo de código: use redisCommand e execute o comando AUTH. Use o formato concatenado 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 (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. Authenticate (corrected part)
    // 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 whether 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 authentication succeeds, remember to release 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);
    }
    // hiredis returns, for a successful SET command, a status (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.

# 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

Conectar usando o DMS

Conectar ao Orca

acesse o Data Management (DMS).
Na barra de navegação superior, escolha Data Assets > Instances.
Clique em Add, selecione Third-party Cloud/Self-managed e, em seguida, selecione Redis para o banco de dados NoSQL.
Clique em Next para acessar a página de configuração de informações básicas e defina os parâmetros conforme mostrado na figura a seguir.
- Instance Source: selecione VPC PrivateLine. Em Region, selecione a região onde o seu cluster PolarDB está hospedado ou uma região próxima. Em VPC ID, selecione a VPC na página de detalhes do seu cluster PolarDB. Em Logon Address, insira o endpoint do Orca.
- Access Method: selecione Security Hosting + Manual. insira o nome de usuário e a senha da conta do Orca que você criou.
- Após inserir as informações, clique em Test Connectivity. Caso não ocorram exceções, uma mensagem indicará que a conexão foi bem-sucedida.
Clique em Next para acessar a página Advanced Information e defina as configurações de acordo com suas necessidades.

Nota
Atualmente, o Orca não oferece suporte à ativação de SSL.
Clique em envie. Caso não ocorram exceções, o Orca entrará no estado de hospedagem de segurança.

gerencie dados

Na barra de navegação superior, escolha Submit e selecione o cluster Orca com a hospedagem concluída.
Atualmente, o Orca oferece suporte a apenas um banco de dados lógico Redis, o DB0. Se o banco de dados atual DB0 não estiver visível, clique em Refresh / Sync Dictionary.
Caso não ocorram exceções, você poderá usar o DMS para gerencie o Orca.

Por exemplo, no SQL console, execute o comando ping key01. Se o resultado for PONG, a conexão foi bem-sucedida.

Preparativos

Notas de uso

Conectar usando o redis-cli

Conectar usando bibliotecas de cliente

Java (Jedis)

Java (Lettuce)

Java (Spring Data Redis)

Configuração com o application.yml

Configuração com Java Config

Python (redis-py)

Go (go-redis)

Node.js (node-redis)

PHP (PhpRedis)

C (Hiredis)

Conectar usando o DMS

Conectar ao Orca

gerencie dados

Configuração com o `application.yml`