Share via

Usar o Spring Data R2DBC com o Banco de Dados SQL do Azure

  • Artigo

Este artigo demonstra a criação de um aplicativo de exemplo que usa o Spring Data R2DBC para armazenar e recuperar informações no Banco de Dados SQL do Azure usando a implementação R2DBC para Microsoft SQL Server do repositório GitHub r2dbc-mssql.

O R2DBC permite utilizar APIs reativas nas bases de dados relacionais tradicionais. Você pode usá-lo com o Spring WebFlux para criar aplicativos Spring Boot totalmente reativos que usam APIs sem bloqueio. Ele fornece melhor escalabilidade do que a abordagem clássica de "um thread por conexão".

Pré-requisitos

  • Utilitário sqlcmd.

  • cURL ou um utilitário HTTP semelhante para testar a funcionalidade.

Veja o aplicativo de exemplo

Neste artigo, você codificará um aplicativo de exemplo. Se você quiser ir mais rápido, este aplicativo já está codificado e disponível em https://github.com/Azure-Samples/quickstart-spring-data-r2dbc-sql-server.

Preparar o ambiente de trabalho

Primeiro, configure algumas variáveis de ambiente ao utilizar os seguintes comandos:

export AZ_RESOURCE_GROUP=database-workshop
export AZ_DATABASE_NAME=<YOUR_DATABASE_NAME>
export AZ_LOCATION=<YOUR_AZURE_REGION>
export AZ_SQL_SERVER_ADMIN_USERNAME=spring
export AZ_SQL_SERVER_ADMIN_PASSWORD=<YOUR_AZURE_SQL_ADMIN_PASSWORD>
export AZ_SQL_SERVER_NON_ADMIN_USERNAME=nonspring
export AZ_SQL_SERVER_NON_ADMIN_PASSWORD=<YOUR_AZURE_SQL_NON_ADMIN_PASSWORD>
export AZ_LOCAL_IP_ADDRESS=<YOUR_LOCAL_IP_ADDRESS>

Substitua os marcadores de posição pelos seguintes valores, que são utilizados ao longo deste artigo:

  • <YOUR_DATABASE_NAME>: O nome do seu servidor do Banco de Dados SQL do Azure, que deve ser exclusivo no Azure.
  • <YOUR_AZURE_REGION>: A região do Azure que você usará. Pode utilizar a região eastus por predefinição, mas recomendamos que configure uma região mais próxima do local onde vive. Você pode ver a lista completa de regiões disponíveis usando az account list-locations.
  • <AZ_SQL_SERVER_ADMIN_PASSWORD> e <AZ_SQL_SERVER_NON_ADMIN_PASSWORD>: A senha do seu servidor do Banco de Dados SQL do Azure, que deve ter no mínimo oito caracteres. Os caracteres devem ser de três das seguintes categorias: letras maiúsculas inglesas, letras minúsculas inglesas, números (0-9) e caracteres não alfanuméricos (!, $, #, % e assim por diante).
  • <YOUR_LOCAL_IP_ADDRESS>: O endereço IP do seu computador local, a partir do qual irá executar a sua aplicação Spring Boot. Uma maneira conveniente de encontrá-lo é abri-whatismyip.akamai.com.

Em seguida, crie um grupo de recursos usando o seguinte comando:

az group create \
    --name $AZ_RESOURCE_GROUP \
    --location $AZ_LOCATION \
    --output tsv

Criar uma instância do Banco de Dados SQL do Azure

Em seguida, crie uma instância gerenciada do servidor do Banco de Dados SQL do Azure executando o seguinte comando.

Nota

A senha do MS SQL deve atender a critérios específicos e a instalação falhará com uma senha não compatível. Para obter mais informações, consulte Política de senha.

az sql server create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name $AZ_DATABASE_NAME \
    --location $AZ_LOCATION \
    --admin-user $AZ_SQL_SERVER_ADMIN_USERNAME \
    --admin-password $AZ_SQL_SERVER_ADMIN_PASSWORD \
    --output tsv

Configurar uma regra de firewall para o servidor do Banco de Dados SQL do Azure

As instâncias do Banco de Dados SQL do Azure são protegidas por padrão. O serviço tem uma firewall que não permite ligações de entrada. Para poder usar seu banco de dados, você precisa adicionar uma regra de firewall que permitirá que o endereço IP local acesse o servidor de banco de dados.

Como você configurou seu endereço IP local no início deste artigo, você pode abrir o firewall do servidor executando o seguinte comando:

az sql server firewall-rule create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name $AZ_DATABASE_NAME-database-allow-local-ip \
    --server $AZ_DATABASE_NAME \
    --start-ip-address $AZ_LOCAL_IP_ADDRESS \
    --end-ip-address $AZ_LOCAL_IP_ADDRESS \
    --output tsv

Se estiver a ligar ao servidor da Base de Dados SQL do Azure a partir do Subsistema Windows para Linux (WSL) num computador Windows, terá de adicionar o ID de anfitrião WSL à firewall.

Obtenha o endereço IP da sua máquina host executando o seguinte comando no WSL:

cat /etc/resolv.conf

Copie o endereço IP após o termo nameservere, em seguida, use o seguinte comando para definir uma variável de ambiente para o endereço IP WSL:

export AZ_WSL_IP_ADDRESS=<the-copied-IP-address>

Em seguida, use o seguinte comando para abrir o firewall do servidor para seu aplicativo baseado em WSL:


az sql server firewall-rule create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name $AZ_DATABASE_NAME-database-allow-local-ip-wsl \
    --server $AZ_DATABASE_NAME \
    --start-ip-address $AZ_WSL_IP_ADDRESS \
    --end-ip-address $AZ_WSL_IP_ADDRESS \
    --output tsv

Configurar um banco de dados SQL do Azure

O servidor do Banco de Dados SQL do Azure que você criou anteriormente está vazio. Não tem nenhuma base de dados que possa utilizar com a aplicação do Spring Boot. Crie um novo banco de dados chamado demo executando o seguinte comando:

az sql db create \
    --resource-group $AZ_RESOURCE_GROUP \
    --name demo \
    --server $AZ_DATABASE_NAME \
    --output tsv

Criar um usuário não administrador do banco de dados SQL e conceder permissão

Esta etapa criará um usuário não administrador e concederá todas as permissões no demo banco de dados a ele.

Crie um script SQL chamado create_user.sql para criar um usuário não administrador. Adicione o seguinte conteúdo e salve-o localmente:

cat << EOF > create_user.sql
USE demo;
GO
CREATE USER $AZ_SQL_SERVER_NON_ADMIN_USERNAME WITH PASSWORD='$AZ_SQL_SERVER_NON_ADMIN_PASSWORD'
GO
GRANT CONTROL ON DATABASE::demo TO $AZ_SQL_SERVER_NON_ADMIN_USERNAME;
GO
EOF

Em seguida, use o seguinte comando para executar o script SQL para criar o usuário não administrador:

sqlcmd -S $AZ_DATABASE_NAME.database.windows.net,1433  -d demo -U $AZ_SQL_SERVER_ADMIN_USERNAME -P $AZ_SQL_SERVER_ADMIN_PASSWORD  -i create_user.sql

Nota

Para obter mais informações sobre como criar usuários do banco de dados SQL, consulte CREATE USER (Transact-SQL).

Criar uma aplicação Spring Boot reativa

Para criar um aplicativo Spring Boot reativo, usaremos o Spring Initializr. A aplicação que iremos criar utiliza:

  • Bota de mola 2.7.11.
  • As seguintes dependências: Spring Reative Web (também conhecido como Spring WebFlux) e Spring Data R2DBC.

Gerar a aplicação com o Spring Initializr

Gere o aplicativo na linha de comando executando o seguinte comando:

curl https://start.spring.io/starter.tgz -d dependencies=webflux,data-r2dbc -d baseDir=azure-database-workshop -d bootVersion=2.7.11 -d javaVersion=17 | tar -xzvf -

Adicionar a implementação reativa do driver do Banco de Dados SQL do Azure

Abra o arquivo pom.xml do projeto gerado para adicionar o driver reativo do Banco de Dados SQL do Azure do repositório GitHub r2dbc-mssql.

Após a spring-boot-starter-webflux dependência, adicione o seguinte texto:

<dependency>
    <groupId>io.r2dbc</groupId>
    <artifactId>r2dbc-mssql</artifactId>
    <scope>runtime</scope>
</dependency>

Configurar o Spring Boot para usar o Banco de Dados SQL do Azure

Abra o arquivo src/main/resources/application.properties e adicione o seguinte texto:

logging.level.org.springframework.data.r2dbc=DEBUG

spring.r2dbc.url=r2dbc:pool:mssql://$AZ_DATABASE_NAME.database.windows.net:1433/demo
spring.r2dbc.username=nonspring@$AZ_DATABASE_NAME
spring.r2dbc.password=$AZ_SQL_SERVER_NON_ADMIN_PASSWORD

Substitua as duas $AZ_DATABASE_NAME variáveis e a $AZ_SQL_SERVER_NON_ADMIN_PASSWORD variável pelos valores que você configurou no início deste artigo.

Nota

Para um melhor desempenho, a propriedade é configurada spring.r2dbc.url para usar um pool de conexões usando r2dbc-pool.

Agora você deve ser capaz de iniciar seu aplicativo usando o wrapper Maven fornecido da seguinte maneira:

./mvnw spring-boot:run

Eis uma captura de ecrã da aplicação em execução pela primeira vez:

Screenshot of the running application.

Criar o esquema da base de dados

Dentro da classe principal DemoApplication , configure um novo Spring bean que criará um esquema de banco de dados, usando o seguinte código:

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.core.io.ClassPathResource;
import org.springframework.data.r2dbc.connectionfactory.init.ConnectionFactoryInitializer;
import org.springframework.data.r2dbc.connectionfactory.init.ResourceDatabasePopulator;

import io.r2dbc.spi.ConnectionFactory;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

    @Bean
    public ConnectionFactoryInitializer initializer(ConnectionFactory connectionFactory) {
        ConnectionFactoryInitializer initializer = new ConnectionFactoryInitializer();
        initializer.setConnectionFactory(connectionFactory);
        ResourceDatabasePopulator populator = new ResourceDatabasePopulator(new ClassPathResource("schema.sql"));
        initializer.setDatabasePopulator(populator);
        return initializer;
    }
}

Este Spring bean usa um arquivo chamado schema.sql, portanto, crie esse arquivo na pasta src/main/resources e adicione o seguinte texto:

DROP TABLE IF EXISTS todo;
CREATE TABLE todo (id INT IDENTITY PRIMARY KEY, description VARCHAR(255), details VARCHAR(4096), done BIT);

Pare o aplicativo em execução e inicie-o novamente usando o seguinte comando. Agora, a aplicação irá utilizar a base de dados demo que criou anteriormente e criar uma tabela todo na mesma.

./mvnw spring-boot:run

Aqui está uma captura de tela da tabela do banco de dados enquanto ela está sendo criada:

Screenshot of the creation of the database table.

Codificar a aplicação

Em seguida, adicione o código Java que usará o R2DBC para armazenar e recuperar dados do seu servidor do Banco de Dados SQL do Azure.

Crie uma nova Todo classe Java, ao lado da DemoApplication classe, usando o seguinte código:

package com.example.demo;

import org.springframework.data.annotation.Id;

public class Todo {

    public Todo() {
    }

    public Todo(String description, String details, boolean done) {
        this.description = description;
        this.details = details;
        this.done = done;
    }

    @Id
    private Long id;

    private String description;

    private String details;

    private boolean done;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    public String getDetails() {
        return details;
    }

    public void setDetails(String details) {
        this.details = details;
    }

    public boolean isDone() {
        return done;
    }

    public void setDone(boolean done) {
        this.done = done;
    }
}

Esta classe é um modelo de domínio mapeado na tabela todo que criou anteriormente.

Para gerir essa classe, precisa de um repositório. Defina uma nova TodoRepository interface no mesmo pacote, usando o seguinte código:

package com.example.demo;

import org.springframework.data.repository.reactive.ReactiveCrudRepository;

public interface TodoRepository extends ReactiveCrudRepository<Todo, Long> {
}

Este repositório é um repositório reativo que o Spring Data R2DBC gerencia.

Conclua o aplicativo criando um controlador que possa armazenar e recuperar dados. Implemente uma classe TodoController no mesmo pacote e adicione o seguinte código:

package com.example.demo;

import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

@RestController
@RequestMapping("/")
public class TodoController {

    private final TodoRepository todoRepository;

    public TodoController(TodoRepository todoRepository) {
        this.todoRepository = todoRepository;
    }

    @PostMapping("/")
    @ResponseStatus(HttpStatus.CREATED)
    public Mono<Todo> createTodo(@RequestBody Todo todo) {
        return todoRepository.save(todo);
    }

    @GetMapping("/")
    public Flux<Todo> getTodos() {
        return todoRepository.findAll();
    }
}

Por último, pare a aplicação e inicie-a novamente com o seguinte comando:

./mvnw spring-boot:run

Testar a aplicação

Pode utilizar o cURL para testar a aplicação.

Comece por criar um item "todo" na base de dados ao utilizar o seguinte comando:

curl --header "Content-Type: application/json" \
    --request POST \
    --data '{"description":"configuration","details":"congratulations, you have set up R2DBC correctly!","done": "true"}' \
    http://127.0.0.1:8080

Este comando deve retornar o item criado, conforme mostrado aqui:

{"id":1,"description":"configuration","details":"congratulations, you have set up R2DBC correctly!","done":true}

Em seguida, recupere os dados usando uma nova solicitação cURL com o seguinte comando:

curl http://127.0.0.1:8080

Este comando retornará a lista de itens "todo", incluindo o item que você criou, conforme mostrado aqui:

[{"id":1,"description":"configuration","details":"congratulations, you have set up R2DBC correctly!","done":true}]

Aqui está uma captura de tela dessas solicitações de cURL:

Screenshot of the cURL test.

Parabéns! Você criou um aplicativo Spring Boot totalmente reativo que usa o R2DBC para armazenar e recuperar dados do Banco de Dados SQL do Azure.

Clean up resources (Limpar recursos)

Para limpar todos os recursos usados durante este início rápido, exclua o grupo de recursos usando o seguinte comando:

az group delete \
    --name $AZ_RESOURCE_GROUP \
    --yes

Próximos passos

Para saber mais sobre como implantar um aplicativo Spring Data no Azure Spring Apps e usar a identidade gerenciada, consulte Tutorial: Implantar um aplicativo Spring no Azure Spring Apps com uma conexão sem senha para um banco de dados do Azure.

Para saber mais sobre o Spring e o Azure, avance para o centro de documentação relativa ao Spring no Azure.

Spring no Azure

Consulte também

Para obter mais informações sobre o Spring Data R2DBC, consulte a documentação de referência do Spring.

Para obter mais informações sobre a utilização do Azure com o Java, veja Azure para programadores de Java e Trabalhar com o Azure DevOps e Java.