zero gravitySOLUTIONS
← All insightsJAVA & PERFORMANCE / DEPENDENCY AND TRANSACTION GUIDE

Choosing a JDBC or R2DBC boundary

QUICK ANSWER

Choose JDBC when its driver ecosystem and imperative transaction model fit the workload; choose R2DBC when a supported non-blocking database path serves a broader reactive design. Compare required SQL features, transaction behavior, and cancellation semantics before changing APIs. Both approaches remain limited by database capacity.

Inside this article 5 sections

JDBC versus R2DBC is a decision about the complete database interaction, not just whether a method returns a value or a publisher. A service may need a particular database feature, transaction pattern, migration tool, or library that constrains the choice. Start with those requirements before comparing execution styles.

Consider a subscription-renewal operation that reads an account, checks an expected revision, writes an invoice, records an audit event, and creates an outbox intent. These changes must either commit together or leave no partial renewal. A useful prototype implements this whole operation, including its failure paths.

Inventory the database features you actually use

List required SQL constructs, data types, generated-key behavior, batch operations, stored procedures, notifications, and driver-specific extensions. Verify support in the specific JDBC or R2DBC driver version, not merely in the database server. A server supporting a feature does not guarantee equivalent client behavior in every driver.

Include surrounding libraries. An ORM, reporting library, or existing transaction integration may depend on JDBC. A migration utility can remain a separate startup or deployment concern without forcing every request to use the same API. Distinguish runtime dependencies from operational tooling so the decision is neither artificially constrained nor unrealistically clean.

Renewal operation: persistence decision worksheet
RequirementQuestion to proveEvidence
Atomic renewalDo invoice, audit, and outbox writes share one transaction?Crash and rollback fixtures
Driver featuresAre required types and SQL operations supported?Versioned integration tests
Execution modelWhere does the caller wait or receive signals?Thread/context traces
CancellationWhat stops locally and at the database?Interrupted query and commit tests
CapacityHow are pool wait and admission bounded?Fixed-pool overload experiment
A complete transaction reveals constraints that a one-query benchmark misses. Both candidates must satisfy the same business invariant.

Keep JDBC work on an appropriate execution path

JDBC exposes a synchronous database interaction model. It can fit an imperative service naturally, including designs that use virtual threads for request handling. The connection pool still limits active database work, and transaction duration still determines how long each connection remains occupied.

Inside a reactive service, unavoidable JDBC work needs an explicit bounded execution boundary. Wrapping an already-executed query result in a publisher does not make the query non-blocking. Defer the call and isolate it from shared non-blocking request threads, then monitor the additional executor and connection waits.

Keep the complete imperative transaction together. Scattering parts across unrelated executor tasks can lose thread-associated transaction context or produce separate connections. A well-defined adapter that performs the whole bounded database operation is easier to reason about than many individually wrapped repository methods.

Treat reactive transaction context deliberately

R2DBC provides a reactive database access model for supported drivers. In Spring, reactive transaction management associates transactional resources with the reactive execution context rather than assuming a single thread-bound call stack. The operations that must participate need to remain inside the managed publisher chain.

Do not manually subscribe to a nested publisher inside a transaction and assume it remains part of the caller's atomic operation. That detached work can outlive the transaction or execute under another context. Return and compose the database operations so the transaction manager can observe their completion, errors, and cancellation.

Illustrative renewal composition:
within one managed transaction:
  read account at expected revision
  insert invoice
  append audit record
  append outbox intent
  advance account revision
return the composed transaction result

No detached subscriptions or external provider calls
inside this transaction boundary.

Also avoid assuming that one transactional connection supports arbitrary concurrent statements. A reactive chain can express concurrency that the connection or driver does not permit safely. Compose dependent statements sequentially and verify any deliberate parallel database work against the driver's documented behavior and transaction requirements.

Test rollback and cancellation separately

Force a failure after inserting the invoice but before appending the outbox intent. Verify that no partial renewal remains. Repeat with a constraint violation, database connection interruption, and application cancellation. Inspect durable database state after each test; a propagated exception alone does not establish that rollback occurred as intended.

Cancellation is particularly important when the client disconnects. Determine whether the driver cancels an active query, releases the connection only after cleanup, or allows server-side work to continue. A timeout observed by the caller does not prove that a commit did not happen. Preserve operation identity so an uncertain mutation can be reconciled.

Test transaction timeout and connection acquisition timeout as separate stages. If most request time is spent waiting for a pool slot, changing the query API may not address the bottleneck. Shorten transaction occupancy, reduce admitted work, or fix the expensive query before treating an execution-model migration as the only remedy.

If JDBC and R2DBC coexist during migration, treat their transaction managers and connections as separate resources unless an explicit supported coordination mechanism says otherwise. Calling one adapter from the other does not automatically create one atomic transaction. Keep a migrated business operation wholly inside one persistence boundary, or model the cross-boundary workflow with durable states and recovery.

Compare a fixed-resource product slice

Use the same database, dataset, isolation requirement, connection budget, and arrival pattern for the representative renewal operation. Record useful completions, pool wait, transaction duration, errors, CPU, memory, and recovery after a slow-query period. Include the code and operational complexity needed to preserve the invariant.

A reactive path may improve how the application handles waiting without increasing database throughput. An imperative path may meet the objective with simpler integration into existing libraries. Choose the design that satisfies the product's latency, capacity, and maintainability requirements under the declared conditions.

The virtual-thread pool guide develops admission limits, and blocking diagnostics helps inspect mixed paths. Java architecture design should preserve transaction meaning while choosing the execution boundary, rather than allowing an API preference to decide consistency accidentally.

FROM INSIGHT TO ACTIONSoftware architecture consulting

Choose persistence with the full transaction in view.

We can implement a representative JDBC or R2DBC slice and verify rollback, cancellation, and pool behavior under load.

Explore architecture consultingDiscuss your architecture

Start with your goals.
We’ll work through the next step together.