0
# Spring Boot Starter jOOQ
1

2
Spring Boot Starter for jOOQ provides seamless integration between Spring Boot and jOOQ (Java Object Oriented Querying), a type-safe SQL query builder. This starter automatically configures jOOQ components, integrates with Spring's transaction management, and provides exception translation to Spring's DataAccessException hierarchy.
3

4
## Package Information
5

6
- **Package Name**: spring-boot-starter-jooq
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add dependency to your Maven or Gradle project
10

11
Maven:
12
```xml
13
<dependency>
14
    <groupId>org.springframework.boot</groupId>
15
    <artifactId>spring-boot-starter-jooq</artifactId>
16
    <version>3.5.3</version>
17
</dependency>
18
```
19

20
Gradle:
21
```groovy
22
implementation 'org.springframework.boot:spring-boot-starter-jooq:3.5.3'
23
```
24

25
## Core Imports
26

27
```java
28
import org.jooq.DSLContext;
29
import org.jooq.Configuration;
30
import org.springframework.boot.autoconfigure.jooq.*;
31
```
32

33
For configuration properties:
34
```java
35
import org.springframework.boot.context.properties.ConfigurationProperties;
36
```
37

38
## Basic Usage
39

40
```java
41
import org.jooq.DSLContext;
42
import org.springframework.beans.factory.annotation.Autowired;
43
import org.springframework.stereotype.Service;
44
import org.springframework.transaction.annotation.Transactional;
45

46
@Service
47
public class UserService {
48
    
49
    @Autowired
50
    private DSLContext dsl;
51
    
52
    @Transactional
53
    public List<User> findActiveUsers() {
54
        return dsl.selectFrom(USER)
55
                  .where(USER.ACTIVE.eq(true))
56
                  .fetchInto(User.class);
57
    }
58
    
59
    @Transactional
60
    public void createUser(String name, String email) {
61
        dsl.insertInto(USER)
62
           .set(USER.NAME, name)
63
           .set(USER.EMAIL, email)
64
           .set(USER.ACTIVE, true)
65
           .execute();
66
    }
67
}
68
```
69

70
## Architecture
71

72
Spring Boot Starter jOOQ is built around several key components:
73

74
- **Auto-Configuration**: `JooqAutoConfiguration` automatically configures jOOQ components based on available beans and properties
75
- **Transaction Integration**: Seamless integration with Spring's `PlatformTransactionManager` through `SpringTransactionProvider`
76
- **Exception Translation**: Converts jOOQ/JDBC exceptions to Spring's `DataAccessException` hierarchy
77
- **SQL Dialect Detection**: Automatically detects the appropriate SQL dialect from the configured `DataSource`
78
- **Configuration Customization**: Supports customization through `DefaultConfigurationCustomizer` beans and external configuration files
79

80
## Capabilities
81

82
### Auto-Configuration
83

84
Core auto-configuration that sets up jOOQ beans automatically based on your Spring Boot application configuration. Provides the main `DSLContext` and `Configuration` beans, and ensures proper database initialization ordering.
85

86
```java { .api }
87
@AutoConfiguration
88
@ConditionalOnClass(DSLContext.class)
89
@ConditionalOnBean(DataSource.class)
90
@EnableConfigurationProperties(JooqProperties.class)
91
public class JooqAutoConfiguration {
92
    
93
    @Bean
94
    @ConditionalOnMissingBean(DSLContext.class)
95
    public DefaultDSLContext dslContext(org.jooq.Configuration configuration);
96
    
97
    @Bean
98
    @ConditionalOnMissingBean(org.jooq.Configuration.class)
99
    DefaultConfiguration jooqConfiguration(JooqProperties properties, 
100
                                          ConnectionProvider connectionProvider,
101
                                          DataSource dataSource, 
102
                                          ObjectProvider<TransactionProvider> transactionProvider,
103
                                          ObjectProvider<ExecuteListenerProvider> executeListenerProviders,
104
                                          ObjectProvider<DefaultConfigurationCustomizer> configurationCustomizers,
105
                                          ObjectProvider<Settings> settingsProvider);
106
}
107
```
108

109
[Auto-Configuration](./auto-configuration.md)
110

111
### Configuration Properties
112

113
Configuration properties for customizing jOOQ behavior through Spring Boot's external configuration.
114

115
```java { .api }
116
@ConfigurationProperties("spring.jooq")
117
public class JooqProperties {
118
    private SQLDialect sqlDialect;
119
    private Resource config;
120
    
121
    public SQLDialect getSqlDialect();
122
    public void setSqlDialect(SQLDialect sqlDialect);
123
    public Resource getConfig();
124
    public void setConfig(Resource config);
125
    public SQLDialect determineSqlDialect(DataSource dataSource);
126
}
127
```
128

129
[Configuration](./configuration.md)
130

131
### Transaction Integration
132

133
Integration with Spring's transaction management system, allowing jOOQ operations to participate in Spring-managed transactions.
134

135
```java { .api }
136
public class SpringTransactionProvider implements TransactionProvider {
137
    public SpringTransactionProvider(PlatformTransactionManager transactionManager);
138
    public void begin(TransactionContext context);
139
    public void commit(TransactionContext ctx);
140
    public void rollback(TransactionContext ctx);
141
}
142
```
143

144
[Transaction Integration](./transaction-integration.md)
145

146
### Exception Translation
147

148
Automatic translation of jOOQ and JDBC exceptions to Spring's DataAccessException hierarchy for consistent error handling.
149

150
```java { .api }
151
public interface ExceptionTranslatorExecuteListener extends ExecuteListener {
152
    ExceptionTranslatorExecuteListener DEFAULT = new DefaultExceptionTranslatorExecuteListener();
153
    
154
    static ExceptionTranslatorExecuteListener of(
155
        Function<ExecuteContext, SQLExceptionTranslator> translatorFactory);
156
}
157
```
158

159
[Exception Handling](./exception-handling.md)
160

161
### Testing Integration  
162

163
Testing support for jOOQ-based components with slice testing capabilities that focus only on jOOQ components while providing embedded database support.
164

165
```java { .api }
166
@Target(ElementType.TYPE)
167
@Retention(RetentionPolicy.RUNTIME)
168
@BootstrapWith(JooqTestContextBootstrapper.class)
169
@ExtendWith(SpringExtension.class)
170
@Transactional
171
@AutoConfigureJooq
172
public @interface JooqTest {
173
    String[] properties() default {};
174
    boolean useDefaultFilters() default true;
175
    Filter[] includeFilters() default {};  
176
    Filter[] excludeFilters() default {};
177
    Class<?>[] excludeAutoConfiguration() default {};
178
}
179
```
180

181
[Testing Integration](./testing-integration.md)