Spring Read-Only Transactions: Boost Performance & Avoid Pitfalls

You've got a service method that only fetches data. You slap @Transactional on it because you read somewhere that it's good practice. But do you set readOnly = true? Most developers don't, and that's a performance leak. I've seen production systems where a simple read operation triggered full Hibernate dirty checking, causing unnecessary overhead and even deadlocks under high concurrency.

Let's get real: read-only transactions are not just a documentation hint. They can significantly reduce database round trips, skip unnecessary locks, and prevent accidental writes. In Spring Boot 3.x, the behavior changed—now the JDBC connection is set to read-only, which can throw exceptions if you try to write. That's a good thing, but it caught many teams off guard.

In this article, I'll show you exactly how to use @Transactional(readOnly = true) effectively, share war stories from production, and reveal what the official docs won't tell you. By the end, you'll know when to use it, when to avoid it, and how to debug the inevitable issues.

What Are Read-Only Transactions?

A read-only transaction is a database transaction that does not modify any data. In Spring, you mark a method with @Transactional(readOnly = true) to indicate that the transaction should be optimized for reads. This tells the JPA provider (like Hibernate) to skip dirty checking and flush at the end, reducing overhead. It also hints the database to use read locks instead of write locks, improving concurrency.

Here's the hard truth: most developers think readOnly is just a hint. It's not. In Spring Boot 3.x, the JDBC connection is actually set to read-only via Connection.setReadOnly(true). This means if you try to execute an INSERT, UPDATE, or DELETE, the database will throw a SQLException. That's a safety net that caught many teams off guard when upgrading from Spring Boot 2.x.

But even without that, Hibernate behaves differently. With readOnly=true, Hibernate disables dirty checking—it doesn't need to track entity changes because it knows nothing will be written. This can significantly reduce memory usage and CPU cycles, especially when dealing with large result sets.

Let's see a simple example:

@Service
public class ReportService {

    private final ReportRepository reportRepository;

    public ReportService(ReportRepository reportRepository) {
        this.reportRepository = reportRepository;
    }

    @Transactional(readOnly = true)
    public List<Report> getReportsByDate(LocalDate date) {
        return reportRepository.findByDate(date);
    }
}

@Repository
public interface ReportRepository extends JpaRepository<Report, Long> {
    List<Report> findByDate(LocalDate date);
}

How Read-Only Transactions Improve Performance

The performance benefits of read-only transactions come from multiple layers:

1. Hibernate Dirty Checking: When a transaction is not read-only, Hibernate must track all loaded entities to detect changes. This requires storing a snapshot of each entity's state and comparing it on flush. With readOnly=true, Hibernate skips this entirely, saving memory and CPU.
2. Flush Mode: By default, Hibernate flushes the persistence context before query execution to synchronize pending changes. With readOnly=true, Hibernate sets the flush mode to MANUAL or NEVER, avoiding unnecessary flushes.
3. Database Locks: Many databases use shared locks for read-only transactions and exclusive locks for write transactions. By declaring read-only, you allow the database to use more optimistic locking strategies, reducing contention.
4. Connection Pooling: Some connection pools (like HikariCP) can optimize read-only connections by routing them to read replicas if configured.

Let's look at a benchmark: In a typical Spring Boot application with Hibernate, a read-only transaction can be up to 30% faster than a read-write transaction for the same query, especially when dealing with large result sets.

Here's a code snippet showing how to verify that dirty checking is skipped:

@SpringBootTest
class PerformanceTest {

    @Autowired
    private EntityManager em;

    @Test
    @Transactional(readOnly = true)
    void testReadOnlyTransaction() {
        // Hibernate will not perform dirty checking
        List<Report> reports = em.createQuery("SELECT r FROM Report r", Report.class)
                .getResultList();
        // No flush will occur at the end
    }

    @Test
    @Transactional
    void testReadWriteTransaction() {
        // Hibernate will perform dirty checking and flush
        List<Report> reports = em.createQuery("SELECT r FROM Report r", Report.class)
                .getResultList();
        // A flush occurs at the end even if no changes were made
    }
}

Common Pitfalls with Read-Only Transactions

Even experienced developers fall into these traps. Here are the most common pitfalls:

1. Writing Inside a Read-Only Transaction In Spring Boot 3.x, this throws a SQLException. In earlier versions, the write might silently succeed but still cause dirty checking overhead. Always ensure that any method annotated with @Transactional(readOnly = true) does not perform writes.

2. Lazy Loading Outside the Transaction A read-only transaction ends when the method returns. If you try to lazy-load an association after the transaction ends, you'll get a LazyInitializationException. This is a common issue when using Spring's Open Session in View (OSIV) pattern. Disable OSIV (spring.jpa.open-in-view=false) and handle lazy loading explicitly.

3. Propagation and Read-Only If a read-only transaction calls another transactional method with PROPAGATION_REQUIRES_NEW, the new transaction is not read-only by default. You must set readOnly on that method as well.

4. Read-Only and Isolation Levels Setting readOnly=true does not change the isolation level. If you need a specific isolation (like READ_UNCOMMITTED), you must set it explicitly. Some databases ignore readOnly for certain isolation levels.

Let's see an example of a pitfall:

@Service
public class UserService {

    @Transactional(readOnly = true)
    public User getUser(Long id) {
        User user = userRepository.findById(id).orElseThrow();
        // Attempt to update last access time - will throw in Spring Boot 3.x
        user.setLastAccessTime(LocalDateTime.now());
        return user;
    }
}

// Fix: separate the write into a different transactional method
@Transactional
public void updateLastAccessTime(Long userId) {
    User user = userRepository.findById(userId).orElseThrow();
    user.setLastAccessTime(LocalDateTime.now());
}

Read-Only Transactions with Multiple Data Sources

If your application uses multiple data sources (e.g., a primary database for writes and a read replica for reads), you need to configure separate transaction managers. Spring's @Transactional annotation can specify which transaction manager to use via the transactionManager attribute.

Here's a common setup: you have a read-only data source pointing to a read replica, and you want all read-only transactions to use that replica. You can create a custom annotation that combines @Transactional(readOnly = true) with the correct transaction manager.

Let's see how to implement this:

@Configuration
public class DataSourceConfig {

    @Bean
    @Primary
    @ConfigurationProperties(prefix = "spring.datasource.primary")
    public DataSource primaryDataSource() {
        return DataSourceBuilder.create().build();
    }

    @Bean
    @ConfigurationProperties(prefix = "spring.datasource.readonly")
    public DataSource readOnlyDataSource() {
        return DataSourceBuilder.create().build();
    }

    @Bean
    @Primary
    public PlatformTransactionManager primaryTransactionManager(@Qualifier("primaryDataSource") DataSource ds) {
        return new JpaTransactionManager(primaryEntityManagerFactory(ds));
    }

    @Bean
    public PlatformTransactionManager readOnlyTransactionManager(@Qualifier("readOnlyDataSource") DataSource ds) {
        return new JpaTransactionManager(readOnlyEntityManagerFactory(ds));
    }
}

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Transactional(readOnly = true, transactionManager = "readOnlyTransactionManager")
public @interface ReadOnlyTransactional {
}

// Usage
@Service
public class ReportService {

    @ReadOnlyTransactional
    public List<Report> getReports() {
        // Uses read replica
    }
}

What the Official Docs Won't Tell You

The Spring documentation covers the basics, but here are the gotchas I've learned from production:

1. Read-Only Does Not Prevent All Writes In Spring Boot 2.x, the readOnly flag is a hint, not a guarantee. Hibernate still flushes if you call flush() explicitly. In Spring Boot 3.x, the JDBC connection is set to read-only, but native queries that are not detected as writes might still slip through. Always test with a database user that has read-only privileges.

2. @Transactional(readOnly=true) on Class Level If you annotate a class with @Transactional(readOnly=true), all methods inherit that setting. But if you override a method with @Transactional(readOnly=false), the class-level annotation is overridden. However, the transaction manager might still be the default one. Be explicit.

3. Read-Only and Hibernate's Query Plan Cache Hibernate caches query plans. With readOnly=true, the query plan cache might not be used if the same query is executed in a read-write context. This can cause performance issues in mixed workloads.

4. Read-Only Transactions in JPA Repositories Spring Data JPA's default methods (like findAll()) are not annotated with @Transactional. If you call them outside a service-level transaction, each call runs in its own transaction, which is read-write by default. Always wrap them in a read-only transaction.

5. Read-Only and Spring's Open Session in View (OSIV) OSIV keeps the session open during view rendering. If you have a read-only transaction that returns entities, and the view tries to lazy-load associations, it will work because the session is still open. But this is a performance anti-pattern. Disable OSIV and handle lazy loading explicitly.

Let's see a code example that demonstrates the OSIV issue:

@Service
public class ReportService {

    @Transactional(readOnly = true)
    public Report getReport(Long id) {
        return reportRepository.findById(id).orElseThrow();
    }
}

// Controller
@GetMapping("/reports/{id}")
public String viewReport(@PathVariable Long id, Model model) {
    Report report = reportService.getReport(id);
    // If OSIV is enabled, lazy loading works here
    // If OSIV is disabled, this will throw LazyInitializationException
    model.addAttribute("authorName", report.getAuthor().getName());
    return "reportView";
}

Best Practices for Read-Only Transactions

After years of production experience, here are my recommendations:

1. Annotate all read-only service methods with @Transactional(readOnly = true). This includes simple finders, reporting methods, and any method that only queries data.
2. Use a custom annotation for read-only transactions to reduce boilerplate and ensure consistency, especially if you have multiple data sources.
3. Test with Spring Boot 3.x if you're upgrading. The behavior change around read-only connections can break existing code.
4. Enable Hibernate statistics in development to verify that read-only transactions are not flushing.
5. Avoid relying on OSIV. Disable it and handle lazy loading explicitly with JOIN FETCH or EntityGraph.
6. Consider using read replicas for read-heavy applications. Configure a separate transaction manager and route read-only transactions to the replica.
7. Be explicit about transaction propagation. If a read-only transaction calls another method with REQUIRES_NEW, that new transaction is not read-only by default.

Here's a complete example of a service with best practices:

@Service
public class ReportService {

    private final ReportRepository reportRepository;
    private final AuthorRepository authorRepository;

    public ReportService(ReportRepository reportRepository, AuthorRepository authorRepository) {
        this.reportRepository = reportRepository;
        this.authorRepository = authorRepository;
    }

    @ReadOnlyTransactional
    public ReportDto getReportWithAuthor(Long id) {
        Report report = reportRepository.findById(id).orElseThrow();
        // Eagerly fetch author to avoid LazyInitializationException
        Author author = authorRepository.findById(report.getAuthor().getId()).orElseThrow();
        return new ReportDto(report, author);
    }

    @Transactional
    public Report createReport(Report report) {
        return reportRepository.save(report);
    }
}