Using Multiple MongoTemplate Beans for Multi-DB Routing in Spring

by

Summary

An application designed to manage data across two distinct MongoDB databases (test and test2) failed to route entities to their respective databases. Instead, all operations performed via the injected MongoTemplate were directed to the default database defined in the configuration. This resulted in cross-database pollution, where data intended for test2 was incorrectly persisted into test.

Root Cause

The failure stems from a fundamental misunderstanding of how Spring Data MongoDB manages Database Context.

  • Single Bean Constraint: The application extended AbstractMongoClientConfiguration and overrode getDatabaseName() to return "test".
  • Singleton Template: Spring automatically creates a single MongoTemplate bean based on that configuration.
  • Implicit Routing: By default, MongoTemplate is bound to the single database name provided during the bean creation phase.
  • Annotation Limitation: The @Document annotation is used to specify the collection name, but it does not provide a mechanism to specify a different database name.

Why This Happens in Real Systems

In complex distributed systems, engineers often encounter Multi-Tenant architectures or Data Sharding strategies where data must be logically or physically separated by database instance.

  • Configuration Rigidity: Many developers assume that setting up a MongoClient is sufficient to access all databases on the cluster. While true for the driver, it is not true for the high-level Spring abstractions.
  • Abstraction Leaks: Frameworks like Spring Data provide “magic” through dependency injection. This magic works perfectly for single-database use cases but creates a blind spot when the underlying infrastructure requires multi-database routing.

Real-World Impact

  • Data Integrity Violations: Data intended for a specific tenant or logical partition is written to the wrong location.
  • Security Vulnerabilities: If databases are used to separate sensitive user data from public data, misconfiguration can lead to unauthorized data exposure.
  • Operational Overhead: Cleaning up “polluted” databases requires manual intervention, scripts, and significant downtime to ensure no corrupted data remains in the production environment.

Example or Code

To solve this, we must define multiple MongoTemplate beans, each mapped to a specific database.

@Configuration
public class MultiDbMongoConfig {

    @Bean
    public MongoClient mongoClient() {
        return MongoClients.create("mongodb://127.0.0.1:27017");
    }

    @Bean(name = "primaryTemplate")
    public MongoTemplate primaryTemplate(MongoClient mongoClient) {
        return new MongoTemplate(mongoClient, "test");
    }

    @Bean(name = "secondaryTemplate")
    public MongoTemplate secondaryTemplate(MongoClient mongoClient) {
        return new MongoTemplate(mongoClient, "test2");
    }
}

To use them, use the @Qualifier annotation:

@Component
public class DataService {

    @Autowired
    @Qualifier("primaryTemplate")
    private MongoTemplate primaryTemplate;

    @Autowired
    @Qualifier("secondaryTemplate")
    private MongoTemplate secondaryTemplate;

    public void saveData() {
        primaryTemplate.save(new Person(...));
        secondaryTemplate.save(new SomethingElse(...));
    }
}

How Senior Engineers Fix It

Senior engineers approach this by decoupling the Connection Logic from the Application Logic.

  • Explicit Bean Qualification: Instead of relying on a single @Autowired MongoTemplate, they define multiple named beans and use @Qualifier to ensure the correct template is used for the correct domain model.
  • Custom Repository Implementations: For highly complex systems, they might implement custom repository logic where the MongoTemplate is chosen dynamically at runtime based on a Tenant Context (e.g., a ThreadLocal variable containing the current database name).
  • Separation of Concerns: They ensure that the configuration layer explicitly defines the boundaries of each data silo, making the routing logic visible and testable.

Why Juniors Miss It

  • The “One Template” Assumption: Juniors often assume that @Autowired MongoTemplate is a global gateway to the entire MongoDB cluster, rather than a specific client tied to a specific database context.
  • Over-reliance on Annotations: They expect @Document to do more than it was designed to do. They try to solve infrastructure problems (routing to a DB) using mapping metadata (collection names).
  • Lack of Contextual Awareness: They focus on making the code “work” (it compiles and runs) without verifying the side effects (where the data actually lands on the disk).

Leave a Comment