Para agentes de IA: hay un índice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las páginas están disponibles agregando .md a cualquier ruta URL.

Configurar el Spring Boot Starter

En esta guía, puede aprender a configurar el Spring Boot starter que proporciona la extensión de MongoDB para Hibernate ORM. Para aprender a instalar el iniciador y crear una aplicación que lo utilice, consulte Introducción al iniciador de Spring Boot.

Para activar el iniciador, establezca la propiedad spring.jpa.database-platform en MongoDB en el archivo application.properties de su aplicación, como se muestra en el siguiente ejemplo:

spring.jpa.database-platform=MongoDB

El iniciador utiliza esta propiedad estándar de Spring Boot y no requiere ninguna configuración dedicada propia. Cuando la propiedad tiene cualquier otro valor o no está definida, el iniciador permanece inactivo. Un iniciador inactivo no afecta a su aplicación.

El iniciador reutiliza la instancia MongoClient que Spring Boot crea a partir de las propiedades spring.mongodb.*. El iniciador no crea un cliente propio y no gestiona el ciclo de vida del cliente, por lo que su aplicación utiliza un pool de conexiones para la persistencia de Java Persistence API (JPA), la verificación de estado, las métricas y cualquier otro componente que utilice el cliente.

El iniciador utiliza el nombre de la base de datos establecido en la propiedad spring.mongodb.database. Si no establece esa propiedad, el iniciador utiliza el nombre de la base de datos en la cadena de conexión que estableció en la propiedad spring.mongodb.uri.

Para personalizar este cliente, declare un MongoClientSettingsBuilderCustomizer bean. Esta interfaz personaliza la instancia MongoClientSettings.Builder antes de que Spring Boot cree el cliente.

El iniciador utiliza las propiedades estándar spring.jpa.*. La siguiente tabla describe las propiedades comúnmente utilizadas:

Propiedad
Descripción

spring.jpa.hibernate.ddl-auto

Especifica la acción de gestión del esquema que Hibernate ORM realiza al empresa emergente. El valor por defecto para las unidades de persistencia respaldadas por MongoDB es none.

spring.jpa.show-sql

Especifica si Hibernate ORM registra las instrucciones que genera.

spring.jpa.properties.*

Pasa las propiedades de configuración de Hibernate ORM directamente a Hibernate ORM.

spring.jpa.open-in-view

Especifica si el contexto de persistencia permanece abierto durante una solicitud web. Esta propiedad está habilitada por defecto en aplicaciones web de servlet.

spring.data.jpa.repositories.enabled

Especifica si el starter habilita el escaneo de repositorios de Spring Data JPA. Esta propiedad está habilitada por defecto.

También puede declarar HibernatePropertiesCustomizer y EntityManagerFactoryBuilderCustomizer beans para modificar la configuración que el iniciador compila. La interfaz HibernatePropertiesCustomizer personaliza las propiedades de Hibernate ORM que el iniciador pasa a la EntityManagerFactory, y la interfaz EntityManagerFactoryBuilderCustomizer personaliza el generador que lo crea.

El iniciador busca entidades en los paquetes que registra mediante la @EntityScan anotación. Si no registra paquetes, el iniciador escanea el paquete de su clase @SpringBootApplication y sus subpaquetes.

Declarar la anotación @EntityScan en la clase principal de su aplicación, como se muestra en el siguiente ejemplo:

@SpringBootApplication@EntityScan("org.example.model") public class MovieApplication { // ...}

El iniciador habilita los repositorios de Spring Data JPA en el mismo alcance del paquete. Si declara usted mismo la anotación @EnableJpaRepositories, su declaración prevalece sobre la del iniciador.

El iniciador habilita estos repositorios sin un SQL DataSource y no incluye un pool de conexiones SQL. Una aplicación exclusiva de MongoDB, por lo tanto, no requiere ninguna propiedad spring.datasource.url, y Spring Boot no utiliza su clase DataSourceAutoConfiguration.

A diferencia de una aplicación SQL Spring Boot, que asigna las propiedades de entidad a los nombres de columna snake_case por defecto, el iniciador asigna cada propiedad de entidad a un campo de documento con el mismo nombre. Una entidad que se inicia a través del iniciador persiste de la misma manera que una entidad que se inicia directamente a través de Hibernate ORM.

Para utilizar una estrategia de nomenclatura diferente, establezca la estrategia explícitamente en el archivo application.properties de su aplicación, como se muestra en el siguiente ejemplo:

spring.jpa.hibernate.naming.physical-strategy=org.hibernate.boot.model.naming.PhysicalNamingStrategySnakeCaseImpl

Advertencia

Migrar documentos antes de cambiar la estrategia de nomenclatura

Cambiar la estrategia de nomenclatura afecta solo a los documentos que su aplicación guardar después del cambio de estrategia. MongoDB no migra los documentos existentes, por lo que una colección puede contener documentos que utilizan múltiples tipos de nombres de campo. Migre sus documentos existentes antes de cambiar la estrategia de nomenclatura.

Cuando el iniciador está activo pero no puede configurar una unidad de persistencia, informa del error al inicio. En la siguiente tabla se describen estos errores:

Error
Resolución

No hay MongoClient disponible para que el iniciador lo utilice.

Agregue la dependencia spring-boot-mongodb y configure las propiedades spring.mongodb.*, o declare un bean MongoClient en su aplicación.

No hay nombre de base de datos disponible.

Agregue el nombre de la base de datos a la cadena de conexión en la propiedad spring.mongodb.uri, establezca la propiedad spring.mongodb.database o establezca el nombre utilizando un bean MongoConfigurationContributor.

Para conectarse a través de un cliente que solo utiliza el iniciador, como un cliente con credenciales diferentes, declare un bean MongoConfigurationContributor que establezca el cliente y el nombre de la base de datos. Cuando declares este bean, el iniciador utiliza tu cliente en lugar del cliente gestionado por Spring.

Si declara más de un bean MongoConfigurationContributor, el iniciador los aplica en el orden que especifique utilizando la anotación @Order, y el último bean que establece un valor determina ese valor.

El iniciador tiene las siguientes limitaciones:

  • La anotación @DataJpaTest no es compatible. Para probar con MongoDB, utilice la anotación @SpringBootTest, que carga el contexto completo de su aplicación.

  • El iniciador configura una única unidad de persistencia. Para usar más de una unidad de persistencia, configure las unidades adicionales usted mismo.