0
# Configuration
1

2
Comprehensive configuration system for customizing SQL rendering, execution behavior, debugging, and dialect-specific optimizations. Includes support for schema mapping, naming strategies, and performance tuning.
3

4
## Capabilities
5

6
### Settings Class
7

8
Main configuration class containing all jOOQ settings for customizing library behavior.
9

10
```java { .api }
11
public class Settings {
12
    /**
13
     * Get the SQL rendering formatting setting
14
     * @return RenderFormatting enum value
15
     */
16
    public RenderFormatting getRenderFormatting();
17
    
18
    /**
19
     * Set SQL rendering formatting
20
     * @param value Formatting setting
21
     * @return Settings with updated formatting
22
     */
23
    public Settings withRenderFormatting(RenderFormatting value);
24
    
25
    /**
26
     * Get the quoted names rendering setting
27
     * @return RenderQuotedNames enum value
28
     */
29
    public RenderQuotedNames getRenderQuotedNames();
30
    
31
    /**
32
     * Set quoted names rendering behavior
33
     * @param value Quoted names setting
34
     * @return Settings with updated quoted names behavior
35
     */
36
    public Settings withRenderQuotedNames(RenderQuotedNames value);
37
    
38
    /**
39
     * Get the statement type setting
40
     * @return StatementType enum value
41
     */
42
    public StatementType getStatementType();
43
    
44
    /**
45
     * Set statement type (prepared vs static)
46
     * @param value Statement type setting
47
     * @return Settings with updated statement type
48
     */
49
    public Settings withStatementType(StatementType value);
50
    
51
    /**
52
     * Get parameter type setting for SQL rendering
53
     * @return ParamType enum value
54
     */
55
    public ParamType getParamType();
56
    
57
    /**
58
     * Set parameter type for SQL rendering
59
     * @param value Parameter type setting
60
     * @return Settings with updated parameter type
61
     */
62
    public Settings withParamType(ParamType value);
63
    
64
    /**
65
     * Get execution logging setting
66
     * @return true if execution logging is enabled
67
     */
68
    public Boolean getExecuteLogging();
69
    
70
    /**
71
     * Set execution logging behavior
72
     * @param value true to enable execution logging
73
     * @return Settings with updated logging setting
74
     */
75
    public Settings withExecuteLogging(Boolean value);
76
    
77
    /**
78
     * Get query timeout setting in seconds
79
     * @return Query timeout in seconds, 0 for no timeout
80
     */
81
    public Integer getQueryTimeout();
82
    
83
    /**
84
     * Set query timeout in seconds
85
     * @param seconds Timeout in seconds, 0 for no timeout
86
     * @return Settings with updated timeout
87
     */
88
    public Settings withQueryTimeout(Integer seconds);
89
    
90
    /**
91
     * Get fetch size for result sets
92
     * @return Fetch size, 0 for driver default
93
     */
94
    public Integer getFetchSize();
95
    
96
    /**
97
     * Set fetch size for result sets
98
     * @param size Fetch size, 0 for driver default
99
     * @return Settings with updated fetch size
100
     */
101
    public Settings withFetchSize(Integer size);
102
    
103
    /**
104
     * Get batch size for batch operations
105
     * @return Batch size, 0 for no batching
106
     */
107
    public Integer getBatchSize();
108
    
109
    /**
110
     * Set batch size for batch operations
111
     * @param size Batch size, 0 for no batching
112
     * @return Settings with updated batch size
113
     */
114
    public Settings withBatchSize(Integer size);
115
    
116
    /**
117
     * Get schema mapping settings
118
     * @return List of schema mappings
119
     */
120
    public List<MappedSchema> getSchemaMapping();
121
    
122
    /**
123
     * Set schema mapping for cross-schema queries
124
     * @param mapping List of schema mappings
125
     * @return Settings with updated schema mapping
126
     */
127
    public Settings withSchemaMapping(List<MappedSchema> mapping);
128
}
129
```
130

131
### Configuration Interface
132

133
Core configuration interface that combines all jOOQ configuration elements.
134

135
```java { .api }
136
public interface Configuration {
137
    /**
138
     * Get the SQL dialect for this configuration
139
     * @return SQLDialect enum value
140
     */
141
    SQLDialect dialect();
142
    
143
    /**
144
     * Get the settings for this configuration
145
     * @return Settings instance
146
     */
147
    Settings settings();
148
    
149
    /**
150
     * Get the connection provider
151
     * @return ConnectionProvider for database connections
152
     */
153
    ConnectionProvider connectionProvider();
154
    
155
    /**
156
     * Get the transaction provider
157
     * @return TransactionProvider for transaction management
158
     */
159
    TransactionProvider transactionProvider();
160
    
161
    /**
162
     * Get the record mapper provider
163
     * @return RecordMapperProvider for custom record mapping
164
     */
165
    RecordMapperProvider recordMapperProvider();
166
    
167
    /**
168
     * Get the record listener providers
169
     * @return Array of RecordListenerProvider instances
170
     */
171
    RecordListenerProvider[] recordListenerProviders();
172
    
173
    /**
174
     * Get the execute listener providers
175
     * @return Array of ExecuteListenerProvider instances
176
     */
177
    ExecuteListenerProvider[] executeListenerProviders();
178
    
179
    /**
180
     * Get the visit listener providers
181
     * @return Array of VisitListenerProvider instances
182
     */
183
    VisitListenerProvider[] visitListenerProviders();
184
    
185
    /**
186
     * Create a derived configuration with different settings
187
     * @param newSettings New settings to use
188
     * @return Configuration with updated settings
189
     */
190
    Configuration derive(Settings newSettings);
191
    
192
    /**
193
     * Create a derived configuration with different connection provider
194
     * @param newConnectionProvider New connection provider
195
     * @return Configuration with updated connection provider
196
     */
197
    Configuration derive(ConnectionProvider newConnectionProvider);
198
    
199
    /**
200
     * Create a derived configuration with different dialect
201
     * @param newDialect New SQL dialect
202
     * @return Configuration with updated dialect
203
     */
204
    Configuration derive(SQLDialect newDialect);
205
}
206
```
207

208
**Usage Examples:**
209

210
```java
211
// Create custom settings
212
Settings settings = new Settings()
213
    .withRenderFormatting(RenderFormatting.TRUE)
214
    .withRenderQuotedNames(RenderQuotedNames.ALWAYS)
215
    .withExecuteLogging(true)
216
    .withQueryTimeout(30)
217
    .withFetchSize(1000);
218

219
// Create configuration with custom settings
220
Configuration config = new DefaultConfiguration()
221
    .set(SQLDialect.POSTGRES)
222
    .set(settings)
223
    .set(dataSource);
224

225
// Create DSLContext with configuration
226
DSLContext create = using(config);
227

228
// Derive configuration for different use cases
229
Configuration readOnlyConfig = config
230
    .derive(new Settings().withQueryTimeout(5))
231
    .derive(readOnlyDataSource);
232

233
DSLContext readOnly = using(readOnlyConfig);
234
```
235

236
### Configuration Enumerations
237

238
Key enumeration types for configuration options.
239

240
```java { .api }
241
public enum RenderFormatting {
242
    /**
243
     * Format SQL with indentation and line breaks
244
     */
245
    TRUE,
246
    
247
    /**
248
     * Render SQL in compact format
249
     */
250
    FALSE
251
}
252

253
public enum RenderQuotedNames {
254
    /**
255
     * Always quote identifiers
256
     */
257
    ALWAYS,
258
    
259
    /**
260
     * Quote identifiers when explicitly specified or required
261
     */
262
    EXPLICIT_DEFAULT_QUOTED,
263
    
264
    /**
265
     * Don't quote identifiers unless explicitly specified
266
     */
267
    EXPLICIT_DEFAULT_UNQUOTED,
268
    
269
    /**
270
     * Never quote identifiers
271
     */
272
    NEVER
273
}
274

275
public enum StatementType {
276
    /**
277
     * Use prepared statements (recommended)
278
     */
279
    PREPARED_STATEMENT,
280
    
281
    /**
282
     * Use static statements with inlined parameters
283
     */
284
    STATIC_STATEMENT
285
}
286

287
public enum ParamType {
288
    /**
289
     * Use indexed parameters (?)
290
     */
291
    INDEXED,
292
    
293
    /**
294
     * Use named parameters (:name)
295
     */
296
    NAMED,
297
    
298
    /**
299
     * Use named parameters or inline values as appropriate
300
     */
301
    NAMED_OR_INLINED,
302
    
303
    /**
304
     * Inline all parameter values directly in SQL
305
     */
306
    INLINED
307
}
308
```
309

310
### Schema Mapping
311

312
Configuration for mapping database schemas and tables.
313

314
```java { .api }
315
public class MappedSchema {
316
    /**
317
     * Get the input schema name (from database)
318
     * @return Input schema name
319
     */
320
    public String getInput();
321
    
322
    /**
323
     * Set the input schema name
324
     * @param input Schema name from database
325
     * @return MappedSchema with updated input
326
     */
327
    public MappedSchema withInput(String input);
328
    
329
    /**
330
     * Get the output schema name (for queries)
331
     * @return Output schema name
332
     */
333
    public String getOutput();
334
    
335
    /**
336
     * Set the output schema name
337
     * @param output Schema name to use in queries
338
     * @return MappedSchema with updated output
339
     */
340
    public MappedSchema withOutput(String output);
341
    
342
    /**
343
     * Get table mappings within this schema
344
     * @return List of table mappings
345
     */
346
    public List<MappedTable> getTables();
347
    
348
    /**
349
     * Set table mappings within this schema
350
     * @param tables List of table mappings
351
     * @return MappedSchema with updated table mappings
352
     */
353
    public MappedSchema withTables(List<MappedTable> tables);
354
}
355

356
public class MappedTable {
357
    /**
358
     * Get the input table name (from database)
359
     * @return Input table name
360
     */
361
    public String getInput();
362
    
363
    /**
364
     * Set the input table name
365
     * @param input Table name from database
366
     * @return MappedTable with updated input
367
     */
368
    public MappedTable withInput(String input);
369
    
370
    /**
371
     * Get the output table name (for queries)
372
     * @return Output table name
373
     */
374
    public String getOutput();
375
    
376
    /**
377
     * Set the output table name
378
     * @param output Table name to use in queries
379
     * @return MappedTable with updated output
380
     */
381
    public MappedTable withOutput(String output);
382
}
383
```
384

385
**Usage Examples:**
386

387
```java
388
// Schema mapping for multi-tenant applications
389
MappedSchema tenantMapping = new MappedSchema()
390
    .withInput("public")
391
    .withOutput("tenant_123");
392

393
Settings settings = new Settings()
394
    .withSchemaMapping(Arrays.asList(tenantMapping));
395

396
// Use configuration with schema mapping
397
DSLContext create = using(connection, SQLDialect.POSTGRES, settings);
398

399
// Query will automatically map "public" schema to "tenant_123"
400
Result<Record> result = create.selectFrom(USERS).fetch();
401
// Generated SQL: SELECT * FROM tenant_123.users
402
```
403

404
### Listeners and Providers
405

406
Interfaces for extending jOOQ functionality through listeners and custom providers.
407

408
```java { .api }
409
public interface ExecuteListener {
410
    /**
411
     * Called before query execution
412
     * @param ctx Execution context
413
     */
414
    void executeStart(ExecuteContext ctx);
415
    
416
    /**
417
     * Called after query execution
418
     * @param ctx Execution context
419
     */
420
    void executeEnd(ExecuteContext ctx);
421
    
422
    /**
423
     * Called when an exception occurs during execution
424
     * @param ctx Execution context with exception information
425
     */
426
    void exception(ExecuteContext ctx);
427
}
428

429
public interface RecordListener {
430
    /**
431
     * Called before a record is stored
432
     * @param ctx Record context
433
     */
434
    void storeStart(RecordContext ctx);
435
    
436
    /**
437
     * Called after a record is stored
438
     * @param ctx Record context
439
     */
440
    void storeEnd(RecordContext ctx);
441
    
442
    /**
443
     * Called before a record is inserted
444
     * @param ctx Record context
445
     */
446
    void insertStart(RecordContext ctx);
447
    
448
    /**
449
     * Called after a record is inserted
450
     * @param ctx Record context
451
     */
452
    void insertEnd(RecordContext ctx);
453
    
454
    /**
455
     * Called before a record is updated
456
     * @param ctx Record context
457
     */
458
    void updateStart(RecordContext ctx);
459
    
460
    /**
461
     * Called after a record is updated
462
     * @param ctx Record context
463
     */
464
    void updateEnd(RecordContext ctx);
465
    
466
    /**
467
     * Called before a record is deleted
468
     * @param ctx Record context
469
     */
470
    void deleteStart(RecordContext ctx);
471
    
472
    /**
473
     * Called after a record is deleted
474
     * @param ctx Record context
475
     */
476
    void deleteEnd(RecordContext ctx);
477
}
478

479
public interface TransactionProvider {
480
    /**
481
     * Begin a new transaction
482
     * @param ctx Transaction context
483
     */
484
    void begin(TransactionContext ctx);
485
    
486
    /**
487
     * Commit the current transaction
488
     * @param ctx Transaction context
489
     */
490
    void commit(TransactionContext ctx);
491
    
492
    /**
493
     * Rollback the current transaction
494
     * @param ctx Transaction context
495
     */
496
    void rollback(TransactionContext ctx) throws DataAccessException;
497
}
498
```
499

500
**Usage Examples:**
501

502
```java
503
// Custom execute listener for logging
504
ExecuteListener loggingListener = new ExecuteListener() {
505
    @Override
506
    public void executeStart(ExecuteContext ctx) {
507
        System.out.println("Executing: " + ctx.sql());
508
    }
509
    
510
    @Override
511
    public void executeEnd(ExecuteContext ctx) {
512
        System.out.println("Execution time: " + ctx.executionTime() + "ms");
513
    }
514
};
515

516
// Custom record listener for auditing
517
RecordListener auditListener = new RecordListener() {
518
    @Override
519
    public void insertEnd(RecordContext ctx) {
520
        System.out.println("Inserted record: " + ctx.record());
521
    }
522
    
523
    @Override
524
    public void updateEnd(RecordContext ctx) {
525
        System.out.println("Updated record: " + ctx.record());
526
    }
527
};
528

529
// Configure with listeners
530
Configuration config = new DefaultConfiguration()
531
    .set(SQLDialect.MYSQL)
532
    .set(dataSource)
533
    .set(ExecuteListenerProvider.providers(loggingListener))
534
    .set(RecordListenerProvider.providers(auditListener));
535

536
DSLContext create = using(config);
537
```