Uso de Spring Data R2DBC con Azure SQL Database

Artículo
11/25/2024

En este artículo se muestra cómo crear una aplicación de ejemplo que utiliza Spring Data R2DBC para almacenar y recuperar información de Azure SQL Database con la implementación de R2DBC para Microsoft SQL Server del repositorio r2dbc-mysql de GitHub.

R2DBC aporta API reactivas a las bases de datos relacionales tradicionales. Puede usarlo con Spring WebFlux para crear aplicaciones de Spring Boot totalmente reactivas que usan API sin bloqueo. Proporciona una mejor escalabilidad que el enfoque clásico "un subproceso por conexión".

Requisitos previos

Una suscripción a Azure: cree una cuenta gratuita.
Kit de desarrollo de Java (JDK), versión 8 o posterior.
Apache Maven.
Azure CLI.

Utilidad sqlcmd
cURL o una utilidad HTTP similar para probar la funcionalidad.

Consulte la aplicación de ejemplo

En este artículo, se codificará una aplicación de ejemplo. Si desea ir más rápido, esta aplicación ya está codificada y disponible en https://github.com/Azure-Samples/quickstart-spring-data-r2dbc-sql-server.

Preparación del entorno de trabajo

En primer lugar, configure algunas variables de entorno mediante los siguientes 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>

Reemplace los marcadores de posición por los valores siguientes, que se usan a lo largo de este artículo:

<YOUR_DATABASE_NAME>: el nombre del servidor de Azure SQL Database, que debe ser único en Azure.
<YOUR_AZURE_REGION>: región de Azure que va a usar. Puede usar eastus de forma predeterminada, pero se recomienda que configure una región más cercana a la ubicación en la que vive. Puede ver la lista completa de regiones disponibles mediante az account list-locations.
<AZ_SQL_SERVER_ADMIN_PASSWORD> y <AZ_SQL_SERVER_NON_ADMIN_PASSWORD>: la contraseña del servidor de Azure SQL Database, que debe tener un mínimo de ocho caracteres. Debe contener caracteres de tres de las siguientes categorías: Letras del alfabeto inglés mayúsculas y minúsculas, números (0-9) y caracteres no alfanuméricos (!, $, #, %, etc.).
<YOUR_LOCAL_IP_ADDRESS>: dirección IP del equipo local, desde el que se ejecutará la aplicación de Spring Boot. Una manera cómoda de encontrarla es abrir whatismyip.akamai.com.

Nota:

Microsoft recomienda usar el flujo de autenticación más seguro disponible. El flujo de autenticación descrito en este procedimiento, como para bases de datos, memorias caché, mensajería o servicios de inteligencia artificial, requiere un grado de confianza muy alto en la aplicación y conlleva riesgos que no están presentes en otros flujos. Use este flujo solo cuando las opciones más seguras, como las identidades administradas para conexiones sin contraseña o sin claves, no sean viables. En el caso de las operaciones de máquina local, prefiera identidades de usuario para conexiones sin contraseña o sin claves.

A continuación, cree un grupo de recursos con el siguiente comando:

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

Creación de una instancia de Azure SQL Database

A continuación, cree una instancia de servidor de Azure SQL Database administrada mediante la ejecución del comando siguiente.

Nota:

La contraseña de MS SQL tiene que cumplir criterios específicos y se producirá un error en la configuración con una contraseña no compatible. Para obtener más información, vea Password Policy.

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

Configuración de una regla de firewall para el servidor de Azure SQL Database

De forma predeterminada, las instancias de Azure SQL Database están protegidas. Tienen un firewall que no permite ninguna conexión entrante. Para poder usar la base de datos, es necesario agregar una regla de firewall que permita a la dirección IP local acceder al servidor de base de datos.

Como hemos configurado nuestra dirección IP local al principio de este artículo, puede abrir el firewall del servidor con el siguiente 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

Si se conecta al servidor de Azure SQL Database desde el subsistema de Windows para Linux (WSL) en un equipo Windows, debe agregar el identificador de host de WSL al firewall.

Para obtener la dirección IP de la máquina host, ejecute el siguiente comando en WSL:

cat /etc/resolv.conf

Copie la dirección IP que sigue al término nameserver y, a continuación, use el siguiente comando para establecer una variable de entorno para la dirección IP de WSL:

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

A continuación, use el siguiente comando para abrir el firewall del servidor en la aplicación basada en 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

Configuración de una base de datos de Azure SQL

El servidor de Azure SQL Database que creó anteriormente está vacío. No tiene ninguna base de datos que pueda usar con la aplicación Spring Boot. Cree una nueva base de datos llamada demo con el comando siguiente:

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

Creación de un usuario no administrador de base de datos SQL y concesión de permisos

Este paso creará un usuario que no sea administrador y le concederá todos los permisos de la base de datos demo.

Cree un script SQL denominado create_user.sql para crear un usuario que no sea administrador. Agregue el siguiente contenido y guárdelo de forma local:

Nota:

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

A continuación, utilice el siguiente comando para ejecutar el script SQL para crear el usuario no 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 obtener más información sobre cómo crear usuarios de bases de datos SQL, consulte CREATE USER (Transact-SQL).

Creación de una aplicación reactiva de Spring Boot

Para crear una aplicación reactiva de Spring Boot, usaremos Spring Initializr. La aplicación que vamos a crear utiliza:

Spring Boot 2.7.11.
Las dependencias siguientes: Spring Reactive Web (también conocido como Spring WebFlux) y Spring Data R2DBC.

Generación de la aplicación con Spring Initializr

Genere la aplicación en la línea de comandos; para ello, ejecute el siguiente 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 -

Adición de la implementación del controlador reactivo de Azure SQL Database

Abra el archivo pom.xml del proyecto generado para agregar el controlador reactivo de Azure SQL Database desde el repositorio r2dbc-mysql de GitHub.

Después de la dependencia spring-boot-starter-webflux, agregue el siguiente texto:

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

Configuración de Spring Boot para usar Azure SQL Database

Abra el archivo src/main/resources/application.properties y agregue el texto siguiente:

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

Reemplace las dos variables $AZ_DATABASE_NAME y la variable $AZ_SQL_SERVER_NON_ADMIN_PASSWORD por los valores que configuró al principio de este artículo.

Nota:

Para mejorar el rendimiento, la propiedad spring.r2dbc.url está configurada para usar un grupo de conexiones con r2dbc-pool.

Ahora podrá iniciar la aplicación mediante el contenedor de Maven proporcionado, de la siguiente manera:

./mvnw spring-boot:run

Esta es una captura de pantalla de la primera ejecución de la aplicación:

Creación del esquema de la base de datos

Dentro de la clase DemoApplication principal, configure un nuevo bean de Spring que creará el esquema de la base de datos, con el siguiente 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 bean de Spring usa un archivo llamado schema.sql, por lo que debe crear dicho archivo en la carpeta src/main/resources y agregar el siguiente texto:

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

Detenga la aplicación e iníciela de nuevo con el siguiente comando. La aplicación usará ahora la base de datos demo que creó anteriormente y creará la tabla todo dentro de ella.

./mvnw spring-boot:run

Esta es una captura de pantalla de la tabla de base de datos que se está creando:

Incorporación del código de la aplicación

A continuación, agregue el código Java que usará R2DBC para almacenar y recuperar datos del servidor de Azure SQL Database.

Cree la nueva clase Todo de Java junto a la clase DemoApplication, con el siguiente 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 clase es un modelo de dominio asignado a la tabla todo que creó antes.

Para administrar esa clase, necesitará un repositorio. Defina una nueva interfaz TodoRepository en el mismo paquete, con el siguiente código:

package com.example.demo;

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

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

Este es un repositorio reactivo que Spring Data R2DBC administra.

Finalice la aplicación mediante la creación de un controlador que pueda almacenar y recuperar datos. Implemente la clase TodoController en el mismo paquete y agregue el código siguiente:

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, detenga la aplicación e iníciela de nuevo con el siguiente comando:

./mvnw spring-boot:run

Prueba de la aplicación

Puede usar cURL para probar la aplicación.

En primer lugar, cree un nuevo elemento "todo" en la base de datos con el siguiente 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 devolverá el elemento creado, como se muestra aquí:

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

A continuación, recupere los datos mediante una nueva solicitud cURL, con el siguiente comando:

curl http://127.0.0.1:8080

Este comando devolverá la lista de elementos "todo", incluido el elemento que ha creado, como se muestra aquí:

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

Esta es una captura de pantalla de estas solicitudes cURL:

Felicidades. Ha creado una aplicación de Spring Boot totalmente reactiva que usa R2DBC para almacenar y recuperar datos de Azure SQL Database.

Limpieza de recursos

Para limpiar todos los recursos usados durante este inicio rápido, elimine el grupo de recursos mediante el siguiente comando:

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

Pasos siguientes

Para más información sobre la implementación de una aplicación Spring Data en Azure Spring Apps y el uso de la identidad administrada, consulte Tutorial: Implementación de una aplicación spring en Azure Spring Apps con una conexión sin contraseña a una base de datos de Azure.

Para más información acerca de Spring y Azure, vaya al centro de documentación de Azure.

Spring en Azure

Consulte también

Para más información sobre Spring Data R2DBC, consulte la documentación de referencia de Spring.

Para más información sobre el uso de Azure con Java, consulte Azure para desarrolladores de Java y Trabajo con Azure DevOps y Java.

Compartir a través de

Uso de Spring Data R2DBC con Azure SQL Database

Requisitos previos

Consulte la aplicación de ejemplo

Preparación del entorno de trabajo

Creación de una instancia de Azure SQL Database

Configuración de una regla de firewall para el servidor de Azure SQL Database

Configuración de una base de datos de Azure SQL

Creación de un usuario no administrador de base de datos SQL y concesión de permisos

Creación de una aplicación reactiva de Spring Boot

Generación de la aplicación con Spring Initializr

Adición de la implementación del controlador reactivo de Azure SQL Database

Configuración de Spring Boot para usar Azure SQL Database

Creación del esquema de la base de datos

Incorporación del código de la aplicación

Prueba de la aplicación

Limpieza de recursos

Pasos siguientes

Consulte también

Comentarios

Recursos adicionales