0
# DataSource Management
1

2
The Druid Spring Boot Starter provides DataSource creation, configuration, and lifecycle management through wrapper classes and builder patterns.
3

4
## Capabilities
5

6
### DruidDataSourceWrapper
7

8
A Spring Boot-integrated wrapper around DruidDataSource that provides automatic property binding and initialization.
9

10
```java { .api }
11
/**
12
 * Spring Boot wrapper for DruidDataSource with automatic configuration
13
 * Extends DruidDataSource and implements InitializingBean for lifecycle management
14
 */
15
@ConfigurationProperties("spring.datasource.druid")
16
public class DruidDataSourceWrapper extends DruidDataSource implements InitializingBean {
17
    
18
    /**
19
     * Initializes the DataSource after all properties are set
20
     * Falls back to basic Spring Boot DataSource properties when Druid-specific properties are not set
21
     * Calls DruidDataSource.init() to complete initialization
22
     * @throws Exception if initialization fails
23
     */
24
    void afterPropertiesSet() throws Exception;
25
    
26
    /**
27
     * Automatically registers available Druid filters with the DataSource
28
     * @param filters List of Filter beans to be added to the DataSource
29
     */
30
    @Autowired(required = false)
31
    void autoAddFilters(List<Filter> filters);
32
    
33
    /**
34
     * Sets maximum evictable idle time with validation bypass
35
     * Bypasses IllegalArgumentException for configuration order issues
36
     * @param maxEvictableIdleTimeMillis Maximum idle time in milliseconds
37
     */
38
    void setMaxEvictableIdleTimeMillis(long maxEvictableIdleTimeMillis);
39
}
40
```
41

42
**Key Features:**
43

44
- **Property Binding**: Automatically binds properties with prefix `spring.datasource.druid`
45
- **Fallback Configuration**: Uses standard Spring Boot DataSource properties when Druid-specific ones aren't set
46
- **Filter Auto-Registration**: Automatically adds any Druid Filter beans found in the Spring context
47
- **Validation Workaround**: Handles property validation edge cases for better Spring Boot integration
48

49
**Usage Example:**
50

51
The wrapper is typically created automatically by the auto-configuration, but you can also create it manually:
52

53
```java
54
@Bean
55
@ConfigurationProperties("spring.datasource.druid.primary")
56
public DruidDataSourceWrapper primaryDataSource() {
57
    return new DruidDataSourceWrapper();
58
}
59
```
60

61
### DruidDataSourceBuilder
62

63
Builder pattern utility for creating DruidDataSource instances, particularly useful for multiple DataSource configurations.
64

65
```java { .api }
66
/**
67
 * Builder utility for creating DruidDataSource instances
68
 * Provides fluent API for DataSource creation
69
 */
70
public class DruidDataSourceBuilder {
71
    
72
    /**
73
     * Creates a new DruidDataSourceBuilder instance
74
     * @return New builder instance
75
     */
76
    static DruidDataSourceBuilder create();
77
    
78
    /**
79
     * Builds a new DruidDataSourceWrapper instance
80
     * @return Configured DruidDataSourceWrapper ready for use
81
     */
82
    DruidDataSource build();
83
    
84
    /**
85
     * @deprecated Legacy method for Spring Boot 1.x compatibility
86
     * Builds DruidDataSource with environment-specific configuration
87
     * Fixed property ordering issues in older Spring Boot versions
88
     * @param env Spring Environment for property resolution
89
     * @param prefix Configuration property prefix
90
     * @return Configured DruidDataSource
91
     */
92
    @Deprecated
93
    DruidDataSource build(Environment env, String prefix);
94
}
95
```
96

97
**Usage Examples:**
98

99
**Single DataSource:**
100
```java
101
@Bean
102
public DataSource dataSource() {
103
    return DruidDataSourceBuilder.create().build();
104
}
105
```
106

107
**Multiple DataSources:**
108
```java
109
@Configuration
110
public class MultiDataSourceConfig {
111
    
112
    @Primary
113
    @Bean
114
    @ConfigurationProperties("spring.datasource.druid.primary")
115
    public DataSource primaryDataSource() {
116
        return DruidDataSourceBuilder.create().build();
117
    }
118
    
119
    @Bean  
120
    @ConfigurationProperties("spring.datasource.druid.secondary")
121
    public DataSource secondaryDataSource() {
122
        return DruidDataSourceBuilder.create().build();
123
    }
124
}
125
```
126

127
### Property Resolution Logic
128

129
The DruidDataSourceWrapper follows a specific property resolution hierarchy:
130

131
1. **Druid-specific properties** (e.g., `spring.datasource.druid.username`)
132
2. **Standard Spring Boot properties** (e.g., `spring.datasource.username`) as fallback
133

134
```java { .api }
135
/**
136
 * Property resolution order in afterPropertiesSet():
137
 * 1. Check if Druid-specific property is set
138
 * 2. If not, fall back to standard Spring Boot DataSource property
139
 * 3. Apply the resolved value to the DruidDataSource
140
 */
141
void afterPropertiesSet() throws Exception {
142
    if (super.getUsername() == null) {
143
        super.setUsername(basicProperties.determineUsername());
144
    }
145
    if (super.getPassword() == null) {
146
        super.setPassword(basicProperties.determinePassword());
147
    }
148
    // ... similar for URL and driver class name
149
    init(); // Complete DruidDataSource initialization
150
}
151
```
152

153
### Filter Integration
154

155
The wrapper automatically integrates with Druid's filter system:
156

157
```java { .api }
158
/**
159
 * Automatic filter registration
160
 * Any Filter beans in the Spring context are automatically added to the DataSource
161
 * Supports conditional filter registration based on configuration
162
 */
163
@Autowired(required = false)
164
public void autoAddFilters(List<Filter> filters) {
165
    super.filters.addAll(filters);
166
}
167
```
168

169
**Supported Filter Types:**
170
- StatFilter (SQL execution statistics)
171
- WallFilter (SQL injection protection)  
172
- ConfigFilter (Encrypted password support)
173
- EncodingConvertFilter (Character encoding conversion)
174
- Slf4jLogFilter, Log4jFilter, Log4j2Filter, CommonsLogFilter (Logging integration)
175

176
### Multiple DataSource Configuration
177

178
For applications requiring multiple DataSources, configure separate property prefixes:
179

180
**Properties Configuration:**
181
```properties
182
# Primary DataSource
183
spring.datasource.druid.primary.url=jdbc:mysql://localhost:3306/primary
184
spring.datasource.druid.primary.username=primary_user
185
spring.datasource.druid.primary.password=primary_pass
186
spring.datasource.druid.primary.initial-size=5
187
spring.datasource.druid.primary.max-active=20
188

189
# Secondary DataSource  
190
spring.datasource.druid.secondary.url=jdbc:mysql://localhost:3306/secondary
191
spring.datasource.druid.secondary.username=secondary_user
192
spring.datasource.druid.secondary.password=secondary_pass
193
spring.datasource.druid.secondary.initial-size=3
194
spring.datasource.druid.secondary.max-active=10
195
```
196

197
**Java Configuration:**
198
```java
199
@Configuration
200
public class DataSourceConfig {
201
    
202
    @Primary
203
    @Bean(name = "primaryDataSource")
204
    @ConfigurationProperties("spring.datasource.druid.primary")
205
    public DataSource primaryDataSource() {
206
        return DruidDataSourceBuilder.create().build();
207
    }
208
    
209
    @Bean(name = "secondaryDataSource")
210
    @ConfigurationProperties("spring.datasource.druid.secondary")
211
    public DataSource secondaryDataSource() {
212
        return DruidDataSourceBuilder.create().build();
213
    }
214
}
215
```
216

217
### Lifecycle Management
218

219
The DruidDataSourceWrapper properly integrates with Spring's bean lifecycle:
220

221
1. **Construction**: Bean is created with default values
222
2. **Property Injection**: Spring injects configured properties  
223
3. **afterPropertiesSet()**: Fallback properties are applied and DruidDataSource is initialized
224
4. **Bean Ready**: DataSource is ready for dependency injection and use
225
5. **Destruction**: Spring handles cleanup when application context closes