Spring Boot with MongoDB: Spring Data MongoDB in Practice for Production Systems

MongoDB has become the go-to NoSQL database for applications that need flexible schemas, horizontal scaling, and high write throughput. When you pair it with Spring Boot, you get a powerful combination that handles everything from simple CRUD to complex geospatial queries. But here's the thing: many developers treat Mongo like a relational database, and that's where the pain starts. In this tutorial, we'll build a real-world SaaS billing system—think subscription plans, usage tracking, and invoice generation. You'll learn how to model documents for performance, use Spring Data MongoDB's repository and template APIs effectively, and avoid the pitfalls that have caused production outages for teams I've worked with. We'll cover indexing strategies, transactions (yes, they exist in Mongo but with caveats), and how to debug slow queries using MongoDB's explain plan. By the end, you'll have a solid mental model for when to use embedded documents versus references, and how to leverage Spring Data MongoDB's reactive support for high-throughput scenarios. This isn't a hello-world tutorial; it's about building something that won't fall over at 3 AM on a Saturday.

Setting Up Spring Data MongoDB with a Realistic Domain

Let's build a billing system. We have customers, subscription plans, and invoices. The key decision: how to model relationships. In MongoDB, you embed when data is always accessed together and rarely changes independently. For example, subscription plan details are embedded in the customer document because you always show the plan name and price when viewing a customer. But invoices are separate collections because they grow unbounded and you query them independently. Here's how we set up the dependencies in your pom.xml. We use Spring Boot 3.2.1 and the reactive MongoDB driver for better throughput, though we'll stick to imperative code in this tutorial for clarity. The spring-boot-starter-data-mongodb artifact pulls in everything you need: the driver, Spring Data MongoDB, and auto-configuration. Add this to your pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-mongodb</artifactId>
</dependency>
<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>mongodb-driver-sync</artifactId>
    <version>4.11.1</version>
</dependency>

What the Official Docs Won't Tell You

The official Spring Data MongoDB documentation is thorough, but it glosses over three realities. First, MongoRepository is great for simple CRUD but becomes a performance trap when you rely on derived query methods with multiple fields. Each derived method generates a query that may or may not use an index. Second, the @Document annotation's collection attribute is case-sensitive on Linux systems; 'Invoice' and 'invoice' are different collections. Third, and most painful, transactions in MongoDB require a replica set. You cannot run transactions on a standalone instance. In development, we use Docker Compose with a three-node replica set. Here's how to configure application.properties for a replica set connection string. The key is the ?replicaSet=rs0 parameter. Without it, transactions will silently fail with a vague 'Transaction numbers are only allowed on a replica set member' error.

spring.data.mongodb.uri=mongodb://localhost:27017,localhost:27018,localhost:27019/billing_db?replicaSet=rs0
spring.data.mongodb.uuid-representation=STANDARD
spring.data.mongodb.auto-index-creation=true

Document Modeling: Embedding vs. Referencing

The most critical design decision in MongoDB is how to structure your documents. For our billing system, consider a customer document. We embed the subscription plan details because when you fetch a customer, you always need the plan name and price. But we reference invoices via a list of ObjectId references. Why? Invoices can grow to thousands per customer. Embedding them would exceed the 16MB document limit and force unnecessary data transfer when you only need the customer's name. Here's the Customer document class. Note the use of @DocumentReference for invoices. This tells Spring Data MongoDB to store only the IDs in the customer document, not the full invoice documents. The plan object is embedded directly. This is a hybrid model that balances read performance with document size.

@Document(collection = "customers")
public record Customer(
    @Id String id,
    String name,
    String email,
    @Field("plan") SubscriptionPlan plan,  // Embedded
    @DocumentReference(lazy = true) List<Invoice> invoices,  // Referenced
    LocalDateTime createdAt
) {}

public record SubscriptionPlan(
    String planName,
    BigDecimal monthlyPrice,
    int maxUsers
) {}

Advanced Querying with MongoTemplate

While MongoRepository handles 80% of queries, you'll need MongoTemplate for the rest. Aggregations, custom update operations, and geospatial queries are where MongoTemplate shines. In our billing system, we need to calculate monthly revenue per plan. That's a pipeline: group invoices by plan name, sum the amounts, and sort. Here's how to do it with MongoTemplate's aggregate method. The Aggregation class provides a fluent API that mirrors MongoDB's aggregation pipeline stages. Notice how we use TypedAggregation to specify the input and output types. This avoids casting and makes the code self-documenting. The result is a list of RevenueByPlan records.

@Repository
public class BillingRepository {
    private final MongoTemplate mongoTemplate;

    public BillingRepository(MongoTemplate mongoTemplate) {
        this.mongoTemplate = mongoTemplate;
    }

    public List<RevenueByPlan> calculateMonthlyRevenue(YearMonth month) {
        Aggregation agg = Aggregation.newAggregation(
            Aggregation.match(Criteria.where("createdAt")
                .gte(month.atDay(1).atStartOfDay())
                .lt(month.plusMonths(1).atDay(1).atStartOfDay())),
            Aggregation.group("planName").sum("amount").as("totalRevenue"),
            Aggregation.sort(Sort.by(Sort.Direction.DESC, "totalRevenue"))
        );
        AggregationResults<RevenueByPlan> results = mongoTemplate.aggregate(
            agg, "invoices", RevenueByPlan.class);
        return results.getMappedResults();
    }
}

public record RevenueByPlan(String planName, BigDecimal totalRevenue) {}

Transactions: When and How to Use Them

MongoDB transactions are not ACID in the traditional sense—they are snapshot-isolated and have a 60-second default timeout. Use them sparingly. In our billing system, we need to atomically create an invoice and update the customer's usage counter. If the invoice creation fails, we don't want to increment the counter. Here's how to use Spring's @Transactional annotation with MongoDB. The key requirement: your MongoTemplate bean must be configured with a session. Spring Data MongoDB handles this automatically if you use a replica set connection. The @Transactional annotation wraps the method in a session. Note that you cannot call other transactional methods within the same transaction if they use different MongoTemplate instances. Always use the same MongoTemplate bean.

@Service
public class BillingService {
    private final MongoTemplate mongoTemplate;

    @Transactional
    public Invoice createInvoiceAndUpdateUsage(String customerId, BigDecimal amount) {
        Customer customer = mongoTemplate.findById(customerId, Customer.class);
        Invoice invoice = new Invoice(customerId, amount, LocalDateTime.now());
        mongoTemplate.insert(invoice);
        
        Query query = Query.query(Criteria.where("id").is(customerId));
        Update update = new Update().inc("usageCount", 1);
        mongoTemplate.updateFirst(query, update, Customer.class);
        
        return invoice;
    }
}

Indexing Strategies for Query Performance

Without proper indexes, MongoDB becomes a slow, expensive table scan machine. In our billing system, the most common queries are: find invoices by customerId and status, and find customers by email. For the first, a compound index on (customerId, status) is optimal. For the second, a unique index on email is critical for both performance and data integrity. Spring Data MongoDB supports index creation via @Indexed and @CompoundIndex annotations. Here's how to define them on your document classes. The @CompoundIndex annotation accepts an array of field names in order. The order matters: MongoDB can use the index for queries on customerId alone, but not for status alone. Always place the most selective field first. For the email index, we set unique=true to prevent duplicate emails at the database level, which is faster than application-level checks.

@Document(collection = "invoices")
@CompoundIndex(name = "customer_status_idx", def = "{'customerId': 1, 'status': 1}")
public record Invoice(
    @Id String id,
    String customerId,
    BigDecimal amount,
    String status,  // "PENDING", "PAID", "CANCELLED"
    LocalDateTime createdAt
) {}

@Document(collection = "customers")
public record Customer(
    @Id String id,
    @Indexed(unique = true) String email,
    // other fields
) {}

Error Handling and Debugging in Production

MongoDB errors in Spring Boot are not always straightforward. The most common ones: DuplicateKeyException for unique index violations, DataIntegrityViolationException for schema validation failures, and MongoSocketReadException for network issues. You need a global exception handler that returns meaningful HTTP responses. Here's a @ControllerAdvice that catches MongoDB-specific exceptions and maps them to appropriate HTTP status codes. Note that we use @ExceptionHandler with specific exception types. For DuplicateKeyException, we return 409 Conflict with a message that doesn't expose internal details (like the index name). For MongoSocketReadException, we return 503 Service Unavailable because it's a transient network issue. Never expose the full stack trace to the client; log it server-side and return a sanitized error.

@ControllerAdvice
public class GlobalExceptionHandler {
    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);

    @ExceptionHandler(DuplicateKeyException.class)
    public ResponseEntity<ErrorResponse> handleDuplicateKey(DuplicateKeyException ex) {
        log.warn("Duplicate key violation", ex);
        return ResponseEntity.status(HttpStatus.CONFLICT)
            .body(new ErrorResponse("Resource already exists", "A record with the given unique field already exists"));
    }

    @ExceptionHandler(MongoSocketReadException.class)
    public ResponseEntity<ErrorResponse> handleNetworkError(MongoSocketReadException ex) {
        log.error("MongoDB network error", ex);
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
            .body(new ErrorResponse("Database unavailable", "Please try again later"));
    }
}

Testing with Testcontainers and Embedded MongoDB

Unit testing MongoDB repositories with mocks is useless—you miss index creation, query generation, and transaction behavior. Use Testcontainers to spin up a real MongoDB instance in your integration tests. For Spring Boot 3.2, the @DataMongoTest annotation slices the context to only MongoDB-related beans. Here's how to write an integration test for our BillingRepository. We use a custom Testcontainers configuration that starts a MongoDB container with a replica set (for transaction testing). The @DynamicPropertySource annotation overrides the MongoDB URI to point to the container. Note that we use a fixed port mapping to simplify configuration, but in CI, use random ports to avoid conflicts.

@DataMongoTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
class BillingRepositoryIntegrationTest {
    static MongoDBContainer mongoDBContainer = new MongoDBContainer("mongo:7.0")
        .withReplicaSet("rs0");

    @DynamicPropertySource
    static void setProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.data.mongodb.uri", mongoDBContainer::getReplicaSetUrl);
    }

    @Autowired
    private MongoTemplate mongoTemplate;

    @Test
    void testTransactionalInvoiceCreation() {
        Customer customer = new Customer("1", "Test", "test@example.com", null, null);
        mongoTemplate.insert(customer);
        
        // Perform transactional operation
        BillingService service = new BillingService(mongoTemplate);
        Invoice invoice = service.createInvoiceAndUpdateUsage("1", BigDecimal.valueOf(100));
        
        assertThat(invoice.getId()).isNotNull();
        Customer updated = mongoTemplate.findById("1", Customer.class);
        assertThat(updated.usageCount()).isEqualTo(1);
    }
}