Available in versions: Dev (3.20) | Latest (3.19) | 3.18 | 3.17 | 3.16 | 3.15 | 3.14 | 3.13 | 3.12 | 3.11 | 3.10

The DSLContext API

Applies to ✅ Open Source Edition ✅ Express Edition ✅ Professional Edition ✅ Enterprise Edition

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.

Fluent creation of a DSLContext object

The DSLContext object can be created fluently from the DSL type:

// Create it from a pre-existing configuration
DSLContext create = DSL.using(configuration);

// Create it from ad-hoc arguments
DSLContext create = DSL.using(connection, dialect);

If you do not have a reference to a pre-existing Configuration object (e.g. created from org.jooq.impl.DefaultConfiguration), the various overloaded DSL.using() methods will create one for you.

Contents of a Configuration object

A Configuration can be supplied with these objects:

org.jooq.SQLDialect : The dialect of your database. This may be any of the currently supported database types (see SQL Dialect for more details)
org.jooq.conf.Settings : An optional runtime configuration (see Custom Settings for more details)
org.jooq.ExecuteListenerProvider : An optional reference to a provider class that can provide execute listeners to jOOQ (see ExecuteListeners for more details)
org.jooq.ParseListenerProvider : An optional reference to a provider class that can provide parse listeners to jOOQ (see SQL Parser Listener for more details)
org.jooq.RecordListenerProvider : An optional reference to a provider class that can provide record listeners to jOOQ (see CRUD SPI: RecordListener for more details)
org.jooq.RecordMapperProvider : An optional reference to a provider class that can provide record mappers to jOOQ (see for more details)
JDBC access:
- java.sql.Connection : An optional JDBC Connection that will be re-used for the whole lifecycle of your Configuration (see Connection vs. DataSource for more details). For simplicity, this is the use-case referenced from this manual, most of the time.
- java.sql.DataSource : An optional JDBC DataSource that will be re-used for the whole lifecycle of your Configuration. If you prefer using DataSources over Connections, jOOQ will internally fetch new Connections from your DataSource, conveniently closing them again after query execution. This is particularly useful in Java EE or Spring contexts (see Connection vs. DataSource for more details)
- org.jooq.ConnectionProvider : A custom abstraction that is used by jOOQ to "acquire" and "release" connections. jOOQ will internally "acquire" new Connections from your ConnectionProvider, conveniently "releasing" them again after query execution. (see Connection vs. DataSource for more details)
R2DBC access:
- io.r2dbc.spi.Connection : An optional R2DBC Connection that will be re-used for the whole lifecycle of your Configuration (see Connection vs. DataSource for more details). For simplicity, this is the use-case referenced from this manual, most of the time.
- io.r2dbc.spi.ConnectionFactory : An optional R2DBC ConnectionFactory that will be re-used for the whole lifecycle of your Configuration. If you prefer using ConnectionFactories over Connections, jOOQ will internally fetch new Connections from your ConnectionFactory, conveniently closing them again after query execution. This is particularly useful in Spring contexts (see Connection vs. DataSource for more details)

Usage of DSLContext

Wrapping a Configuration object, a DSLContext can construct statements, for later execution. An example is given here:

// The DSLContext is "configured" with a Connection and a SQLDialect
DSLContext create = DSL.using(connection, dialect);

// This select statement contains an internal reference to the DSLContext's Configuration:
Select<?> select = create.selectOne();

// Using the internally referenced Configuration, the select statement can now be executed:
Result<?> result = select.fetch();

Note that you do not need to keep a reference to a DSLContext. You may as well inline your local variable, and fluently execute a SQL statement as such:

// Execute a statement from a single execution chain:
Result<?> result =
DSL.using(connection, dialect)
   .select()
   .from(BOOK)
   .where(BOOK.TITLE.like("Animal%"))
   .fetch();

4.2.1.: SQL Dialect
4.2.2.: SQL Dialect Family
4.2.3.: Connection vs. DataSource
4.2.4.: Custom data
4.2.5.: Custom ExecuteListeners
4.2.6.: Custom Unwrappers
4.2.7.: Custom Settings
4.2.7.1.: Auto-attach Records
4.2.7.2.: Backslash Escaping
4.2.7.3.: Batch size
4.2.7.4.: Dialect compatibility (new)
4.2.7.5.: Execute Logging
4.2.7.6.: Fetch Warnings
4.2.7.7.: GROUP_CONCAT Configuration (new)
4.2.7.8.: Identifier style
4.2.7.9.: Implicit join type
4.2.7.10.: Inline Threshold
4.2.7.11.: IN-list Padding
4.2.7.12.: Interpreter Configuration
4.2.7.13.: JDBC Flags
4.2.7.14.: Keyword style
4.2.7.15.: Listener Invocation Order
4.2.7.16.: Locales
4.2.7.17.: Map JPA Annotations
4.2.7.18.: Object qualification
4.2.7.19.: Optimistic Locking
4.2.7.20.: Parameter name prefix
4.2.7.21.: Parameter types
4.2.7.22.: Parser Configuration
4.2.7.23.: Reflection caching
4.2.7.24.: Return all columns on store
4.2.7.25.: Return Identity Value On Store
4.2.7.26.: Runtime catalog, schema and table mapping
4.2.7.27.: Scalar subqueries for stored functions
4.2.7.28.: Statement Type
4.2.7.29.: Updatable Primary Keys
4.2.8.: Thread safety

previous : next

Feedback

Do you have any feedback about this page? We'd love to hear it!

Tell us a little bit about yourself and join our newsletter (examples)

The DSLContext API

Fluent creation of a DSLContext object

Contents of a Configuration object

Usage of DSLContext

Table of contents

References to this page

Feedback

Community

Support

Legal

Documentation