Spring transaction timeout: put the deadline on the owning scope

Who owns the clock?

A receipt command opens a transaction and invokes a repository helper annotated with @Transactional(timeout = 9). If that helper joins the existing REQUIRED transaction, its local timeout is normally not the physical transaction deadline. Put the timeout on the service entry method that creates the transaction. Propagation determines whether a method starts or joins a physical transaction; annotations on self-invoked methods may be bypassed by proxy boundaries.

Treat timeout as one layer

A transaction timeout can influence supported JDBC operations and rollback handling, but it is not a universal wall-clock cancellation signal for HTTP calls, in-memory loops or every driver. Configure query and remote-call deadlines separately. Keep the database lock wait under the request budget and leave time to release the connection. Connection pool wait before transaction start is another clock to measure.

Test the failure path

Use a deliberately slow database operation in an integration test against the target driver. Assert the call fails, the transaction rolls back and the connection returns to the pool. Then call the helper inside a longer outer transaction and verify which timeout actually applies. Do not make the production timeout absurdly short merely to satisfy a test; use a test-specific boundary and report p95/p99 latency separately.

Implementation contract

@Transactional(timeout = 9)
public ReceiptView issueReceipt(IssueReceipt command) {
    ReceiptEntity receipt = repository.save(ReceiptEntity.from(command));
    return ReceiptView.from(receipt);
}

Cost and verification

A deadline can limit lock and connection occupancy when supported, improving pool availability during a stall. Premature deadlines increase retries and rollback work; size them from the operation budget.

Common Mistakes

• Do not expect an inner REQUIRED timeout to reset an existing outer transaction.
• Do not treat a transaction timeout as an HTTP-client timeout.
• Do not assume every database driver interrupts a running statement identically.

Read next

Spring transaction propagation: joined rollback and independent commit, Spring transactional methods: call paths and rollback assumptions, Spring Boot JDBC pool capacity: size connections across replicas, Spring Data JPA pessimistic lock: hold it only through the stock decision, Spring transaction rollback: checked failures commit unless a rule says otherwise.