0
# Configuration
1

2
Configuration properties and customization options for jOOQ integration in Spring Boot applications.
3

4
## Capabilities
5

6
### JooqProperties
7

8
Configuration properties class that maps to `spring.jooq.*` properties in your application configuration.
9

10
```java { .api }
11
/**
12
 * Configuration properties for jOOQ database library under spring.jooq prefix
13
 */
14
@ConfigurationProperties("spring.jooq")
15
public class JooqProperties {
16
    
17
    /** SQL dialect to use. Auto-detected by default. */
18
    private SQLDialect sqlDialect;
19
    
20
    /** Location of the jOOQ config file. */
21
    private Resource config;
22
    
23
    /**
24
     * Get the configured SQL dialect
25
     * @return the SQL dialect, or null if auto-detection should be used
26
     */
27
    public SQLDialect getSqlDialect();
28
    
29
    /**
30
     * Set the SQL dialect to use
31
     * @param sqlDialect the SQL dialect
32
     */
33
    public void setSqlDialect(SQLDialect sqlDialect);
34
    
35
    /**
36
     * Get the jOOQ configuration file location
37
     * @return Resource pointing to the config file, or null if not specified
38
     */
39
    public Resource getConfig();
40
    
41
    /**
42
     * Set the jOOQ configuration file location
43
     * @param config Resource pointing to the XML configuration file
44
     */
45
    public void setConfig(Resource config);
46
    
47
    /**
48
     * Determine the SQL dialect to use based on configuration and DataSource
49
     * Uses explicit sqlDialect if set, otherwise auto-detects from DataSource
50
     * @param dataSource the primary data source
51
     * @return the SQL dialect to use for the DataSource
52
     */
53
    public SQLDialect determineSqlDialect(DataSource dataSource);
54
}
55
```
56

57
### DefaultConfigurationCustomizer
58

59
Functional interface for customizing jOOQ's DefaultConfiguration while retaining auto-configuration benefits.
60

61
```java { .api }
62
/**
63
 * Callback interface for beans that want to customize DefaultConfiguration
64
 * while keeping default auto-configuration
65
 */
66
@FunctionalInterface
67
public interface DefaultConfigurationCustomizer {
68
    
69
    /**
70
     * Customize the jOOQ Configuration
71
     * @param configuration the configuration to customize
72
     */
73
    void customize(DefaultConfiguration configuration);
74
}
75
```
76

77
### SqlDialectLookup
78

79
Utility class for automatically determining the appropriate SQL dialect from a DataSource.
80

81
```java { .api }
82
/**
83
 * Utility to lookup well known SQL dialects from a DataSource
84
 * Used internally for auto-detection when spring.jooq.sql-dialect is not specified
85
 */
86
final class SqlDialectLookup {
87
    
88
    /**
89
     * Return the most suitable SQL dialect for the given DataSource
90
     * @param dataSource the source DataSource
91
     * @return the most suitable SQL dialect, or SQLDialect.DEFAULT if detection fails
92
     */
93
    static SQLDialect getDialect(DataSource dataSource);
94
}
95
```
96

97
**Usage Examples:**
98

99
### Application Properties Configuration
100

101
```properties
102
# Specify SQL dialect explicitly (otherwise auto-detected)
103
spring.jooq.sql-dialect=MYSQL
104

105
# Specify external jOOQ configuration file
106
spring.jooq.config=classpath:jooq-config.xml
107
```
108

109
```yaml
110
# YAML format
111
spring:
112
  jooq:
113
    sql-dialect: POSTGRESQL
114
    config: classpath:config/jooq-settings.xml
115
```
116

117
### Custom Configuration via Customizer
118

119
```java
120
@Component
121
public class MyJooqCustomizer implements DefaultConfigurationCustomizer {
122
    
123
    @Override
124
    public void customize(DefaultConfiguration configuration) {
125
        // Add custom converters
126
        configuration.set(new LocalDateTimeConverter());
127
        
128
        // Add custom execute listeners
129
        configuration.set(new DefaultExecuteListenerProvider(
130
            new MyCustomExecuteListener()
131
        ));
132
        
133
        // Customize settings programmatically
134
        Settings settings = new Settings();
135
        settings.withExecuteLogging(true);
136
        settings.withRenderSchema(false);
137
        configuration.set(settings);
138
    }
139
}
140
```
141

142
### External jOOQ Configuration File
143

144
When `spring.jooq.config` is specified, you can provide an external XML configuration file:
145

146
```xml
147
<?xml version="1.0" encoding="UTF-8"?>
148
<configuration xmlns="http://www.jooq.org/xsd/jooq-runtime-3.18.0.xsd">
149
    <settings>
150
        <executeLogging>true</executeLogging>
151
        <renderSchema>false</renderSchema>
152
        <renderNamedParamPrefix>$</renderNamedParamPrefix>
153
        <fetchWarnings>true</fetchWarnings>
154
    </settings>
155
</configuration>
156
```
157

158
### SQL Dialect Auto-Detection
159

160
The SQL dialect is automatically detected based on your DataSource configuration:
161

162
```java
163
// Auto-detection examples based on JDBC URL patterns:
164
// jdbc:mysql://... -> SQLDialect.MYSQL  
165
// jdbc:postgresql://... -> SQLDialect.POSTGRES
166
// jdbc:h2:... -> SQLDialect.H2
167
// jdbc:oracle:... -> SQLDialect.ORACLE
168
// etc.
169

170
@Service
171
public class DatabaseService {
172
    
173
    @Autowired
174
    private DSLContext dsl;
175
    
176
    public void demonstrateDialectSpecificFeatures() {
177
        // The DSLContext automatically uses the correct dialect
178
        // MySQL-specific syntax when using MySQL
179
        // PostgreSQL-specific syntax when using PostgreSQL
180
        // etc.
181
    }
182
}
183
```
184

185
### Multiple Configuration Customizers
186

187
You can define multiple customizers with ordering:
188

189
```java
190
@Component
191
@Order(1)
192
public class ConverterCustomizer implements DefaultConfigurationCustomizer {
193
    @Override
194
    public void customize(DefaultConfiguration configuration) {
195
        // Add data type converters
196
        configuration.set(new LocalDateConverter());
197
    }
198
}
199

200
@Component  
201
@Order(2)
202
public class ListenerCustomizer implements DefaultConfigurationCustomizer {
203
    @Override
204
    public void customize(DefaultConfiguration configuration) {
205
        // Add execute listeners (after converters)
206
        configuration.set(new DefaultExecuteListenerProvider(
207
            new AuditingExecuteListener()
208
        ));
209
    }
210
}
211
```
212

213
## Configuration Properties Reference
214

215
### spring.jooq.sql-dialect
216

217
- **Type**: `org.jooq.SQLDialect` enum value
218
- **Default**: Auto-detected from DataSource
219
- **Valid Values**: `H2`, `MYSQL`, `MARIADB`, `POSTGRES`, `ORACLE`, `SQLSERVER`, `SQLITE`, `DERBY`, `HSQLDB`, etc.
220
- **Description**: Explicitly specify the SQL dialect instead of auto-detection
221

222
### spring.jooq.config
223

224
- **Type**: Spring Resource (file path, classpath, URL)
225
- **Default**: Not set
226
- **Description**: Location of external jOOQ XML configuration file
227
- **Examples**: 
228
  - `classpath:jooq-config.xml`
229
  - `file:/path/to/config.xml`
230
  - `config/jooq-settings.xml`
231

232
**Note**: When using `spring.jooq.config`, JAXB must be available on the classpath for XML parsing. If JAXB is not available, a `JaxbNotAvailableException` will be thrown with helpful error information.