JOOQ difference between DSL and DSLContext, when to use DSL instead of a dslContext instance?

When having queries like this, for the inner query, should I use DSL or the dslContext that I have?

return dslContext
    .insertInto(TABLE_FOO)
    .select(
        dslContext         // vs DSL here
            .select(
                ...
            .from(TABLE_BAR))
    .execute();

From my research, I understand that DSL is JOOQ’s entrypoint to express SQL without being in the context of a connection. In the above example, is it safe to use DSL instead of a dslContext object?

Answer

The name DSLContext means

DSL in the context of a Configuration

The API is equivalent, though technically different. All of DSL‘s methods are static to allow for static imports, which is particularly useful for function calls or your nested select case. It is more readable to use DSL.select() like this:

import static org.jooq.impl.DSL.*;

// ...
return dslContext
    .insertInto(TABLE_FOO)
    .select(
        select(...)
        .from(TABLE_BAR))
    .execute();

However, objects constructed using static API cannot be executed, hence you will need to use the DSLContext API for your top level queries if you want to execute them like you did.

See also: https://www.jooq.org/doc/latest/manual/sql-building/dsl-context/

DSLContext references a org.jooq.Configuration, an object that configures jOOQ’s behaviour when executing queries (see SQL execution for more details). Unlike the static DSL, the DSLContext allow for creating SQL statements that are already “configured” and ready for execution.