A Pragmatic Guide to Reactive Repositories with MongoDB and R2DBC
Over the last few years, reactive programming has gone from buzzword to production reality. But if you’ve ever wondered:
- “Do I really need reactive repositories?”
- “Will switching to reactive improve my app’s performance?”
- “What’s the catch?”
You’re not alone.
Reactive Spring Data (via Spring Data Reactive Repositories) promises non-blocking, event-driven data access. It sounds great—especially for applications dealing with high concurrency or streaming data.
But here’s the honest truth:
Reactive repositories are powerful, but not always necessary.
Sometimes they make your life easier. Other times they make it… complicated.
This article cuts through the hype with a pragmatic look at when and how to use reactive repositories. We’ll cover real examples using MongoDB and R2DBC, discuss performance trade-offs, and provide best practices for clarity—no hand-waving.
What Are Reactive Repositories, Really?
A reactive repository is a non-blocking abstraction over your database.
Instead of returning List<T> or Optional<T>, it returns:
Flux<T>→ For streams of data (zero to many)Mono<T>→ For single results (zero or one)
Reactive repositories are part of Spring Data’s reactive stack, which works with Project Reactor under the hood.
Example: Reactive MongoDB Repository
public interface UserRepository extends ReactiveMongoRepository<User, String> {
Flux<User> findByRole(String role);
Mono<User> findByEmail(String email);
}
When Should You Use Reactive Repositories?
Here’s the first question to ask:
Is your entire data stack non-blocking?
| Use Reactive Repos If: | Stick to Traditional Repos If: |
|---|---|
| You’re using MongoDB Reactive Driver, R2DBC, or Cassandra Reactive | You’re using JPA, JDBC, or legacy relational DBs |
| You need high concurrency handling (e.g., 1000+ parallel connections) | You have typical CRUD workloads |
| Your app is I/O bound (not CPU bound) | Your app is CPU bound or data volumes are small |
| You’re building streaming applications (e.g., SSE, WebSocket feeds) | Your data is relational with complex transactions |
Realistic Use Case Examples
Good Fit: Reactive with MongoDB
MongoDB has native reactive drivers, making it a perfect fit for reactive repositories.
Example: Streaming API
@GetMapping("/users/stream")
public Flux<User> streamUsers() {
return userRepository.findAll();
}
- Ideal for server-sent events (SSE) or WebSockets
- No blocking threads waiting for DB connections
- Handles thousands of concurrent streams efficiently
Good Fit: R2DBC for Non-Blocking SQL
If you prefer SQL but want non-blocking access, use R2DBC (Reactive Relational Database Connectivity).
Example: PostgreSQL with R2DBC
public interface OrderRepository extends ReactiveCrudRepository<Order, Long> {
Flux<Order> findByStatus(String status);
}
You can connect to Postgres or MySQL without JDBC’s blocking calls.
However, R2DBC does not support JPA or Hibernate ORM. You lose features like:
- Lazy loading
- @Transactional propagation (works differently in reactive)
Not a Good Fit: Complex Multi-Entity Transactions
Reactive repositories are not ideal for complex transactional use cases involving multiple updates or relational joins.
Tip: If your app is mostly reads or simple writes, go reactive.
If you’re managing ACID transactions across multiple entities, stick with JPA + JDBC.
Performance: Reactive vs Blocking—What’s the Real Difference?
Blocking I/O (Traditional Repos)
- Each thread waits for DB response
- Needs thread pools to scale
- Easy to run out of threads under heavy load
Non-Blocking I/O (Reactive Repos)
- One thread can handle many requests
- Better at handling high-concurrency with fewer resources
- But… more complex error handling and backpressure management
Performance Test Snapshot
| Metric | Blocking (JDBC) | Non-Blocking (R2DBC) |
|---|---|---|
| 100 concurrent users | Fine | Fine |
| 500 concurrent users | Starts to strain threads | Stable |
| 2000 concurrent users | Thread pool exhaustion risk | Still handles load (if properly tuned) |
Real-World Opinion:
Reactive shines when your system is I/O-bound and concurrency-heavy. If you have 50 users with normal workloads, you won’t notice a huge difference.
If you’re building highly concurrent APIs or event streams, it’s worth it.
Best Practices for Using Reactive Repositories
1️⃣ Don’t Mix Blocking and Non-Blocking Calls
Calling blocking() inside a reactive chain is an anti-pattern. It defeats the purpose of going reactive
// ❌ Bad practice
Mono<User> userMono = userRepository.findById(id)
.map(user -> {
// Avoid this
someBlockingCall(user);
return user;
});
2️⃣ Handle Backpressure
Use limitRate() or onBackpressureBuffer() wisely to avoid OutOfMemoryErrors in case of fast producers and slow consumers.
3️⃣ Use Connection Pools Properly
Even non-blocking drivers use connection pools. Use Reactor Netty or R2DBC Connection Pool and tune it for your workloads.
4️⃣ Test for Realistic Concurrency
Don’t just benchmark with curl. Use tools like:
5️⃣ Know When Not to Use Reactive
Sometimes, simple is better. If your app has:
- Low concurrency
- Simple CRUD operations
- Heavy business logic but light DB interaction
Stick with traditional repositories. You’ll save yourself from unnecessary complexity.
Example Projects and Repos
- Spring WebFlux + Reactive MongoDB Sample
GitHub Repo - Spring R2DBC Example (PostgreSQL)
GitHub Repo - Official Spring Data R2DBC Docs
https://spring.io/projects/spring-data-r2dbc
Further Reading
Final Thoughts
Reactive programming is not about raw speed—it’s about scalability.
If your app is struggling with high concurrency, backpressure, or streaming use cases, Reactive Spring Data can be a game changer.
But if you’re just building CRUD apps for internal systems?
You might be fine sticking with the classic blocking Spring Data repositories.
Pragmatism beats hype. Use the right tool for the job.
