0
# Query Execution and Contexts
1

2
Core functionality for creating database contexts, executing queries, and managing connections. The DSLContext serves as the primary entry point for all database operations with support for both JDBC and R2DBC.
3

4
## Capabilities
5

6
### DSL Factory Methods
7

8
Static factory methods in the DSL class for creating DSLContext instances with various connection types and configurations.
9

10
```java { .api }
11
/**
12
 * Create a DSLContext for a specific SQL dialect without connection
13
 * @param dialect The SQL dialect to use
14
 * @return DSLContext instance for query building without execution
15
 */
16
public static DSLContext using(SQLDialect dialect);
17

18
/**
19
 * Create a DSLContext with custom settings
20
 * @param dialect The SQL dialect to use
21
 * @param settings Configuration settings
22
 * @return DSLContext instance with custom configuration
23
 */
24
public static DSLContext using(SQLDialect dialect, Settings settings);
25

26
/**
27
 * Create a closeable DSLContext from URL string
28
 * @param url JDBC connection URL
29
 * @return CloseableDSLContext that manages its own connection
30
 */
31
public static CloseableDSLContext using(String url);
32

33
/**
34
 * Create a closeable DSLContext with credentials
35
 * @param url JDBC connection URL
36
 * @param username Database username
37
 * @param password Database password
38
 * @return CloseableDSLContext that manages its own connection
39
 */
40
public static CloseableDSLContext using(String url, String username, String password);
41

42
/**
43
 * Create a closeable DSLContext with Properties
44
 * @param url JDBC connection URL
45
 * @param properties Connection properties
46
 * @return CloseableDSLContext that manages its own connection
47
 */
48
public static CloseableDSLContext using(String url, Properties properties);
49

50
/**
51
 * Create a DSLContext from existing JDBC connection
52
 * @param connection JDBC connection (dialect auto-detected)
53
 * @return DSLContext using the provided connection
54
 */
55
public static DSLContext using(Connection connection);
56

57
/**
58
 * Create a DSLContext from JDBC connection with specific dialect
59
 * @param connection JDBC connection
60
 * @param dialect SQL dialect to use
61
 * @return DSLContext using the provided connection and dialect
62
 */
63
public static DSLContext using(Connection connection, SQLDialect dialect);
64

65
/**
66
 * Create a DSLContext from JDBC connection with settings
67
 * @param connection JDBC connection
68
 * @param settings Configuration settings
69
 * @return DSLContext using the provided connection and settings
70
 */
71
public static DSLContext using(Connection connection, Settings settings);
72

73
/**
74
 * Create a DSLContext from JDBC connection with dialect and settings
75
 * @param connection JDBC connection
76
 * @param dialect SQL dialect to use
77
 * @param settings Configuration settings
78
 * @return DSLContext using the provided connection, dialect and settings
79
 */
80
public static DSLContext using(Connection connection, SQLDialect dialect, Settings settings);
81

82
/**
83
 * Create a DSLContext from DataSource
84
 * @param datasource JDBC DataSource
85
 * @param dialect SQL dialect to use
86
 * @return DSLContext using the provided DataSource
87
 */
88
public static DSLContext using(DataSource datasource, SQLDialect dialect);
89

90
/**
91
 * Create a DSLContext from DataSource with settings
92
 * @param datasource JDBC DataSource
93
 * @param dialect SQL dialect to use
94
 * @param settings Configuration settings
95
 * @return DSLContext using the provided DataSource, dialect and settings
96
 */
97
public static DSLContext using(DataSource datasource, SQLDialect dialect, Settings settings);
98

99
/**
100
 * Create a DSLContext from ConnectionProvider
101
 * @param connectionProvider Custom connection provider
102
 * @param dialect SQL dialect to use
103
 * @return DSLContext using the provided ConnectionProvider
104
 */
105
public static DSLContext using(ConnectionProvider connectionProvider, SQLDialect dialect);
106

107
/**
108
 * Create a DSLContext from ConnectionProvider with settings
109
 * @param connectionProvider Custom connection provider
110
 * @param dialect SQL dialect to use
111
 * @param settings Configuration settings
112
 * @return DSLContext using the provided ConnectionProvider, dialect and settings
113
 */
114
public static DSLContext using(ConnectionProvider connectionProvider, SQLDialect dialect, Settings settings);
115

116
/**
117
 * Create a DSLContext from R2DBC ConnectionFactory
118
 * @param connectionFactory R2DBC ConnectionFactory for reactive access
119
 * @return DSLContext for reactive database operations
120
 */
121
public static DSLContext using(ConnectionFactory connectionFactory);
122

123
/**
124
 * Create a DSLContext from R2DBC ConnectionFactory with dialect
125
 * @param connectionFactory R2DBC ConnectionFactory for reactive access
126
 * @param dialect SQL dialect to use
127
 * @return DSLContext for reactive database operations
128
 */
129
public static DSLContext using(ConnectionFactory connectionFactory, SQLDialect dialect);
130

131
/**
132
 * Create a DSLContext from R2DBC ConnectionFactory with dialect and settings
133
 * @param connectionFactory R2DBC ConnectionFactory for reactive access
134
 * @param dialect SQL dialect to use
135
 * @param settings Configuration settings
136
 * @return DSLContext for reactive database operations
137
 */
138
public static DSLContext using(ConnectionFactory connectionFactory, SQLDialect dialect, Settings settings);
139

140
/**
141
 * Create a DSLContext from R2DBC Connection
142
 * @param connection R2DBC Connection for reactive access
143
 * @return DSLContext for reactive database operations
144
 */
145
public static DSLContext using(io.r2dbc.spi.Connection connection);
146

147
/**
148
 * Create a DSLContext from R2DBC Connection with dialect
149
 * @param connection R2DBC Connection for reactive access
150
 * @param dialect SQL dialect to use
151
 * @return DSLContext for reactive database operations
152
 */
153
public static DSLContext using(io.r2dbc.spi.Connection connection, SQLDialect dialect);
154

155
/**
156
 * Create a DSLContext from R2DBC Connection with dialect and settings
157
 * @param connection R2DBC Connection for reactive access
158
 * @param dialect SQL dialect to use
159
 * @param settings Configuration settings
160
 * @return DSLContext for reactive database operations
161
 */
162
public static DSLContext using(io.r2dbc.spi.Connection connection, SQLDialect dialect, Settings settings);
163

164
/**
165
 * Create a DSLContext from Configuration
166
 * @param configuration Complete jOOQ configuration
167
 * @return DSLContext using the provided configuration
168
 */
169
public static DSLContext using(Configuration configuration);
170
```
171

172
**Usage Examples:**
173

174
```java
175
import static org.jooq.impl.DSL.*;
176
import org.jooq.*;
177
import java.sql.*;
178

179
// Simple dialect-only context for query building
180
DSLContext create = using(SQLDialect.POSTGRES);
181
String sql = create.select().from("users").getSQL();
182

183
// JDBC connection with auto-detected dialect
184
Connection conn = DriverManager.getConnection("jdbc:h2:mem:test");
185
DSLContext create = using(conn);
186

187
// Managed connection from URL
188
try (CloseableDSLContext create = using("jdbc:h2:mem:test", "sa", "")) {
189
    Result<Record> result = create.select().from("users").fetch();
190
}
191

192
// DataSource with specific dialect
193
DataSource ds = new HikariDataSource();
194
DSLContext create = using(ds, SQLDialect.MYSQL);
195
```
196

197
### DSLContext Interface
198

199
Primary interface for executing queries and accessing database functionality.
200

201
```java { .api }
202
public interface DSLContext extends Scope {
203
    /**
204
     * Access the SQL parser API for parsing SQL strings
205
     * @return Parser instance for this context
206
     */
207
    Parser parser();
208
    
209
    /**
210
     * Get a JDBC connection that parses SQL through jOOQ first
211
     * @return Connection wrapper with jOOQ parsing
212
     */
213
    Connection parsingConnection();
214
    
215
    /**
216
     * Access database metadata information
217
     * @return Meta instance for schema introspection
218
     */
219
    Meta meta();
220
    
221
    /**
222
     * Execute a query and return affected row count
223
     * @param query Query to execute
224
     * @return Number of affected rows
225
     */
226
    int execute(Query query);
227
    
228
    /**
229
     * Fetch all records from a table
230
     * @param table Table to fetch from
231
     * @return Result containing all records
232
     */
233
    <R extends Record> Result<R> fetch(Table<R> table);
234
    
235
    /**
236
     * Fetch records matching a condition
237
     * @param table Table to fetch from
238
     * @param condition WHERE condition
239
     * @return Result containing matching records
240
     */
241
    <R extends Record> Result<R> fetch(Table<R> table, Condition condition);
242
    
243
    /**
244
     * Execute code within a transaction, returning a result
245
     * @param transactional Code to execute in transaction
246
     * @return Result from the transactional code
247
     */
248
    <T> T transactionResult(ContextTransactionalCallable<T> transactional);
249
    
250
    /**
251
     * Execute code within a transaction
252
     * @param transactional Code to execute in transaction
253
     */
254
    void transaction(ContextTransactionalRunnable transactional);
255
}
256
```
257

258
### Query Interface
259

260
Base interface for all executable SQL statements.
261

262
```java { .api }
263
public interface Query extends QueryPart, Attachable {
264
    /**
265
     * Execute the query synchronously
266
     * @return Number of affected rows
267
     */
268
    int execute();
269
    
270
    /**
271
     * Execute the query asynchronously
272
     * @return CompletionStage with number of affected rows
273
     */
274
    CompletionStage<Integer> executeAsync();
275
    
276
    /**
277
     * Bind a named parameter to a value
278
     * @param param Parameter name
279
     * @param value Parameter value
280
     * @return Query with bound parameter
281
     */
282
    Query bind(String param, Object value);
283
    
284
    /**
285
     * Set query timeout in seconds
286
     * @param seconds Timeout in seconds
287
     * @return Query with timeout set
288
     */
289
    Query queryTimeout(int seconds);
290
    
291
    /**
292
     * Check if query can be executed
293
     * @return true if query is executable
294
     */
295
    boolean isExecutable();
296
    
297
    /**
298
     * Get the SQL string for this query
299
     * @return SQL string representation
300
     */
301
    String getSQL();
302
    
303
    /**
304
     * Get the SQL string with parameter placeholders
305
     * @param paramType Parameter placeholder type
306
     * @return SQL string with specified parameter format
307
     */
308
    String getSQL(ParamType paramType);
309
}
310
```
311

312
### Connection Management
313

314
Interfaces for managing database connections and connection pooling.
315

316
```java { .api }
317
public interface ConnectionProvider {
318
    /**
319
     * Acquire a connection from the provider
320
     * @return JDBC Connection
321
     */
322
    Connection acquire() throws DataAccessException;
323
    
324
    /**
325
     * Release a connection back to the provider
326
     * @param connection Connection to release
327
     */
328
    void release(Connection connection) throws DataAccessException;
329
}
330

331
public interface CloseableDSLContext extends DSLContext, AutoCloseable {
332
    /**
333
     * Close the context and release any managed resources
334
     */
335
    void close() throws DataAccessException;
336
}
337
```
338

339
**Usage Examples:**
340

341
```java
342
// Transaction with result
343
Integer bookCount = create.transactionResult(configuration -> {
344
    DSLContext txCreate = using(configuration);
345
    
346
    // Insert author
347
    AuthorRecord author = txCreate.newRecord(AUTHOR);
348
    author.setFirstName("John");
349
    author.setLastName("Doe");
350
    author.store();
351
    
352
    // Insert books
353
    return txCreate.insertInto(BOOK)
354
        .set(BOOK.TITLE, "My Book")
355
        .set(BOOK.AUTHOR_ID, author.getId())
356
        .execute();
357
});
358

359
// Async execution
360
CompletionStage<Integer> future = create
361
    .insertInto(USER)
362
    .set(USER.NAME, "Alice")
363
    .executeAsync();
364

365
// Parameter binding
366
Query query = create.query("INSERT INTO users (name, age) VALUES (?, ?)")
367
    .bind(1, "Bob")
368
    .bind(2, 25);
369
int rows = query.execute();
370
```