Spring Boot, Spring Data JPA with multiple DataSources
System Design practice on Codemia
Work through 120+ system design problems with detailed solutions, from rate limiters to multi-region storage.
Introduction
Using multiple JPA data sources in Spring Boot means you must be explicit about which entities, repositories, entity managers, and transaction managers belong to which database. Spring Boot can auto-configure one data source very conveniently, but once you add a second one, clarity and separation become more important than convenience.
Define Separate Properties
Start by giving each database its own configuration prefix.
Keeping the settings separate avoids ambiguity and makes it obvious which database each block configures.
Primary Data Source Configuration
Here is a typical primary configuration:
The important part is that repositories in com.example.primary.repo are tied explicitly to the primary entity manager and transaction manager.
Secondary Data Source Configuration
The second configuration follows the same pattern with different package boundaries:
This separation is what keeps Spring from mixing entities and repositories across the two databases.
Why Package Boundaries Matter
Multiple data sources become manageable when you organize code like this:
- '
com.example.primary.model' - '
com.example.primary.repo' - '
com.example.reporting.model' - '
com.example.reporting.repo'
Once those boundaries are clear, the annotations can bind each repository set to the correct database components.
Mark One Data Source as Primary When Needed
In many real applications, one data source is the default for framework integrations that expect a single bean. In that case, mark the main data source and its related beans with @Primary so generic injections resolve predictably.
That does not remove the need for qualifiers elsewhere, but it reduces ambiguity for the application's default database path.
Common Pitfalls
The most common mistake is putting repositories for both databases under the same package tree and expecting Spring to infer the right data source automatically. With multiple JPA contexts, explicit package separation is much safer.
Another issue is forgetting separate transaction managers. If both databases share a vague transaction setup, repository operations may fail or bind to the wrong persistence context.
A third pitfall is assuming distributed transactions are automatic. If one service method writes to two different databases, you need to think carefully about consistency and transaction strategy.
Finally, resist the temptation to hide all of this behind copy-pasted config without naming conventions. Multiple data source setups are maintainable only when the naming is consistent and obvious.
Summary
- Multiple JPA data sources in Spring Boot require explicit configuration.
- Give each database its own data source, entity manager factory, transaction manager, and repository package.
- Keep entity and repository packages clearly separated per database.
- Do not rely on one-database Spring Boot defaults once a second data source is introduced.
- Treat cross-database transaction design as a separate architectural concern.
Related reading
- Spring boot testing with liquibase fails
- Spring CrudRepository findByInventoryIds(List<Long> inventoryIdList) - equivalent to IN clause
- Spring Data JPA - could not initialize proxy - no Session - With Methods marked as transactional
- Spring Data JPA Unable to locate Attribute with the given name
- Spring Boot Spring Data with multi tenancy
- Spring Boot Spring Security Hierarchical Roles
- Spring Data JPA without Spring Boot
- Spring Data rollback transaction on retry

System Design Fundamentals
Build a strong foundation in designing scalable, reliable distributed systems.
View the courseTrack what you have practised
A free account saves your progress, solutions and study plan across every problem on Codemia.
System Design practice on Codemia
Work through 120+ system design problems with detailed solutions, from rate limiters to multi-region storage.