DEV Community: Amir Golmoradi

Understanding Java Memory: Primitive Types vs Reference Types (The Concept That Finally Made It Click)

Amir Golmoradi — Fri, 03 Jul 2026 17:46:41 +0000

If you've just started learning Java, you've probably heard something like this:

"Primitive variables are stored on the Stack, and Objects are stored on the Heap."

While this is a useful starting point, it's also one of the biggest sources of confusion for Java developers.

The real concept you need to understand isn't Stack vs Heap.

It's Values vs References.

Once you understand that difference, concepts like object sharing, method arguments, and Garbage Collection suddenly become much easier.

Primitive Types Store Values

Let's start with a simple example.

int age = 25;

Think of the variable as a small box.

+-------+
| age   |
+-------+
|  25   |
+-------+

The variable contains the value itself.

There is no hidden object.

There is no reference.

There is no memory address you need to think about.

The number 25 is the value stored by the variable.

Another example:

int a = 10;
int b = a;

Java copies the value.

Conceptually:

+-------+     +-------+
|   a   |     |   b   |
+-------+     +-------+
|  10   |     |  10   |
+-------+     +-------+

Now suppose we do this:

b = 20;

Memory becomes:

+-------+     +-------+
|   a   |     |   b   |
+-------+     +-------+
|  10   |     |  20   |
+-------+     +-------+

Notice something important:

Changing b does not change a.

Why?

Because Java copied the value, not a connection between the variables.

Reference Types Store References

Now let's create an object.

User user = new User();

This time the variable doesn't contain the object itself.

Instead, it contains a reference to the object.

Conceptually:

user
  │
  ▼
+----------------+
|   User Object  |
+----------------+

The object lives in memory, and the variable simply knows how to find it.

Copying a Reference

Now consider this code.

User u1 = new User();
User u2 = u1;

Many beginners think Java creates another object.

It doesn't.

Instead, Java copies the reference.

u1 ───┐
      │
u2 ───┤
      ▼
+----------------+
|   User Object  |
+----------------+

There is still one object.

There are simply two variables referring to it.

Now suppose we write:

u2.setName("Steve");

If we later read:

System.out.println(u1.getName());

We'll also get:

Steve

Why?

Because both variables refer to the same object.

Why Doesn't Java Copy the Entire Object?

Imagine this object contains:

a large image
thousands of records
megabytes of data

If Java copied the entire object every time you assigned it to another variable:

Image b = a;

your application would become extremely slow and memory hungry.

Copying a reference is cheap.

Copying an entire object can be expensive.

That's one of the main reasons Java uses references.

A Helpful Analogy

Imagine a hotel.

The room number is:

The guest is inside the room.

If you write down:

did you copy the guest?

No.

You only copied the room number.

A Java reference works the same way.

The variable stores information that allows Java to locate the object.

What Happens When a Reference Becomes null?

Consider this example.

User user = new User();

user = null;

Did the object disappear immediately?

No.

The object may still exist in memory.

What changed is that the variable no longer refers to it.

If no reachable references remain, the object becomes:

Eligible for Garbage Collection

Notice the wording.

Eligible does not mean:

"Deleted immediately."

It simply means the JVM is now allowed to reclaim its memory whenever it decides it's appropriate.

Garbage Collection Uses Reachability

One of the most common misconceptions is that Java counts references.

It doesn't.

The JVM starts from a set of special locations called GC Roots (such as active thread stacks and static fields) and asks one question:

Can I still reach this object?

If the answer is:

Yes → The object is alive.
No → The object is eligible for garbage collection.

This is why even objects that reference each other can still be collected if nothing in the running program can reach them.

The Mental Model That Changed Everything

Whenever you're unsure what's happening, remember these two rules:

Primitive Types

Variable

↓

Value

Reference Types

Variable

↓

Reference

↓

Object

That's it.

This simple mental model explains:

why objects can be shared,
why changing one reference affects another,
why null doesn't immediately delete an object,
and why Java needs Garbage Collection.

Final Thoughts

Many developers spend years memorizing syntax but never build a clear mental model of memory.

Once you understand the difference between values and references, Java becomes much more predictable.

The next time you write:

User u2 = u1;

don't think:

"I created another object."

Think:

"I created another reference to the same object."

That small change in thinking is one of the biggest milestones in becoming a confident Java developer.

SQL as Architecture: The Irreconcilable Philosophies of jOOQ and LINQ

Amir Golmoradi — Fri, 12 Jun 2026 09:40:07 +0000

The Central Architectural Conflict

Every persistent layer draws a line: on one side sits your domain model and application logic; on the other, a relational engine that knows nothing of your abstractions. The engineering decision that defines the quality of your data layer is not which library to use — it is who owns the translation across that boundary, what guarantees survive the crossing, and what happens when the translation fails at 3 AM in production.

jOOQ and LINQ answer this question from diametrically opposite starting points, and those starting points propagate through every decision a team makes: schema governance, query composability, failure modes, and concurrent throughput at scale.

jOOQ asserts that SQL is not a problem to be abstracted away. It is the most expressive, battle-tested DSL for relational data ever devised, and the correct engineering response is to expose it, type-safe and schema-grounded, directly in your application code. LINQ inverts this: queries are a universal language construct, integrated into the compiler itself, where the underlying data source — SQL, XML, in-memory objects — is an implementation detail the language abstracts uniformly.

Both philosophies are internally consistent. Both produce entirely different failure modes, performance envelopes, and developer experience surfaces. This article examines them without ecosystem loyalty.

Foundational Architectures

jOOQ: The SQL Rehabilitation Manifesto

jOOQ's intellectual commitment is radical in the context of the JVM ecosystem, which spent a decade trying to abolish SQL behind ORM magic. The thesis is simple: SQL is good. The problem is writing SQL as untyped, compiler-invisible strings. The solution is not a higher-level abstraction — it is a type-safe, schema-driven Java DSL that mirrors SQL's own syntax tree.

The mechanism that makes this possible is code generation. Before your application compiles, jOOQ's generator connects to your live schema (or a Flyway-managed DDL baseline) and emits a Java class hierarchy that is a structural mirror of your database:

// Generated from the live schema — not hand-written
// src/generated/tables/Orders.java
public class Orders extends TableImpl<OrdersRecord> {
    public static final Orders ORDERS = new Orders();

    public final TableField<OrdersRecord, Long>       ID          = createField(DSL.name("id"),          SQLDataType.BIGINT.nullable(false));
    public final TableField<OrdersRecord, Long>       CUSTOMER_ID = createField(DSL.name("customer_id"), SQLDataType.BIGINT.nullable(false));
    public final TableField<OrdersRecord, BigDecimal> AMOUNT      = createField(DSL.name("amount"),      SQLDataType.NUMERIC(12, 2).nullable(false));
    public final TableField<OrdersRecord, String>     STATUS      = createField(DSL.name("status"),      SQLDataType.VARCHAR(32).nullable(false));
    public final TableField<OrdersRecord, Instant>    CREATED_AT  = createField(DSL.name("created_at"), SQLDataType.INSTANT.nullable(false));
}

This is not reflection-based mapping at runtime. It is a compile-time contract between your application and your database schema. ORDERS.AMOUNT is statically typed as TableField<OrdersRecord, BigDecimal>. The DSL enforces this type across every operation that touches it:

// Compile error — ORDERS.AMOUNT is BigDecimal; eq() does not accept String
dsl.selectFrom(ORDERS)
   .where(ORDERS.AMOUNT.eq("ten thousand")); // DOES NOT COMPILE

The comparison is not with JPQL or HQL — those are untyped strings. The comparison is with code that looks safe but isn't. jOOQ makes the type contract structurally verifiable by the compiler.

LINQ: The Universal Query Algebra

LINQ's design goal was broader and, in retrospect, more ambitious: integrate query as a first-class syntactic construct into C# itself, applicable to any data source that implements the query provider contract. The implementation rests on three interlocking language mechanisms that are worth understanding precisely, because their interaction defines LINQ's failure modes.

1. Expression Trees — The Keystone

The standard Java or C# lambda compiles to an IL delegate: an executable function pointer. LINQ's innovation is a second lambda form typed as Expression<Func<T, TResult>>, which the compiler does not compile to IL. Instead, it builds an in-memory AST — a parse tree of the lambda's structure — at compile time, serialized as a System.Linq.Expressions.Expression object graph:

// Compiled to an IL delegate — executable, opaque to EF Core
Func<Order, bool> func = o => o.Amount > 1000m;

// Compiled to an expression tree — EF Core can walk this AST and translate it
Expression<Func<Order, bool>> expr = o => o.Amount > 1000m;
// Internally: BinaryExpression(GT,
//               MemberExpression(o, "Amount"),
//               ConstantExpression(1000m))

EF Core's LINQ provider implements IQueryProvider, which receives these expression trees and translates them into SQL. This is architecturally elegant — the query is a data structure, not a string, and it can be inspected, composed, and transformed programmatically before execution.

2. IQueryable<T> and Deferred Composition

Queries accumulate as expression trees against IQueryable<T> until a terminal operator (ToListAsync, CountAsync, FirstOrDefaultAsync) is invoked, at which point translation and execution occur:

// No SQL emitted yet — expression tree accumulates
IQueryable<Order> query = context.Orders
    .Where(o => o.Status == OrderStatus.Pending);

if (filter.MinAmount.HasValue)
    query = query.Where(o => o.Amount >= filter.MinAmount.Value);

if (filter.CustomerId.HasValue)
    query = query.Where(o => o.CustomerId == filter.CustomerId.Value);

// Single SQL query emitted here — all predicates composed into one WHERE clause
var results = await query
    .OrderBy(o => o.CreatedAt)
    .Take(50)
    .ToListAsync();

3. Query Comprehension Syntax

A syntactic layer over the method chain API, compiled identically to .Where().Select() chains:

var highValueOrders =
    from o in context.Orders
    join c in context.Customers on o.CustomerId equals c.Id
    where o.Amount > 5_000m && c.Tier == CustomerTier.Gold
    orderby o.CreatedAt descending
    select new { o.Id, c.Name, o.Amount };

LINQ's elegance is genuine. Its failure mode is equally precise: the boundary between translatable and untranslatable LINQ is invisible until runtime.

Type Safety: Two Contracts, Two Failure Modes

jOOQ's Schema-Grounded Contract

The generated types carry the database schema's structure through the entire call chain. The following query's return type is fully resolved at compile time:

import static com.example.generated.Tables.*;
import static org.jooq.impl.DSL.*;

// Return type is Record3<String, BigDecimal, Long> — fully typed, no casting
Result<Record3<String, BigDecimal, Long>> topCustomers = dsl
    .select(
        CUSTOMERS.NAME,
        sum(ORDERS.AMOUNT).as("total_revenue"),
        count(ORDERS.ID).as("order_count")
    )
    .from(CUSTOMERS)
    .join(ORDERS).on(ORDERS.CUSTOMER_ID.eq(CUSTOMERS.ID))
    .where(ORDERS.CREATED_AT.greaterOrEqual(LocalDate.now().minusYears(1)))
    .groupBy(CUSTOMERS.NAME)
    .having(sum(ORDERS.AMOUNT).greaterThan(BigDecimal.valueOf(10_000)))
    .orderBy(sum(ORDERS.AMOUNT).desc())
    .limit(20)
    .fetch();

// topCustomers.get(0).value1() → String
// topCustomers.get(0).value2() → BigDecimal
// topCustomers.get(0).value3() → Long

When your DBA renames a column or changes a type, you regenerate, and the compiler identifies every broken callsite immediately. This is the schema-as-contract model: the build pipeline enforces schema correctness, not the test suite.

LINQ's Expression Tree Contract — and Where It Fails

LINQ with EF Core provides type safety at the C# model level. Typed POCO properties, typed projections, typed .Select() lambdas. What the compiler cannot enforce is whether those expressions are translatable to SQL by EF Core's query provider at runtime:

// Compiles without warning. Crashes at runtime.
private static bool IsPremiumOrder(Order o) =>
    o.Amount > 5_000m && o.Items.Any(i => i.IsDiscounted);

var premiumOrders = await context.Orders
    .Where(o => IsPremiumOrder(o))  // InvalidOperationException: could not be translated
    .ToListAsync();

EF Core's expression tree translator requires inline lambdas that the C# compiler has preserved as Expression<Func<T, bool>>. A regular method call is an opaque IL delegate — the translator sees a MethodCallExpression pointing to a compiled method it cannot decompose into SQL predicates.

This is not a contrived edge case. It manifests whenever business logic is extracted into helper methods — a normal and correct software engineering practice — and then composed into LINQ queries. The mitigation is EF.CompileAsyncQuery(), which pre-compiles the expression tree to a reusable delegate, amortizing both translation overhead and the runtime failure surface:

// Expression tree compiled once at startup — translation failure surfaced at startup, not at runtime
private static readonly Func<AppDbContext, OrderStatus, decimal, IAsyncEnumerable<OrderSummary>>
    GetFilteredOrders = EF.CompileAsyncQuery(
        (AppDbContext ctx, OrderStatus status, decimal minAmount) =>
            ctx.Orders
               .Where(o => o.Status == status && o.Amount >= minAmount)
               .Select(o => new OrderSummary(o.Id, o.Amount, o.CreatedAt))
    );

// Zero translation overhead on the hotpath
await foreach (var summary in GetFilteredOrders(context, OrderStatus.Pending, 1_000m))
    await ProcessAsync(summary);

Compiled queries shift the failure from the first production request to application startup — meaningfully better, but still later than a jOOQ build failure.

Schema Drift: The Operational Divergence

Scenario	jOOQ	EF Core LINQ
Column renamed in DB	Regenerate → compiler error at every usage site	Runtime `SqlException` on first query execution
Column type widened (int → bigint)	Compile error — generated field type changes	Silent data truncation or runtime cast failure
Table dropped	Compile error on `Tables.X` reference	Runtime `SqlException`
NOT NULL column added without default	Compile error if INSERT omits the field	Runtime constraint violation
Column added to projected type	Regenerate → explicit update required	Silent — EF Core materializes what maps

jOOQ shifts schema breakage to the build pipeline. EF Core shifts it to integration test coverage — or to production if that coverage is incomplete.

Query Composition Under Pressure

jOOQ: Explicit, Predictable, No Translation Surprises

jOOQ composes queries by building SQL node trees directly. Every operator you invoke maps to a SQL clause — there is no expression tree, no translation step, no runtime surprises. Conditional predicate accumulation is idiomatic and transparent:

public List<OrderRecord> findOrders(OrderFilter filter) {
    var conditions = new ArrayList<Condition>();

    if (filter.getStatus() != null)
        conditions.add(ORDERS.STATUS.eq(filter.getStatus().name()));

    if (filter.getMinAmount() != null)
        conditions.add(ORDERS.AMOUNT.greaterOrEqual(filter.getMinAmount()));

    if (filter.getFromDate() != null)
        conditions.add(ORDERS.CREATED_AT.greaterOrEqual(filter.getFromDate()));

    if (filter.getCustomerId() != null)
        conditions.add(ORDERS.CUSTOMER_ID.eq(filter.getCustomerId()));

    return dsl
        .selectFrom(ORDERS)
        .where(DSL.and(conditions))
        .orderBy(ORDERS.CREATED_AT.desc())
        .fetchInto(OrderRecord.class);
}

What you construct is what executes — one SQL statement, one round-trip, no hidden branching in the execution plan.

LINQ's Deferred Composition — And Its Genuine Edge

LINQ's deferred execution model produces architecturally clean composable query pipelines in layered systems. Each layer adds predicates to the expression tree without touching the database. The single SQL query is emitted only when the terminal operator is invoked:

// Repository — baseline, reusable
public IQueryable<Order> GetBaseQuery() =>
    _context.Orders
        .AsNoTracking()
        .Where(o => !o.IsDeleted);

// Application service — decorates without knowledge of the underlying query
public IQueryable<Order> GetPendingOrders(IQueryable<Order> base) =>
    base.Where(o => o.Status == OrderStatus.Pending)
        .Include(o => o.Items);

// Use case — narrows and paginates
public async Task<PagedResult<OrderDto>> GetHighValuePending(
    IQueryable<Order> query,
    int page,
    int pageSize)
{
    var filtered = query.Where(o => o.Amount > 1_000m);
    var total    = await filtered.CountAsync();
    var items    = await filtered
        .OrderByDescending(o => o.Amount)
        .Skip(page * pageSize)
        .Take(pageSize)
        .Select(o => new OrderDto(o.Id, o.Amount, o.Status))
        .ToListAsync();

    return new PagedResult<OrderDto>(items, total, page, pageSize);
}

Three layers, zero database round-trips until ToListAsync(). A single SQL query with WHERE, COUNT, ORDER BY, and OFFSET/FETCH is emitted at the terminal. This is genuinely elegant — for use cases that stay within EF Core's translatable boundary.

The architectural cost: passing IQueryable<T> across layer boundaries couples those layers to EF Core's query model. Your domain service now carries an implicit dependency on EF Core's ability to translate whatever expressions the caller composes into it. In practice, this is a leaky abstraction by design — and in most enterprise applications, a pragmatic trade-off that works.

SQL Expressibility: Where Abstractions Show Their Seams

This is the starkest divergence. Modern SQL engines have invested heavily in analytics operators that go far beyond what ORM-style query builders can represent. The expressibility gap between jOOQ and EF Core LINQ is not a minor feature delta — it is an architectural ceiling.

Window Functions

jOOQ — first-class DSL support, dialect-translated:

dsl.select(
    TRANSACTIONS.ACCOUNT_ID,
    TRANSACTIONS.AMOUNT,
    TRANSACTIONS.CREATED_AT,
    sum(TRANSACTIONS.AMOUNT)
        .over(partitionBy(TRANSACTIONS.ACCOUNT_ID)
                  .orderBy(TRANSACTIONS.CREATED_AT)
                  .rowsBetweenUnboundedPreceding().andCurrentRow())
        .as("running_balance"),
    rank()
        .over(partitionBy(TRANSACTIONS.ACCOUNT_ID)
                  .orderBy(TRANSACTIONS.AMOUNT.desc()))
        .as("amount_rank")
)
.from(TRANSACTIONS)
.orderBy(TRANSACTIONS.ACCOUNT_ID, TRANSACTIONS.CREATED_AT)
.fetch();

The DSL mirrors the SQL window specification precisely. The generated SQL is exactly what you specified — no ORM reinterpretation.

EF Core LINQ — window functions are outside the LINQ provider's translatable boundary. The only path is raw SQL:

// No LINQ equivalent — must fall back to a raw SQL string
var results = await context.Database
    .SqlQueryRaw<TransactionWithBalance>(@"
        SELECT
            account_id,
            amount,
            created_at,
            SUM(amount) OVER (
                PARTITION BY account_id
                ORDER BY created_at
                ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
            ) AS running_balance,
            RANK() OVER (
                PARTITION BY account_id
                ORDER BY amount DESC
            ) AS amount_rank
        FROM transactions
        ORDER BY account_id, created_at
    ")
    .ToListAsync();

Type safety is gone. Column names are strings. The compiler is blind to schema drift.

Recursive CTEs

jOOQ — inline CTE construction with full type propagation:

var hierarchy = name("org_hierarchy").fields("id", "name", "parent_id", "depth");

var orgTree = dsl
    .withRecursive(hierarchy.as(
        select(DEPARTMENTS.ID, DEPARTMENTS.NAME, DEPARTMENTS.PARENT_ID, val(0).as("depth"))
            .from(DEPARTMENTS)
            .where(DEPARTMENTS.PARENT_ID.isNull())
        .unionAll(
            select(
                DEPARTMENTS.ID, DEPARTMENTS.NAME, DEPARTMENTS.PARENT_ID,
                field(name("org_hierarchy", "depth"), Integer.class).plus(1)
            )
            .from(DEPARTMENTS)
            .join(table(name("org_hierarchy")))
            .on(field(name("org_hierarchy", "id"), Long.class).eq(DEPARTMENTS.PARENT_ID))
        )
    ))
    .select()
    .from(table(name("org_hierarchy")))
    .orderBy(field(name("depth")))
    .fetch();

EF Core LINQ — recursive CTEs are not representable in the LINQ provider. Raw SQL or database-side views are the only options.

MULTISET: jOOQ's Structural Superpower

jOOQ 3.15 introduced MULTISET — a SQL/XML-derived operator that allows nested collection results within a single query, eliminating both N+1 and the round-trip cost of multiple fetches. The result is not JOIN-inflated rows but a structurally nested result set materialized in one database round-trip:

record CustomerWithOrders(String name, String email, List<OrderSummary> orders) {}
record OrderSummary(Long id, BigDecimal amount, String status) {}

List<CustomerWithOrders> result = dsl
    .select(
        CUSTOMERS.NAME,
        CUSTOMERS.EMAIL,
        multiset(
            select(ORDERS.ID, ORDERS.AMOUNT, ORDERS.STATUS)
                .from(ORDERS)
                .where(ORDERS.CUSTOMER_ID.eq(CUSTOMERS.ID))
                .orderBy(ORDERS.CREATED_AT.desc())
        ).convertFrom(r -> r.into(OrderSummary.class))
    )
    .from(CUSTOMERS)
    .where(CUSTOMERS.STATUS.eq("ACTIVE"))
    .fetchInto(CustomerWithOrders.class);

Depending on dialect, jOOQ renders this using ARRAY_AGG with row constructors (PostgreSQL) or JSON_ARRAYAGG (MySQL). A single round-trip returns a fully materialized object graph with no Cartesian product.

EF Core's Include() achieves graph materialization, but through JOIN inflation or split queries — both controlled by EF Core's planner. On multi-level Include() chains over large result sets, the Cartesian product from nested JOINs can produce catastrophic query plans. EF Core 5's split query mode (AsSplitQuery()) addresses this with multiple queries, but at the cost of multiple round-trips and no transactional atomicity across the splits:

// Split query mode — multiple DB round-trips, no atomicity across splits
var customers = await context.Customers
    .Include(c => c.Orders)
        .ThenInclude(o => o.Items)
    .AsSplitQuery()   // 3 separate SELECT statements
    .ToListAsync();

MULTISET is strictly superior for this access pattern.

High-Concurrency I/O: Where the Architectures Diverge Most Consequentially

This is not an academic concern. At 10,000 concurrent database operations per second, the threading model is the bottleneck — not the SQL generation overhead.

EF Core: The Async-First Model

EF Core's async story is mature and pervasive. All terminal operators are Task-based. ADO.NET's ReadAsync() / ExecuteReaderAsync() are genuinely non-blocking: during the database network round-trip, the calling thread is returned to the thread pool to service other work. The async/await state machine the C# compiler generates handles continuation scheduling when I/O completes.

IAsyncEnumerable<T> extends this model to streaming result sets — the caller processes rows as they arrive from the server, with cooperative back-pressure through the iterator protocol:

// ASP.NET Core endpoint — streaming, fully non-blocking
[HttpGet("accounts/{accountId}/transactions")]
public async IAsyncEnumerable<TransactionDto> StreamTransactions(
    long accountId,
    [EnumeratorCancellation] CancellationToken ct)
{
    await foreach (var tx in context.Transactions
        .Where(t => t.AccountId == accountId && !t.IsVoided)
        .OrderByDescending(t => t.CreatedAt)
        .Select(t => new TransactionDto(t.Id, t.Amount, t.CreatedAt, t.Type))
        .AsAsyncEnumerable()
        .WithCancellation(ct))
    {
        yield return tx;
    }
}

Thread count does not scale with concurrent request count. A service handling 10,000 concurrent database reads runs efficiently on a thread pool sized to CPU count. This is the model's primary throughput advantage.

jOOQ + Java 21 Virtual Threads: Structured Concurrency Arrives

JDBC is a blocking API. Under the traditional thread-per-request model, a service with 500 concurrent database operations requires 500 OS threads — expensive to create, expensive to context-switch, and limited to ~10,000 per JVM in practice. This was jOOQ's principal liability at scale.

Project Loom in Java 21 fundamentally alters this calculus. Virtual threads are JVM-managed, heap-allocated continuation objects — not OS threads. They mount onto a small pool of OS carrier threads (default: CPU count). When a virtual thread calls a blocking JDBC operation and encounters a Socket.read() or SocketChannel.read(), the JVM unmounts it from the carrier thread. The carrier thread is immediately available to mount and execute another virtual thread. When the I/O syscall completes, the JVM schedules the parked virtual thread back onto any available carrier.

The result: blocking JDBC code achieves the throughput profile of async code without the cognitive complexity of reactive pipelines. Your jOOQ DSL code reads like synchronous, step-by-step SQL construction — because it is — while the JVM handles I/O concurrency transparently.

StructuredTaskScope (Java 21 Preview, production-ready in 23+) provides structured concurrency semantics — fan-out with coordinated failure propagation:

import java.util.concurrent.StructuredTaskScope;

record DashboardData(
    List<OrderRecord>    recentOrders,
    List<CustomerRecord> topCustomers,
    BigDecimal           periodRevenue
) {}

DashboardData loadDashboard(long tenantId, YearMonth period) throws Exception {
    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {

        var ordersFuture = scope.fork(() ->
            dsl.selectFrom(ORDERS)
               .where(ORDERS.TENANT_ID.eq(tenantId))
               .orderBy(ORDERS.CREATED_AT.desc())
               .limit(20)
               .fetchInto(OrderRecord.class)
        );

        var customersFuture = scope.fork(() ->
            dsl.select(CUSTOMERS.fields())
               .from(CUSTOMERS)
               .join(ORDERS).on(ORDERS.CUSTOMER_ID.eq(CUSTOMERS.ID))
               .where(ORDERS.TENANT_ID.eq(tenantId))
               .groupBy(CUSTOMERS.fields())
               .orderBy(sum(ORDERS.AMOUNT).desc())
               .limit(10)
               .fetchInto(CustomerRecord.class)
        );

        var revenueFuture = scope.fork(() ->
            dsl.select(coalesce(sum(ORDERS.AMOUNT), BigDecimal.ZERO))
               .from(ORDERS)
               .where(
                   ORDERS.TENANT_ID.eq(tenantId)
                       .and(ORDERS.CREATED_AT.greaterOrEqual(period.atDay(1)))
                       .and(ORDERS.CREATED_AT.lessThan(period.plusMonths(1).atDay(1)))
               )
               .fetchOneInto(BigDecimal.class)
        );

        scope.join().throwIfFailed();  // Waits for all; propagates first failure

        return new DashboardData(
            ordersFuture.get(),
            customersFuture.get(),
            revenueFuture.get()
        );
    }
}

Three concurrent JDBC queries. Three virtual threads. Normal sequential jOOQ DSL. No CompletableFuture chains, no reactive operators, no callback nesting. ShutdownOnFailure cancels all in-flight queries the moment any subtask throws.

Critical caveat — the connection pool boundary. Virtual threads do not expand your database connection pool. HikariCP's maximumPoolSize still governs the maximum number of concurrent live connections. If 10,000 virtual threads each attempt dsl.selectFrom(...) simultaneously, 9,980 park on the HikariCP acquisition semaphore — not on JDBC socket I/O. The semaphore parking is efficient (virtual threads release their carrier during the park), but the database is still limited to maximumPoolSize parallel queries. Size the pool for your database's connection capacity, not for your virtual thread concurrency.

jOOQ + R2DBC: True Non-Blocking for Reactive Pipelines

For architectures built on WebFlux or where Reactive Streams backpressure is architecturally required — high-throughput event pipelines, streaming ETL, pub/sub consumer processors — jOOQ provides native R2DBC integration. The DSLContext backed by an R2DBC connection factory returns Publisher<R> from every terminal operation:

// Project Reactor + jOOQ R2DBC — true non-blocking, backpressure-aware
public Flux<CustomerRevenueSummary> getTopCustomers(int tenantId, int limit) {
    return Flux.from(
        dsl.select(
               CUSTOMERS.ID,
               CUSTOMERS.NAME,
               sum(ORDERS.AMOUNT).as("total_revenue"),
               count(ORDERS.ID).as("order_count")
           )
           .from(CUSTOMERS)
           .join(ORDERS).on(ORDERS.CUSTOMER_ID.eq(CUSTOMERS.ID))
           .where(
               ORDERS.TENANT_ID.eq(tenantId)
                   .and(ORDERS.STATUS.eq("COMPLETED"))
           )
           .groupBy(CUSTOMERS.ID, CUSTOMERS.NAME)
           .orderBy(sum(ORDERS.AMOUNT).desc())
           .limit(limit)
    )
    .map(r -> new CustomerRevenueSummary(
        r.get(CUSTOMERS.ID),
        r.get(CUSTOMERS.NAME),
        r.get("total_revenue",  BigDecimal.class),
        r.get("order_count",    Long.class)
    ))
    .doOnError(e -> log.error("Revenue query failed for tenant {}", tenantId, e));
}

The Flux is cold — no query executes until subscription. Backpressure propagates through the R2DBC driver, controlling the rate at which result rows are fetched from the server. This is the correct model for streaming large result sets into downstream processors without materializing the full set in heap.

R2DBC driver maturity varies by database: r2dbc-postgresql (Pivotal/VMware) is production-grade; r2dbc-mssql and r2dbc-mysql are stable; Oracle's R2DBC support arrived late and has documented edge cases. Factor driver maturity into architectural decisions.

Concurrency Model Comparison

Dimension	EF Core async/await	jOOQ + Virtual Threads (Java 21)	jOOQ + R2DBC
I/O mechanism	True non-blocking (ADO.NET async)	Cooperative blocking (JVM parks VT on blocking call; carrier freed)	True non-blocking (R2DBC async driver)
Code cognitive load	Low — sequential `async/await`	Very low — identical to blocking code	High — reactive operator chains
Thread efficiency	High — threads freed during I/O wait	High — carrier threads freed when VT parks	High — no threads blocked on I/O
Backpressure	Not native	Not native	Native (Reactive Streams)
Stack trace clarity	Moderate (async continuations fragment traces)	Excellent (full, readable call stacks)	Poor (reactive chains obscure origin)
Structured concurrency	`Task.WhenAll` / `Task.WhenAny`	`StructuredTaskScope` (Java 21+)	Flux combinators (`zip`, `merge`, `flatMap`)
Connection pool behavior	Async acquisition — no thread blocked on pool wait	VT parks on semaphore — carrier freed	Async acquisition — no thread blocked
Production maturity	Very high	High (Java 21 GA, Loom stable)	Moderate (driver-dependent)
Cancellation model	`CancellationToken` propagation	`StructuredTaskScope` shutdown	Reactive `Disposable` / `cancel()`

Engineering Vector Comparison Matrix

Engineering Vector	jOOQ	LINQ / EF Core
Type safety model	Schema-grounded — compile-time contract via code gen	Model-grounded — C# types safe; expression translation fails at runtime
SQL expressibility	Near-complete — dialect-specific SQL, including vendor extensions	Limited — complex SQL requires untyped raw string fallback
Window functions	First-class DSL	Not supported in LINQ provider
Recursive CTEs	Full DSL support	Not supported in LINQ provider
UPSERT / MERGE	Dialect-aware (`onConflictDoUpdate`, `mergeInto`)	Not supported; raw SQL or workarounds
Nested results (N+1 elimination)	`MULTISET` — single round-trip, typed object graph	`Include()` / split queries — multiple round-trips or JOIN inflation
Schema drift detection	Build-time — regeneration forces compiler-guided remediation	Runtime — test coverage determines discovery timing
Query composition	Programmatic (explicit node tree construction; no deferred execution)	Deferred `IQueryable` — elegant layering, translatable boundary risk
Change tracking	Not provided — intentional	Full EF Core change tracker with identity map
Optimistic concurrency	Manual — row version conditions in DSL	Built-in — `[ConcurrencyCheck]`, `[Timestamp]`
Async / high-I/O model	Virtual Threads (Java 21) or R2DBC	Mature `async/await`, `IAsyncEnumerable`
Vendor-specific features	Dialect-aware — PostgreSQL `COPY`, Oracle `CONNECT BY`, SQL Server `OUTPUT`	Raw SQL fallback required for dialect-specific syntax
Migration safety	Regenerate → compiler guides all remediations	Dependent on model attribute hygiene and migration script correctness
Onboarding curve	Steep — code gen pipeline, DSL semantics, SQL discipline required	Low — LINQ is pervasive in .NET; EF Core conventions are well-documented
ORM capabilities	Not an ORM — intentionally and by design	Full ORM — navigation properties, lazy loading, identity map

Architectural Synthesis: Where Each Model Belongs

These tools are not interchangeable, and framing the question as a preference misses the point. The correct question is: what is the primary shape of your data access workload?

Choose jOOQ when:

The queries are the product. Financial systems, ledger-backed backends, reporting engines, and analytics platforms where window functions, recursive hierarchies, and complex aggregations are first-class requirements, not edge cases that you'll hand to a DBA. In regulated environments — PSD2, MiFID2, GDPR, DORA — schema drift that reaches a production runtime is a compliance event. jOOQ's build-time contract eliminates the category of failure, not just the incidence.

On Java 21+, the Virtual Thread model closes the throughput gap that once made jOOQ's synchronous JDBC model architecturally risky at scale. Structured concurrency gives you parallel database operations with clean, readable failure propagation — no reactive complexity.

Choose LINQ/EF Core when:

Your access pattern is entity-centric and CRUD-dominant. EF Core's change tracker, identity map, and SaveChanges() batching semantics are genuine force multipliers for write-heavy workloads that navigate complex object graphs. The Migrations toolchain allows a team to iterate on a domain model with high velocity in early development phases.

If your team is .NET-native, LINQ is not a library you add — it is woven into the language, the BCL, and every developer's existing intuitions. The cost of introducing jOOQ-equivalent thinking into a .NET shop is rebuilding those intuitions from scratch.

The CQRS Split (Production Reality)

The most defensible architecture in Java/Spring systems is not a binary choice. jOOQ and JPA/Hibernate operate cleanly within separate bounded contexts of the same hexagonal architecture:

// Write port — managed by Hibernate/JPA aggregate roots
public interface OrderRepository extends JpaRepository<Order, Long> {
    // Change tracking, optimistic locking, transactional consistency
}

// Read port — managed by jOOQ projections
public interface OrderQueryPort {
    List<OrderProjection>  findPendingOrdersWithCustomerDetails(Pageable pageable);
    RevenueReport          generateMonthlyReport(YearMonth month);
    List<OrderRiskSummary> identifyHighRiskOrders(RiskThreshold threshold);
}

// jOOQ adapter — no entity tracking, no identity map overhead, full SQL control
@Repository
@RequiredArgsConstructor
public class JooqOrderQueryAdapter implements OrderQueryPort {

    private final DSLContext dsl;

    @Override
    public List<OrderProjection> findPendingOrdersWithCustomerDetails(Pageable pageable) {
        return dsl
            .select(
                ORDERS.ID,
                ORDERS.AMOUNT,
                ORDERS.STATUS,
                CUSTOMERS.NAME.as("customerName"),
                CUSTOMERS.EMAIL.as("customerEmail"),
                count(ORDER_ITEMS.ID).over(partitionBy(ORDERS.ID)).as("itemCount")
            )
            .from(ORDERS)
            .join(CUSTOMERS).on(CUSTOMERS.ID.eq(ORDERS.CUSTOMER_ID))
            .join(ORDER_ITEMS).on(ORDER_ITEMS.ORDER_ID.eq(ORDERS.ID))
            .where(ORDERS.STATUS.eq("PENDING"))
            .orderBy(ORDERS.CREATED_AT.desc())
            .limit(pageable.getPageSize())
            .offset(pageable.getOffset())
            .fetchInto(OrderProjection.class);
    }

    @Override
    public RevenueReport generateMonthlyReport(YearMonth month) {
        var start = month.atDay(1);
        var end   = month.plusMonths(1).atDay(1);

        return dsl
            .select(
                trunc(ORDERS.CREATED_AT, DatePart.DAY).as("date"),
                sum(ORDERS.AMOUNT).as("daily_revenue"),
                count(ORDERS.ID).as("order_count"),
                sum(sum(ORDERS.AMOUNT))
                    .over(orderBy(trunc(ORDERS.CREATED_AT, DatePart.DAY))
                              .rowsBetweenUnboundedPreceding().andCurrentRow())
                    .as("cumulative_revenue")
            )
            .from(ORDERS)
            .where(
                ORDERS.STATUS.eq("COMPLETED")
                    .and(ORDERS.CREATED_AT.greaterOrEqual(start))
                    .and(ORDERS.CREATED_AT.lessThan(end))
            )
            .groupBy(trunc(ORDERS.CREATED_AT, DatePart.DAY))
            .orderBy(trunc(ORDERS.CREATED_AT, DatePart.DAY))
            .fetchInto(RevenueReport.class);
    }
}

The write side benefits from Hibernate's rich object graph management, optimistic locking via @Version, and the Outbox pattern for transactional consistency. The read side gets jOOQ's full SQL expressibility, zero entity tracking overhead on projections, and compile-time schema safety on every read model.

This CQRS-aligned split eliminates the false choice. You are not forfeiting ORM capabilities on writes to gain SQL power on reads — you are correctly partitioning the problem by access shape.

The Honest Bottom Line

LINQ is a language feature masquerading as a data access strategy. Its elegance derives from compiler integration and the deferred execution model, but that elegance has a hard ceiling: the boundary of what EF Core's expression tree translator can render as SQL. Push past it — with window functions, recursive hierarchies, lateral joins, or UPSERT semantics — and you are writing strings. The abstraction has ended.

jOOQ is a discipline. It demands that you think in SQL — which for engineers building data-intensive systems is not a cost. It is a qualification. The code generation pipeline is an upfront investment that pays compound returns in schema correctness, refactoring safety, and query expressibility across the lifetime of the project.

The performance gap at high I/O concurrency — once jOOQ's most significant architectural liability — has been effectively closed by Java 21's Virtual Threads. For the majority of data-intensive services, virtual thread concurrency is simpler to reason about, produces cleaner stack traces, and is operationally more predictable than the reactive pipeline model that R2DBC demands.

In any system where the database is a first-class engineering concern — not a persistence detail to be hidden behind a repository interface — jOOQ's model is the more honest, more maintainable, and ultimately more scalable choice. LINQ's model is the faster path to a working system. The distance between those two descriptions is the cost of technical debt.

Stop Hiding SQL Behind Your ORM: jOOQ, JPA, and JDBC Under Production Load

Amir Golmoradi — Thu, 11 Jun 2026 11:42:02 +0000

Most persistence debates in Java are framed incorrectly.

The question is not:

Should we use JPA, jOOQ, or JDBC?

The real question is:

Is this part of the system modeling object lifecycle, relational computation, or raw database interaction?

Those are different problems. Treating them as one problem is how teams end up with bloated repositories, unreadable Criteria API trees, native SQL strings inside @Query, unstable pagination, accidental N+1 queries, and production dashboards powered by List<Object[]>.

jOOQ exists because SQL is not an implementation detail. SQL is the language of the relational engine. If your application depends on joins, projections, aggregations, window functions, recursive queries, JSON operators, upserts, locking, or vendor-specific database features, hiding SQL behind an object graph is architectural denial.

This article is not a beginner introduction to jOOQ. It is a decision framework for senior engineers designing Java persistence layers that must survive real schema evolution, high query complexity, and production load.

The Architectural Conflict

Java applications usually want one of three persistence models:

Persistence Model	Primary Concern	Best Tooling Fit	Failure Mode
Object lifecycle persistence	Aggregate identity, invariants, dirty checking, optimistic locking	JPA / Hibernate	Over-fetching, lazy-loading surprises, persistence-context bloat
Relational query modeling	Joins, projections, reports, search screens, dashboards, read models	jOOQ	Build/codegen discipline required
Low-level database access	Minimal abstraction, library code, administrative SQL, edge-case driver behavior	JDBC / JdbcTemplate	Stringly typed SQL and manual mapping

The mistake is forcing one abstraction to cover all three.

JPA is excellent when the unit of work is an aggregate root and the application wants to persist domain state changes. jOOQ is excellent when the unit of work is a query. JDBC is excellent when no abstraction should exist between the application and the driver.

A serious architecture does not pick one blindly. It assigns each tool to the layer where its runtime model is honest.

Why Raw JDBC Is Still Not Enough

JDBC is transparent, but transparency is not the same as safety.

String sql = """
    SELECT a.id, a.currency, SUM(e.amount) AS balance
    FROM account a
    JOIN ledger_entry e ON e.account_id = a.id
    WHERE a.status = ?
    GROUP BY a.id, a.currency
    HAVING SUM(e.amount) > ?
    ORDER BY balance DESC
    """;

try (PreparedStatement statement = connection.prepareStatement(sql)) {
    statement.setString(1, "ACTIVE");
    statement.setBigDecimal(2, new BigDecimal("10000.00"));

    try (ResultSet rs = statement.executeQuery()) {
        while (rs.next()) {
            UUID accountId = rs.getObject("id", UUID.class);
            String currency = rs.getString("currency");
            BigDecimal balance = rs.getBigDecimal("balance");
        }
    }
}

This is not bad code. It is just structurally fragile.

The compiler cannot verify:

whether ledger_entry.amount exists
whether account.currency is still a VARCHAR
whether balance is aliased correctly
whether rs.getBigDecimal("balance") matches the selected expression
whether a column rename broke the query
whether the projection still matches the DTO constructor

JDBC gives full control, but it pushes schema correctness into runtime. In small scripts, that is acceptable. In a financial system, reporting engine, or high-volume backend, it is a liability.

Why JPA Breaks Down Outside Aggregate Persistence

JPA is not “bad.” That is a lazy take.

JPA is a powerful object persistence model. It tracks managed entities inside a persistence context, performs dirty checking, supports optimistic locking, maps associations, and provides a unit-of-work abstraction around aggregate state changes.

That model is valuable for this:

@Transactional
public void renameOrganization(UUID organizationId, String newName) {
    Organization organization = organizationRepository.findById(organizationId)
        .orElseThrow(() -> new OrganizationNotFoundException(organizationId));

    organization.renameTo(newName);

    // No explicit save required if the entity is managed.
    // Hibernate dirty checking will flush the changed state.
}

This is exactly where JPA belongs: domain state transition, aggregate invariant, transactional write.

But JPA becomes the wrong abstraction when the query no longer represents an entity graph.

This is where teams quietly abandon the ORM while pretending they still use it:

@Query(
    value = """
        SELECT
            a.region,
            COUNT(*) AS account_count,
            SUM(e.amount) AS total_balance
        FROM account a
        JOIN ledger_entry e ON e.account_id = a.id
        WHERE a.status = 'ACTIVE'
        GROUP BY a.region
        HAVING SUM(e.amount) > 100000
        ORDER BY total_balance DESC
        """,
    nativeQuery = true
)
List<Object[]> findRegionalBalances();

That code has the worst of both worlds:

SQL is hidden inside an annotation string.
Projection mapping is index-based or reflection-based.
Refactoring safety is weak.
The database schema is invisible to the compiler.
The repository method name pretends this is still object persistence.
The calling service now depends on implicit tuple shape.

This is not advanced JPA. This is a persistence layer admitting defeat.

What jOOQ Actually Provides

jOOQ is a schema-first SQL DSL and code generator.

The critical phrase is schema-first.

jOOQ does not ask you to pretend that Java classes own the relational model. It introspects the database schema and generates Java metadata for tables, columns, records, routines, enums, keys, and constraints.

A query stops being an opaque string:

String sql = "SELECT id, email FROM users WHERE status = ?";

And becomes a typed expression:

List<UserSummary> users = dsl
    .select(USER_ACCOUNT.ID, USER_ACCOUNT.EMAIL)
    .from(USER_ACCOUNT)
    .where(USER_ACCOUNT.STATUS.eq(UserStatus.ACTIVE))
    .fetch(Records.mapping(UserSummary::new));

The compiler now participates in schema correctness.

If email is renamed to email_address, regenerated jOOQ metadata removes USER_ACCOUNT.EMAIL. The application fails at compile time, not during a production request.

That is the entire value proposition.

Not “less boilerplate.”

Not “nicer SQL.”

Not “fluent syntax.”

The value is shifting schema drift from runtime failure to build-time failure.

Runtime Model: JDBC vs JPA vs jOOQ

Dimension	JDBC	JPA / Hibernate	jOOQ
Query representation	Raw string	JPQL, Criteria, derived methods, native strings	Generated DSL objects
Schema awareness	None at compile time	Entity model, not full schema	Generated database metadata
Mapping model	Manual	Entity hydration and persistence context	Records, DTOs, generated POJOs, custom mappers
Runtime overhead	Lowest abstraction overhead	Entity state tracking, proxies, dirty checking, first-level cache	Query construction plus mapping, no persistence context
SQL predictability	Exact SQL	SQL generated by provider, unless native query	Exact SQL generated from explicit DSL
Complex SQL support	Complete but stringly typed	Limited; often falls back to native SQL	Strong; models SQL directly
Write model	Manual	Excellent for aggregate writes	Excellent for explicit SQL writes
Read model	Manual mapping	Entity-centric; projections become awkward	Excellent for projections and read models
Failure timing	Runtime	Mix of startup/runtime/query execution	Build time for schema drift, runtime for data/constraint issues
Best use	Low-level access	Domain aggregate persistence	Complex queries, reporting, CQRS read side

The runtime distinction matters.

JPA maintains a persistence context. Every managed entity has identity, state, and lifecycle. That is useful when changing aggregates. It is wasteful when building a dashboard projection that should never become a managed entity.

jOOQ does not track object graphs. It builds SQL, binds parameters, executes statements, and maps results. That makes it predictable for read-heavy paths where the database is doing relational computation.

The Code Generator Is Not Optional

Using jOOQ without code generation is like using TypeScript with any everywhere. Technically possible. Architecturally pointless.

The generator is the mechanism that converts this:

CREATE TABLE account (
    id UUID PRIMARY KEY,
    owner_id UUID NOT NULL,
    currency CHAR(3) NOT NULL,
    status VARCHAR(32) NOT NULL,
    created_at TIMESTAMPTZ NOT NULL
);

CREATE TABLE ledger_entry (
    id UUID PRIMARY KEY,
    account_id UUID NOT NULL REFERENCES account(id),
    amount NUMERIC(19, 4) NOT NULL,
    direction VARCHAR(16) NOT NULL,
    posted_at TIMESTAMPTZ NOT NULL
);

Into typed Java metadata:

ACCOUNT.ID          // TableField<AccountRecord, UUID>
ACCOUNT.CURRENCY    // TableField<AccountRecord, String>
LEDGER_ENTRY.AMOUNT // TableField<LedgerEntryRecord, BigDecimal>
LEDGER_ENTRY.POSTED_AT

That generated model is what makes query refactoring safe.

A production-grade generation pipeline should look like this:

Flyway / Liquibase migrations
        ↓
Ephemeral database matching production dialect
        ↓
jOOQ code generation
        ↓
Java compilation
        ↓
Integration tests against the same dialect

Do not generate jOOQ classes from an H2 approximation of PostgreSQL. That is a fake safety net. If production is PostgreSQL, generate against PostgreSQL. If production is MySQL, generate against MySQL. Dialect behavior matters.

For CI, the reliable pattern is:

Start database container
Apply migrations
Generate jOOQ sources
Compile application
Run integration tests
Fail build on schema/code mismatch

Generated sources may be committed or generated during CI. Both strategies can work. What cannot work is allowing developers to generate from stale local databases while CI compiles against a different schema.

Maven Setup: Keep Versions and Credentials Out of the Plugin Body

Use a property-managed version. Do not hardcode credentials inside the plugin.

<properties>
    <java.version>21</java.version>
    <jooq.version>3.21.0</jooq.version>
    <postgres.version>42.7.5</postgres.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.jooq</groupId>
        <artifactId>jooq</artifactId>
        <version>${jooq.version}</version>
    </dependency>

    <dependency>
        <groupId>org.jooq</groupId>
        <artifactId>jooq-meta</artifactId>
        <version>${jooq.version}</version>
    </dependency>

    <dependency>
        <groupId>org.jooq</groupId>
        <artifactId>jooq-codegen</artifactId>
        <version>${jooq.version}</version>
    </dependency>

    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <version>${postgres.version}</version>
        <scope>runtime</scope>
    </dependency>
</dependencies>

A minimal Maven codegen configuration:

<plugin>
    <groupId>org.jooq</groupId>
    <artifactId>jooq-codegen-maven</artifactId>
    <version>${jooq.version}</version>

    <executions>
        <execution>
            <id>generate-jooq</id>
            <phase>generate-sources</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>

    <configuration>
        <jdbc>
            <driver>org.postgresql.Driver</driver>
            <url>${env.JOOQ_CODEGEN_JDBC_URL}</url>
            <user>${env.JOOQ_CODEGEN_DB_USERNAME}</user>
            <password>${env.JOOQ_CODEGEN_DB_PASSWORD}</password>
        </jdbc>

        <generator>
            <database>
                <name>org.jooq.meta.postgres.PostgresDatabase</name>
                <inputSchema>public</inputSchema>
                <includes>.*</includes>
                <excludes>flyway_schema_history</excludes>
            </database>

            <generate>
                <records>true</records>
                <pojos>false</pojos>
                <daos>false</daos>
                <fluentSetters>true</fluentSetters>
                <javaTimeTypes>true</javaTimeTypes>
            </generate>

            <target>
                <packageName>com.acme.persistence.jooq</packageName>
                <directory>target/generated-sources/jooq</directory>
            </target>
        </generator>
    </configuration>
</plugin>

Do not enable generated DAOs by default. They encourage an anemic table-centric persistence style. In serious applications, your query objects should be designed around use cases, not around generated table wrappers.

Spring Boot Configuration

Spring Boot can auto-configure jOOQ, but production systems usually need explicit control over settings, exception translation, logging, and execution listeners.

package com.acme.persistence.config;

import org.jooq.ExecuteListenerProvider;
import org.jooq.SQLDialect;
import org.jooq.conf.RenderQuotedNames;
import org.jooq.conf.Settings;
import org.jooq.impl.DefaultConfiguration;
import org.jooq.impl.DefaultDSLContext;
import org.jooq.tools.LoggerListener;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import javax.sql.DataSource;

@Configuration
class JooqConfiguration {

    @Bean
    DefaultDSLContext dslContext(
            DataSource dataSource,
            ExecuteListenerProvider exceptionTranslator
    ) {
        Settings settings = new Settings()
                .withRenderQuotedNames(RenderQuotedNames.NEVER)
                .withExecuteLogging(false)
                .withRenderFormatted(false);

        DefaultConfiguration configuration = new DefaultConfiguration();
        configuration.setDataSource(dataSource);
        configuration.setSQLDialect(SQLDialect.POSTGRES);
        configuration.setSettings(settings);
        configuration.setExecuteListenerProvider(exceptionTranslator);

        return new DefaultDSLContext(configuration);
    }
}

For local debugging, use logging at the datasource/proxy layer or a jOOQ ExecuteListener. Do not enable noisy SQL logging globally in production. Query observability should be structured: operation name, bind values policy, duration, row count, failure type, and correlation ID.

Use jOOQ for Read Models, Not Generic Repositories

Do not write this:

public interface GenericRepository<T, ID> {
    Optional<T> findById(ID id);
    List<T> findAll();
    void save(T entity);
}

That abstraction is junior-level damage. It hides the actual query shape and gives every use case the same fake persistence model.

A read model should be explicit:

package com.acme.accounts.readmodel;

import java.math.BigDecimal;
import java.time.OffsetDateTime;
import java.util.UUID;

public record AccountBalanceView(
        UUID accountId,
        String currency,
        BigDecimal balance,
        OffsetDateTime lastEntryAt
) {}

The query should express the real relational operation:

package com.acme.accounts.readmodel;

import lombok.RequiredArgsConstructor;
import org.jooq.DSLContext;
import org.jooq.Field;
import org.springframework.stereotype.Repository;

import java.math.BigDecimal;
import java.time.OffsetDateTime;
import java.util.Optional;
import java.util.UUID;

import static com.acme.persistence.jooq.Tables.ACCOUNT;
import static com.acme.persistence.jooq.Tables.LEDGER_ENTRY;
import static org.jooq.Records.mapping;
import static org.jooq.impl.DSL.coalesce;
import static org.jooq.impl.DSL.max;
import static org.jooq.impl.DSL.sum;

@Repository
@RequiredArgsConstructor
public class AccountBalanceQuery {

    private final DSLContext dsl;

    public Optional<AccountBalanceView> findBalance(UUID accountId) {
        Field<BigDecimal> balance = coalesce(
                sum(LEDGER_ENTRY.AMOUNT),
                BigDecimal.ZERO
        ).as("balance");

        Field<OffsetDateTime> lastEntryAt = max(LEDGER_ENTRY.POSTED_AT)
                .as("last_entry_at");

        return dsl
                .select(
                        ACCOUNT.ID,
                        ACCOUNT.CURRENCY,
                        balance,
                        lastEntryAt
                )
                .from(ACCOUNT)
                .leftJoin(LEDGER_ENTRY)
                    .on(LEDGER_ENTRY.ACCOUNT_ID.eq(ACCOUNT.ID))
                .where(ACCOUNT.ID.eq(accountId))
                .groupBy(ACCOUNT.ID, ACCOUNT.CURRENCY)
                .fetchOptional(mapping(AccountBalanceView::new));
    }
}

This is a read model. It is not an entity. It should not be managed by Hibernate. It should not have lazy relationships. It should not be forced through a fake repository abstraction.

The query shape is the contract.

Avoid Reflection Mapping When the Projection Is Critical

fetchInto(SomeDto.class) is convenient, but it relies on naming conventions and reflective mapping. That may be fine for internal admin screens. It is not ideal for critical paths where constructor shape should be explicit.

Prefer constructor mapping:

return dsl
        .select(
                ACCOUNT.ID,
                ACCOUNT.CURRENCY,
                balance,
                lastEntryAt
        )
        .from(ACCOUNT)
        .leftJoin(LEDGER_ENTRY)
            .on(LEDGER_ENTRY.ACCOUNT_ID.eq(ACCOUNT.ID))
        .where(ACCOUNT.ID.eq(accountId))
        .groupBy(ACCOUNT.ID, ACCOUNT.CURRENCY)
        .fetchOptional(mapping(AccountBalanceView::new));

Now the selected fields and the DTO constructor must agree at compile time.

That is the level of safety you want in payment, ledger, compliance, and reporting code.

Keyset Pagination: Stop Shipping Offset Pagination by Default

Offset pagination is common because it is easy:

.limit(pageSize)
.offset(page * pageSize)

It is also often the wrong default for high-volume tables.

The database still has to walk past skipped rows. Under concurrent inserts, offset pagination can duplicate or miss rows between requests. For event streams, ledger entries, audit logs, and inbox-like feeds, use keyset pagination.

package com.acme.ledger.readmodel;

import org.jooq.Condition;
import org.jooq.DSLContext;
import org.springframework.stereotype.Repository;

import java.time.OffsetDateTime;
import java.util.List;
import java.util.UUID;

import static com.acme.persistence.jooq.Tables.LEDGER_ENTRY;
import static org.jooq.impl.DSL.noCondition;

@Repository
public class LedgerEntryFeedQuery {

    private final DSLContext dsl;

    public LedgerEntryFeedQuery(DSLContext dsl) {
        this.dsl = dsl;
    }

    public List<LedgerEntryRow> findPage(UUID accountId, LedgerCursor cursor, int pageSize) {
        Condition afterCursor = cursor == null
                ? noCondition()
                : LEDGER_ENTRY.POSTED_AT.lt(cursor.postedAt())
                    .or(LEDGER_ENTRY.POSTED_AT.eq(cursor.postedAt())
                    .and(LEDGER_ENTRY.ID.lt(cursor.id())));

        return dsl
                .select(
                        LEDGER_ENTRY.ID,
                        LEDGER_ENTRY.ACCOUNT_ID,
                        LEDGER_ENTRY.AMOUNT,
                        LEDGER_ENTRY.DIRECTION,
                        LEDGER_ENTRY.POSTED_AT
                )
                .from(LEDGER_ENTRY)
                .where(LEDGER_ENTRY.ACCOUNT_ID.eq(accountId))
                .and(afterCursor)
                .orderBy(
                        LEDGER_ENTRY.POSTED_AT.desc(),
                        LEDGER_ENTRY.ID.desc()
                )
                .limit(pageSize)
                .fetch(record -> new LedgerEntryRow(
                        record.get(LEDGER_ENTRY.ID),
                        record.get(LEDGER_ENTRY.ACCOUNT_ID),
                        record.get(LEDGER_ENTRY.AMOUNT),
                        record.get(LEDGER_ENTRY.DIRECTION),
                        record.get(LEDGER_ENTRY.POSTED_AT)
                ));
    }

    public record LedgerCursor(OffsetDateTime postedAt, UUID id) {}
}

The ordering is stable because it uses a deterministic tie-breaker: posted_at DESC, id DESC.

That is the difference between pagination that demos well and pagination that survives production writes.

Upserts: Use Database Semantics Directly

A frequent ORM anti-pattern:

Optional<AccountBalance> existing = repository.findByAccountId(accountId);

if (existing.isPresent()) {
    existing.get().increase(delta);
} else {
    repository.save(new AccountBalance(accountId, currency, delta));
}

Under concurrency, this becomes a race unless guarded by constraints and transaction isolation. The database already has the correct primitive: unique constraint plus upsert.

CREATE TABLE account_balance (
    account_id UUID NOT NULL,
    currency CHAR(3) NOT NULL,
    amount NUMERIC(19, 4) NOT NULL,
    updated_at TIMESTAMPTZ NOT NULL,
    PRIMARY KEY (account_id, currency)
);

Express the database operation directly:

package com.acme.accounts.write;

import org.jooq.DSLContext;
import org.springframework.stereotype.Repository;

import java.math.BigDecimal;
import java.time.OffsetDateTime;
import java.util.UUID;

import static com.acme.persistence.jooq.Tables.ACCOUNT_BALANCE;

@Repository
public class AccountBalanceWriter {

    private final DSLContext dsl;

    public AccountBalanceWriter(DSLContext dsl) {
        this.dsl = dsl;
    }

    public void applyDelta(UUID accountId, String currency, BigDecimal delta, OffsetDateTime now) {
        dsl.insertInto(
                    ACCOUNT_BALANCE,
                    ACCOUNT_BALANCE.ACCOUNT_ID,
                    ACCOUNT_BALANCE.CURRENCY,
                    ACCOUNT_BALANCE.AMOUNT,
                    ACCOUNT_BALANCE.UPDATED_AT
                )
                .values(accountId, currency, delta, now)
                .onConflict(
                    ACCOUNT_BALANCE.ACCOUNT_ID,
                    ACCOUNT_BALANCE.CURRENCY
                )
                .doUpdate()
                .set(
                    ACCOUNT_BALANCE.AMOUNT,
                    ACCOUNT_BALANCE.AMOUNT.plus(delta)
                )
                .set(ACCOUNT_BALANCE.UPDATED_AT, now)
                .execute();
    }
}

This is not “database leakage.” This is using the database correctly.

The boundary should not hide concurrency semantics. The boundary should make them explicit.

Transactional Writes With Locking

jOOQ participates in Spring-managed transactions when it uses the same DataSource and transaction manager.

package com.acme.ledger.application;

import com.acme.ledger.domain.AccountNotPostableException;
import lombok.RequiredArgsConstructor;
import org.jooq.DSLContext;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.time.Clock;
import java.time.OffsetDateTime;
import java.util.UUID;

import static com.acme.persistence.jooq.Tables.ACCOUNT;
import static com.acme.persistence.jooq.Tables.LEDGER_ENTRY;

@Service
@RequiredArgsConstructor
public class PostLedgerEntryHandler {

    private final DSLContext dsl;
    private final Clock clock;

    @Transactional
    public UUID handle(PostLedgerEntryCommand command) {
        UUID accountId = dsl
                .select(ACCOUNT.ID)
                .from(ACCOUNT)
                .where(ACCOUNT.ID.eq(command.accountId()))
                .and(ACCOUNT.STATUS.eq("ACTIVE"))
                .forUpdate()
                .fetchOptional(ACCOUNT.ID)
                .orElseThrow(() -> new AccountNotPostableException(command.accountId()));

        UUID entryId = UUID.randomUUID();
        OffsetDateTime now = OffsetDateTime.now(clock);

        dsl.insertInto(
                    LEDGER_ENTRY,
                    LEDGER_ENTRY.ID,
                    LEDGER_ENTRY.ACCOUNT_ID,
                    LEDGER_ENTRY.AMOUNT,
                    LEDGER_ENTRY.DIRECTION,
                    LEDGER_ENTRY.POSTED_AT
                )
                .values(
                    entryId,
                    accountId,
                    command.amount(),
                    command.direction().name(),
                    now
                )
                .execute();

        return entryId;
    }
}

FOR UPDATE is not an implementation detail. It is part of the consistency model.

If two commands can mutate financial state concurrently, the transaction must say how contention is handled. Hiding that behind repository.save() does not make the race disappear.

Batch Inserts: Know What You Are Optimizing

JPA batching is provider-specific and sensitive to identifier strategy, flush size, persistence-context size, and ordering settings. With Hibernate, insert batching is limited when using identity-generated identifiers because the provider needs generated identifiers as entities become managed.

jOOQ batch execution is more direct:

List<LedgerEntryRecord> records = commands.stream()
        .map(command -> {
            LedgerEntryRecord record = dsl.newRecord(LEDGER_ENTRY);
            record.setId(UUID.randomUUID());
            record.setAccountId(command.accountId());
            record.setAmount(command.amount());
            record.setDirection(command.direction().name());
            record.setPostedAt(command.postedAt());
            return record;
        })
        .toList();

dsl.batchInsert(records).execute();

This reduces per-row statement overhead by using batched binds. It does not magically turn every workload into optimal bulk ingestion.

For very large imports, PostgreSQL COPY, database-native bulk loaders, partition-aware ingestion, or staging tables may beat both jOOQ and JPA. jOOQ is a strong general-purpose SQL construction and execution tool. It is not a replacement for every database-native ingestion mechanism.

Advanced SQL Should Not Be Second-Class Java Code

Window functions are a good example of where ORM abstractions collapse.

A risk dashboard might need the top accounts by daily outgoing transfer volume:

package com.acme.risk.readmodel;

import org.jooq.DSLContext;
import org.jooq.Field;
import org.springframework.stereotype.Repository;

import java.math.BigDecimal;
import java.time.LocalDate;
import java.util.List;

import static com.acme.persistence.jooq.Tables.TRANSFER;
import static org.jooq.impl.DSL.currentDate;
import static org.jooq.impl.DSL.date;
import static org.jooq.impl.DSL.rank;
import static org.jooq.impl.DSL.sum;

@Repository
public class RiskExposureQuery {

    private final DSLContext dsl;

    public RiskExposureQuery(DSLContext dsl) {
        this.dsl = dsl;
    }

    public List<AccountExposureRow> findTopOutgoingExposure(LocalDate businessDate, int limit) {
        Field<BigDecimal> outgoingTotal = sum(TRANSFER.AMOUNT).as("outgoing_total");

        return dsl
                .select(
                        TRANSFER.SOURCE_ACCOUNT_ID,
                        TRANSFER.CURRENCY,
                        outgoingTotal,
                        rank().over()
                                .partitionBy(TRANSFER.CURRENCY)
                                .orderBy(outgoingTotal.desc())
                                .as("currency_rank")
                )
                .from(TRANSFER)
                .where(TRANSFER.BUSINESS_DATE.eq(businessDate))
                .and(TRANSFER.STATUS.eq("SETTLED"))
                .groupBy(
                        TRANSFER.SOURCE_ACCOUNT_ID,
                        TRANSFER.CURRENCY
                )
                .orderBy(outgoingTotal.desc())
                .limit(limit)
                .fetch(record -> new AccountExposureRow(
                        record.get(TRANSFER.SOURCE_ACCOUNT_ID),
                        record.get(TRANSFER.CURRENCY),
                        record.get(outgoingTotal),
                        record.get("currency_rank", Integer.class)
                ));
    }
}

This query belongs in SQL form. The database optimizer understands it. The DSL keeps it composable and type-aware. A JPA entity graph does not improve this model; it only obscures it.

Dynamic Queries Without String Concatenation

Search endpoints often become string-concatenation traps.

With jOOQ, dynamic predicates remain typed values:

package com.acme.accounts.readmodel;

import org.jooq.Condition;
import org.jooq.DSLContext;
import org.springframework.stereotype.Repository;

import java.time.OffsetDateTime;
import java.util.List;

import static com.acme.persistence.jooq.Tables.ACCOUNT;
import static org.jooq.impl.DSL.noCondition;

@Repository
public class AccountSearchQuery {

    private final DSLContext dsl;

    public AccountSearchQuery(DSLContext dsl) {
        this.dsl = dsl;
    }

    public List<AccountSearchRow> search(AccountSearchCriteria criteria) {
        Condition condition = noCondition();

        if (criteria.status() != null) {
            condition = condition.and(ACCOUNT.STATUS.eq(criteria.status().name()));
        }

        if (criteria.currency() != null) {
            condition = condition.and(ACCOUNT.CURRENCY.eq(criteria.currency()));
        }

        if (criteria.createdAfter() != null) {
            condition = condition.and(ACCOUNT.CREATED_AT.ge(criteria.createdAfter()));
        }

        if (criteria.ownerId() != null) {
            condition = condition.and(ACCOUNT.OWNER_ID.eq(criteria.ownerId()));
        }

        return dsl
                .select(
                        ACCOUNT.ID,
                        ACCOUNT.OWNER_ID,
                        ACCOUNT.CURRENCY,
                        ACCOUNT.STATUS,
                        ACCOUNT.CREATED_AT
                )
                .from(ACCOUNT)
                .where(condition)
                .orderBy(ACCOUNT.CREATED_AT.desc(), ACCOUNT.ID.desc())
                .limit(criteria.limit())
                .fetch(record -> new AccountSearchRow(
                        record.get(ACCOUNT.ID),
                        record.get(ACCOUNT.OWNER_ID),
                        record.get(ACCOUNT.CURRENCY),
                        record.get(ACCOUNT.STATUS),
                        record.get(ACCOUNT.CREATED_AT)
                ));
    }
}

No string concatenation. No Criteria API ceremony. No hidden query derivation. No accidental SQL injection risk from manually assembled fragments.

The conditions are values.

Multi-Tenancy: Prefer Explicit Render Mapping Over Ad-Hoc SQL Rewriting

For schema-per-tenant systems, avoid casual query rewriting through listeners unless you have a very strong reason. Query listeners are powerful, but they can become invisible infrastructure magic.

Prefer deriving a tenant-specific configuration:

package com.acme.tenant;

import org.jooq.Configuration;
import org.jooq.DSLContext;
import org.jooq.conf.MappedSchema;
import org.jooq.conf.RenderMapping;
import org.jooq.conf.Settings;
import org.jooq.impl.DSL;
import org.springframework.stereotype.Component;

@Component
public class TenantDslFactory {

    private final Configuration baseConfiguration;

    public TenantDslFactory(DSLContext dsl) {
        this.baseConfiguration = dsl.configuration();
    }

    public DSLContext forTenantSchema(String tenantSchema) {
        Settings tenantSettings = baseConfiguration.settings()
                .withRenderMapping(new RenderMapping()
                        .withSchemata(new MappedSchema()
                                .withInput("public")
                                .withOutput(tenantSchema)));

        return DSL.using(baseConfiguration.derive(tenantSettings));
    }
}

This keeps tenant schema selection explicit at the boundary.

Also: validate tenantSchema against tenant metadata. Never accept raw schema names from request input and feed them into SQL rendering.

Reactive jOOQ: Useful, But Not a Free Performance Upgrade

jOOQ supports reactive execution through publisher-based query execution when configured with R2DBC. That does not automatically make a persistence layer faster.

Reactive database access is useful when:

the application stack is already reactive end-to-end
request threads must not block on I/O
the driver, connection pool, transaction manager, and execution model are all reactive
backpressure and cancellation semantics are actually understood by the team

It is not useful when a blocking Spring MVC application wraps database calls in reactive types and calls it architecture.

A reactive query shape looks similar:

Flux<AccountSearchRow> rows = Flux.from(
        reactiveDsl
                .select(
                        ACCOUNT.ID,
                        ACCOUNT.OWNER_ID,
                        ACCOUNT.CURRENCY,
                        ACCOUNT.STATUS,
                        ACCOUNT.CREATED_AT
                )
                .from(ACCOUNT)
                .where(ACCOUNT.STATUS.eq("ACTIVE"))
                .orderBy(ACCOUNT.CREATED_AT.desc())
                .limit(100)
).map(record -> new AccountSearchRow(
        record.get(ACCOUNT.ID),
        record.get(ACCOUNT.OWNER_ID),
        record.get(ACCOUNT.CURRENCY),
        record.get(ACCOUNT.STATUS),
        record.get(ACCOUNT.CREATED_AT)
));

The query DSL is not the hard part. The hard part is transaction boundaries, connection ownership, backpressure, driver maturity, and operational debugging.

Use reactive jOOQ because your system has a coherent non-blocking architecture, not because “reactive” sounds modern.

The Correct Hybrid: JPA for Aggregate Writes, jOOQ for Read Models

The strongest Java persistence architectures do not force JPA and jOOQ to compete.

They separate responsibilities.

Command side
  Application service
      ↓
  Domain aggregate
      ↓
  JPA repository
      ↓
  Transactional write model

Query side
  Query handler
      ↓
  jOOQ read model query
      ↓
  DTO / projection / API response

Example:

@Service
@RequiredArgsConstructor
public class OrganizationCommandService {

    private final OrganizationRepository organizationRepository;

    @Transactional
    public void renameOrganization(RenameOrganizationCommand command) {
        Organization organization = organizationRepository.findById(command.organizationId())
                .orElseThrow(() -> new OrganizationNotFoundException(command.organizationId()));

        organization.rename(command.newName());
    }
}

That is a good JPA use case.

Now the dashboard:

@Repository
@RequiredArgsConstructor
public class OrganizationDashboardQuery {

    private final DSLContext dsl;

    public OrganizationDashboardView getDashboard(UUID organizationId) {
        return dsl
                .select(
                        ORGANIZATION.ID,
                        ORGANIZATION.NAME,
                        ORGANIZATION.STATUS,
                        ACCOUNT.ID.count().as("account_count"),
                        coalesce(sum(ACCOUNT_BALANCE.AMOUNT), BigDecimal.ZERO).as("total_balance")
                )
                .from(ORGANIZATION)
                .leftJoin(ACCOUNT)
                    .on(ACCOUNT.ORGANIZATION_ID.eq(ORGANIZATION.ID))
                .leftJoin(ACCOUNT_BALANCE)
                    .on(ACCOUNT_BALANCE.ACCOUNT_ID.eq(ACCOUNT.ID))
                .where(ORGANIZATION.ID.eq(organizationId))
                .groupBy(
                        ORGANIZATION.ID,
                        ORGANIZATION.NAME,
                        ORGANIZATION.STATUS
                )
                .fetchOne(record -> new OrganizationDashboardView(
                        record.get(ORGANIZATION.ID),
                        record.get(ORGANIZATION.NAME),
                        record.get(ORGANIZATION.STATUS),
                        record.get("account_count", Integer.class),
                        record.get("total_balance", BigDecimal.class)
                ));
    }
}

This should not be a JPA entity graph. It is a read projection.

The Consistency Rules When Mixing JPA and jOOQ

Mixing JPA and jOOQ in one application is safe. Mixing them carelessly inside the same transaction is not.

Follow these rules:

Scenario	Risk	Required Discipline
JPA writes, jOOQ reads in same transaction	JPA changes may still be pending in persistence context	Call `entityManager.flush()` before the jOOQ query
jOOQ writes, JPA reads entity already loaded earlier	JPA first-level cache may return stale state	Avoid this flow, or call `entityManager.refresh(entity)` / `clear()` deliberately
Both JPA and jOOQ write same tables	Conflicting ownership and stale entity state	Assign write ownership per use case; do not casually interleave
jOOQ updates rows behind managed entities	Persistence context no longer reflects database state	Refresh, clear, or isolate the jOOQ write in a separate boundary
jOOQ read models over JPA-owned tables	Usually safe	Keep queries read-only and transactionally consistent

This is the part most hybrid articles under-explain.

The issue is not whether JPA and jOOQ can share a DataSource. They can.

The issue is that JPA has an identity map and jOOQ does not know it exists.

Decision Matrix

Use Case	JDBC	JPA	jOOQ	Recommendation
Simple aggregate CRUD	Possible but manual	Excellent	Possible but table-centric	Use JPA
Rich domain invariants	Poor fit	Excellent	Poor fit unless manually modeled	Use JPA
Dashboard projection	Manual and brittle	Awkward	Excellent	Use jOOQ
Reporting query	Manual and brittle	Poor fit	Excellent	Use jOOQ
Window functions	Supported but stringly typed	Poor / native SQL escape	Excellent	Use jOOQ
Bulk ingestion	Good with batching/COPY	Provider-sensitive	Good, but not always best	JDBC/native or jOOQ
Dynamic search filters	String builder risk	Criteria API complexity	Excellent	Use jOOQ
Stored procedures	Manual	Vendor awkwardness	Generated wrappers	Use jOOQ
Library with no persistence dependency	Excellent	Bad fit	Bad fit	Use JDBC
Event-sourced write store	Good	Often unnecessary	Good	JDBC or jOOQ
CQRS read side	Manual	Wrong abstraction	Excellent	Use jOOQ
CQRS command side with aggregates	Manual	Excellent	Possible but lower-level	Use JPA

Anti-Patterns

1. Generic Repository Over jOOQ

If you wrap jOOQ in a generic repository that only exposes save, findById, and findAll, you destroyed the reason to use jOOQ.

jOOQ’s strength is query shape. Do not erase it.

2. Native Queries Returning `Object[]`

This is not a production abstraction:

List<Object[]> rows = repository.findSomethingComplicated();

It is a runtime tuple with undocumented positional semantics.

Use a DTO, constructor mapping, interface projection, or jOOQ record mapper.

3. Entity Graphs for Dashboard APIs

A dashboard is not an aggregate. A dashboard is a projection.

Do not hydrate 200 entities to compute a response the database can calculate in one query.

4. Offset Pagination on Hot Tables

Offset pagination is fine for small admin tables. It is a poor default for append-heavy datasets.

Use keyset pagination for ledgers, audit logs, feeds, timelines, and transaction history.

5. Reactive Wrappers Around Blocking JDBC

Wrapping blocking JDBC calls in Mono.fromCallable() does not make the database layer reactive. It only moves blocking work somewhere else.

Recommended Architecture

For a serious Spring Boot backend using DDD, Hexagonal Architecture, or CQRS:

src/main/java/com/acme
  ├── accounts
  │   ├── domain
  │   │   └── Account.java
  │   ├── application
  │   │   ├── command
  │   │   │   └── RenameAccountHandler.java
  │   │   └── query
  │   │       └── GetAccountDashboardHandler.java
  │   ├── infrastructure
  │   │   ├── persistence
  │   │   │   ├── AccountJpaRepository.java
  │   │   │   └── AccountBalanceQuery.java
  │   │   └── web
  │   │       └── AccountController.java
  │   └── readmodel
  │       └── AccountDashboardView.java
  └── persistence
      └── jooq
          └── generated sources

Use JPA repositories for aggregate persistence.

Use jOOQ query classes for read models.

Do not put jOOQ-generated records into your domain model. They are persistence artifacts. Keep them at the infrastructure boundary.

Final Recommendation

Use JPA when the business operation is centered on an aggregate lifecycle.

Use jOOQ when the business operation is centered on relational data retrieval, projection, reporting, search, aggregation, or database-native behavior.

Use JDBC when the abstraction itself is unnecessary or harmful.

The strongest architecture is not “jOOQ everywhere” or “JPA everywhere.”

The strongest architecture is honest about the shape of the problem:

Aggregate state transition → JPA
Relational read model      → jOOQ
Driver-level operation     → JDBC

SQL is not something to hide.

SQL is part of the system’s design surface. Treat it with the same engineering discipline you apply to Java code: compile-time safety, explicit boundaries, testable behavior, stable contracts, and production observability.

That is where jOOQ earns its place.