Get Started with the Spring Boot Starter

Create a Spring Boot project

Create a Spring Boot 4.x project named MongoHibernateSpringQuickstart. You can generate the project by using the Spring Initializr or create it in your IDE.

The Spring Initializr generates a main application class named after your project, such as MongoHibernateSpringQuickstartApplication.java. If you use the Spring Initializr to generate your project, delete the auto-generated main application class file. You will create a main application file for this project named Movie Application later in this tutorial. If your project contains two main application classes, your application fails to start with an Unable to find a single main class error.

Add the starter dependency

For Maven projects, add the following dependency to your pom.xml file:

<dependencies>
   <dependency>
      <groupId>org.mongodb</groupId>
      <artifactId>mongodb-hibernate-spring-boot-starter</artifactId>
      <version>1.0.0</version>
   </dependency>
</dependencies>

For Gradle projects, add the following dependency to your build.gradle file:

dependencies {
   implementation("org.mongodb:mongodb-hibernate-spring-boot-starter:1.0.0")
}

Override the managed Hibernate ORM version

The starter requires Hibernate ORM 7.4 or later. Spring Boot manages the Hibernate ORM version through its bill of materials (BOM), and some Spring Boot 4.x releases manage an earlier version of Hibernate ORM than the version that the starter requires. If the managed version is earlier than 7.4, your application fails to start and the Hibernate ORM extension throws a NoSuchMethodError.

To override the managed version in a Maven project, add the following property to your pom.xml file:

<properties>
   <hibernate.version>7.4.7.Final</hibernate.version>
</properties>

To override the managed version in a Gradle project, add the following line to your build.gradle file:

ext['hibernate.version'] = '7.4.7.Final'

Reload or sync your project to complete the installation.

Set your application properties

In your project's src/main/resources directory, open the application.properties file and add the following properties:

spring.jpa.database-platform=MongoDB
spring.mongodb.uri=<connection string>
spring.jpa.properties.com.mongodb.hibernate.semantics.nulls=MQL

Replace the <connection string> placeholder with the sample_mflix connection string that you created in the Create a Connection String step of the Get Started with the Hibernate ORM Extension tutorial. Your connection string should resemble the following example:

mongodb+srv://<db_username>:<db_password>@<cluster>/sample_mflix?<options>

The application properties you set do the following:

• spring.jpa.database-platform: Activates the starter. The starter remains inactive unless you set this property to MongoDB.

• spring.mongodb.uri: Configures the MongoClient instance that the starter reuses. The starter does not create a client of its own.

• spring.jpa.properties.com.mongodb.hibernate.semantics.nulls: Declares the null-comparison semantics that queries use. This property is required and its only supported value is MQL.

Define your Movie entity

In your project's src/main/java/org/example directory, create a file called Movie.java and paste the following code into it:

package org.example;
import com.mongodb.hibernate.annotations.ObjectIdGenerator;
import org.bson.types.ObjectId;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
@Entity
@Table(name = "movies")
public class Movie {
    @Id
    @ObjectIdGenerator
    private ObjectId id;
    private String title;
    private int year;
    public Movie() {
    }
    public Movie(String title, int year) {
        this.title = title;
        this.year = year;
    }
    public ObjectId getId() {
        return id;
    }
    public String getTitle() {
        return title;
    }
    public void setTitle(String title) {
        this.title = title;
    }
    public int getYear() {
        return year;
    }
    public void setYear(int year) {
        this.year = year;
    }
}

This entity represents the sample_mflix.movies collection from the Atlas sample datasets. The starter scans your application's main package for entities, so you do not need to register the entity.

Define your repository

In the same directory, create a file called MovieRepository.java and paste the following code into it:

package org.example;
import org.bson.types.ObjectId;
import org.springframework.data.jpa.repository.JpaRepository;
import java.util.List;
public interface MovieRepository extends JpaRepository<Movie, ObjectId> {
    List<Movie> findByTitle(String title);
}

The starter enables Spring Data JPA repositories without a SQL DataSource, so Spring Boot implements the MovieRepository interface for you.

Define your application class

In the same directory, create a file called MovieApplication.java and paste the following code into it:

package org.example;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
@SpringBootApplication
public class MovieApplication {
    public static void main(String[] args) {
        SpringApplication.run(MovieApplication.class, args);
    }
    @Bean
    CommandLineRunner run(MovieRepository repository) {
        return args -> {
            for (Movie movie : repository.findByTitle("Little Women")) {
                System.out.println("Title: " + movie.getTitle()
                        + ", Year: " + movie.getYear());
            }
        };
    }
}

This class runs a repository query at startup and prints each matching movie.