0
# Filter Configuration
1

2
The Druid Spring Boot Starter provides automatic configuration and registration of various Druid filters for logging, security, statistics, encoding, and configuration management.
3

4
## Capabilities
5

6
### DruidFilterConfiguration
7

8
Central configuration class that conditionally creates and configures various Druid filter beans based on properties.
9

10
```java { .api }
11
/**
12
 * Auto-configuration for Druid filters
13
 * Each filter is conditionally created based on enabled property
14
 */
15
public class DruidFilterConfiguration {
16
    
17
    /**
18
     * Creates StatFilter for SQL execution statistics
19
     * Tracks SQL performance, slow queries, and execution patterns
20
     * @return Configured StatFilter instance
21
     */
22
    @Bean
23
    @ConfigurationProperties("spring.datasource.druid.filter.stat")
24
    @ConditionalOnProperty(prefix = "spring.datasource.druid.filter.stat", name = "enabled")
25
    @ConditionalOnMissingBean
26
    public StatFilter statFilter();
27
    
28
    /**
29
     * Creates ConfigFilter for encrypted password and external configuration support
30
     * Enables password encryption and configuration file inclusion
31
     * @return Configured ConfigFilter instance
32
     */
33
    @Bean
34
    @ConfigurationProperties("spring.datasource.druid.filter.config")
35
    @ConditionalOnProperty(prefix = "spring.datasource.druid.filter.config", name = "enabled")
36
    @ConditionalOnMissingBean
37
    public ConfigFilter configFilter();
38
    
39
    /**
40
     * Creates EncodingConvertFilter for character encoding conversion
41
     * Handles character set conversion for SQL parameters and results
42
     * @return Configured EncodingConvertFilter instance
43
     */
44
    @Bean
45
    @ConfigurationProperties("spring.datasource.druid.filter.encoding")
46
    @ConditionalOnProperty(prefix = "spring.datasource.druid.filter.encoding", name = "enabled")
47
    @ConditionalOnMissingBean
48
    public EncodingConvertFilter encodingConvertFilter();
49
    
50
    /**
51
     * Creates Slf4jLogFilter for SLF4J logging integration
52
     * Logs SQL statements and connection events using SLF4J
53
     * @return Configured Slf4jLogFilter instance
54
     */
55
    @Bean
56
    @ConfigurationProperties("spring.datasource.druid.filter.slf4j")
57
    @ConditionalOnProperty(prefix = "spring.datasource.druid.filter.slf4j", name = "enabled")
58
    @ConditionalOnMissingBean
59
    public Slf4jLogFilter slf4jLogFilter();
60
    
61
    /**
62
     * Creates Log4jFilter for Log4j 1.x logging integration
63
     * Logs SQL statements and connection events using Log4j
64
     * @return Configured Log4jFilter instance
65
     */
66
    @Bean
67
    @ConfigurationProperties("spring.datasource.druid.filter.log4j")
68
    @ConditionalOnProperty(prefix = "spring.datasource.druid.filter.log4j", name = "enabled")
69
    @ConditionalOnMissingBean
70
    public Log4jFilter log4jFilter();
71
    
72
    /**
73
     * Creates Log4j2Filter for Log4j 2.x logging integration
74
     * Logs SQL statements and connection events using Log4j 2
75
     * @return Configured Log4j2Filter instance
76
     */
77
    @Bean
78
    @ConfigurationProperties("spring.datasource.druid.filter.log4j2")
79
    @ConditionalOnProperty(prefix = "spring.datasource.druid.filter.log4j2", name = "enabled")
80
    @ConditionalOnMissingBean
81
    public Log4j2Filter log4j2Filter();
82
    
83
    /**
84
     * Creates CommonsLogFilter for Commons Logging integration
85
     * Logs SQL statements and connection events using Commons Logging
86
     * @return Configured CommonsLogFilter instance
87
     */
88
    @Bean
89
    @ConfigurationProperties("spring.datasource.druid.filter.commons-log")
90
    @ConditionalOnProperty(prefix = "spring.datasource.druid.filter.commons-log", name = "enabled")
91
    @ConditionalOnMissingBean
92
    public CommonsLogFilter commonsLogFilter();
93
    
94
    /**
95
     * Creates WallConfig for SQL firewall configuration
96
     * Configures security rules and policies for WallFilter
97
     * @return Configured WallConfig instance
98
     */
99
    @Bean
100
    @ConfigurationProperties("spring.datasource.druid.filter.wall.config")
101
    @ConditionalOnProperty(prefix = "spring.datasource.druid.filter.wall", name = "enabled")
102
    @ConditionalOnMissingBean
103
    public WallConfig wallConfig();
104
    
105
    /**
106
     * Creates WallFilter for SQL injection protection
107
     * Provides SQL firewall functionality with security rule enforcement
108
     * @param wallConfig Configuration object for security rules
109
     * @return Configured WallFilter instance with security policies
110
     */
111
    @Bean
112
    @ConfigurationProperties("spring.datasource.druid.filter.wall")
113
    @ConditionalOnProperty(prefix = "spring.datasource.druid.filter.wall", name = "enabled")
114
    @ConditionalOnMissingBean
115
    public WallFilter wallFilter(WallConfig wallConfig);
116
}
117
```
118

119
## Filter Types and Configuration
120

121
### StatFilter - SQL Statistics
122

123
Collects SQL execution statistics including performance metrics and slow query detection.
124

125
**Configuration Properties:**
126
```properties
127
# Enable StatFilter
128
spring.datasource.druid.filter.stat.enabled=true
129

130
# Database type for optimal statistics collection
131
spring.datasource.druid.filter.stat.db-type=mysql
132

133
# Slow SQL logging
134
spring.datasource.druid.filter.stat.log-slow-sql=true
135
spring.datasource.druid.filter.stat.slow-sql-millis=3000
136

137
# Merge SQL statements for better statistics
138
spring.datasource.druid.filter.stat.merge-sql=true
139

140
# Connection stack trace collection
141
spring.datasource.druid.filter.stat.connection-stack-trace-enable=true
142
```
143

144
**Supported Database Types:**
145
db2, postgresql, sqlserver, oracle, AliOracle, mysql, mariadb, hive, h2, lealone, dm, kingbase, tydb, oceanbase, xugu, odps, teradata, log4jdbc, phoenix, edb, kylin, sqlite
146

147
### WallFilter - SQL Security
148

149
Provides SQL injection protection and security rule enforcement.
150

151
**Configuration Properties:**
152
```properties
153
# Enable WallFilter
154
spring.datasource.druid.filter.wall.enabled=true
155

156
# Database type for security rules
157
spring.datasource.druid.filter.wall.db-type=mysql
158

159
# Security policy configuration
160
spring.datasource.druid.filter.wall.config.delete-allow=false
161
spring.datasource.druid.filter.wall.config.drop-table-allow=false
162
spring.datasource.druid.filter.wall.config.create-table-allow=true
163
spring.datasource.druid.filter.wall.config.alter-table-allow=false
164
spring.datasource.druid.filter.wall.config.truncate-allow=false
165

166
# Function call restrictions
167
spring.datasource.druid.filter.wall.config.select-into-outfile-allow=false
168
spring.datasource.druid.filter.wall.config.select-union-check=true
169

170
# Comment and hint restrictions
171
spring.datasource.druid.filter.wall.config.comment-allow=false
172
spring.datasource.druid.filter.wall.config.multi-statement-allow=false
173
```
174

175
### ConfigFilter - Configuration Management
176

177
Supports encrypted passwords and external configuration file inclusion.
178

179
**Configuration Properties:**
180
```properties
181
# Enable ConfigFilter
182
spring.datasource.druid.filter.config.enabled=true
183

184
# Encrypted password configuration
185
spring.datasource.druid.connection-properties=config.decrypt=true;config.decrypt.key=${DRUID_DECRYPT_KEY}
186

187
# External configuration file
188
spring.datasource.druid.filter.config.file=classpath:druid-config.properties
189
```
190

191
**Password Encryption Example:**
192
```java
193
// Generate encrypted password
194
String encryptedPassword = ConfigTools.encrypt("your-password");
195

196
// Use in configuration
197
spring.datasource.druid.password=${ENCRYPTED_PASSWORD}
198
spring.datasource.druid.connection-properties=config.decrypt=true;config.decrypt.key=${DECRYPT_KEY}
199
```
200

201
### Logging Filters
202

203
Multiple logging integration options for SQL statement and connection event logging.
204

205
**SLF4J Logging Filter:**
206
```properties
207
# Enable SLF4J logging
208
spring.datasource.druid.filter.slf4j.enabled=true
209
spring.datasource.druid.filter.slf4j.statement-executable-sql-log-enable=true
210
spring.datasource.druid.filter.slf4j.statement-log-enabled=true
211
spring.datasource.druid.filter.slf4j.statement-log-error-enabled=true
212
spring.datasource.druid.filter.slf4j.connection-log-enabled=true
213
```
214

215
**Log4j 2 Logging Filter:**
216
```properties
217
# Enable Log4j2 logging
218
spring.datasource.druid.filter.log4j2.enabled=true
219
spring.datasource.druid.filter.log4j2.statement-executable-sql-log-enable=true
220
spring.datasource.druid.filter.log4j2.statement-log-enabled=true
221
```
222

223
**Commons Logging Filter:**
224
```properties
225
# Enable Commons Logging
226
spring.datasource.druid.filter.commons-log.enabled=true
227
spring.datasource.druid.filter.commons-log.statement-executable-sql-log-enable=true
228
```
229

230
### EncodingConvertFilter - Character Encoding
231

232
Handles character encoding conversion for SQL parameters and results.
233

234
**Configuration Properties:**
235
```properties
236
# Enable encoding conversion
237
spring.datasource.druid.filter.encoding.enabled=true
238
spring.datasource.druid.filter.encoding.client-encoding=UTF-8
239
spring.datasource.druid.filter.encoding.server-encoding=ISO8859-1
240
```
241

242
## Filter Activation Methods
243

244
### Method 1: Simple Filter String
245

246
Enable filters using a comma-separated string:
247

248
```properties
249
spring.datasource.druid.filters=stat,wall,slf4j
250
```
251

252
This method uses default configuration for each filter.
253

254
### Method 2: Individual Filter Configuration
255

256
Enable and configure filters individually:
257

258
```properties
259
# StatFilter with custom configuration
260
spring.datasource.druid.filter.stat.enabled=true
261
spring.datasource.druid.filter.stat.slow-sql-millis=2000
262
spring.datasource.druid.filter.stat.log-slow-sql=true
263

264
# WallFilter with security policies
265
spring.datasource.druid.filter.wall.enabled=true
266
spring.datasource.druid.filter.wall.config.delete-allow=false
267
spring.datasource.druid.filter.wall.config.drop-table-allow=false
268

269
# SLF4J logging with specific settings
270
spring.datasource.druid.filter.slf4j.enabled=true
271
spring.datasource.druid.filter.slf4j.statement-log-enabled=true
272
```
273

274
### Method 3: Programmatic Configuration
275

276
Create custom filter beans:
277

278
```java
279
@Configuration
280
public class CustomFilterConfig {
281
    
282
    @Bean
283
    public StatFilter customStatFilter() {
284
        StatFilter filter = new StatFilter();
285
        filter.setSlowSqlMillis(1000);
286
        filter.setLogSlowSql(true);
287
        filter.setMergeSql(true);
288
        return filter;
289
    }
290
    
291
    @Bean
292
    public WallFilter customWallFilter() {
293
        WallFilter filter = new WallFilter();
294
        WallConfig config = new WallConfig();
295
        config.setDeleteAllow(false);
296
        config.setDropTableAllow(false);
297
        filter.setConfig(config);
298
        return filter;
299
    }
300
}
301
```
302

303
## Filter Chain and Ordering
304

305
### Automatic Registration
306

307
Filters are automatically registered with DataSource in the order they are discovered:
308

309
1. **StatFilter** - Should typically be first for accurate statistics
310
2. **WallFilter** - Security filtering before other operations
311
3. **Logging Filters** - Log filtered and processed SQL
312
4. **EncodingConvertFilter** - Character conversion last
313
5. **ConfigFilter** - Configuration support throughout chain
314

315
### Custom Ordering
316

317
Control filter order through explicit bean naming:
318

319
```java
320
@Configuration
321
public class FilterOrderConfig {
322
    
323
    @Bean("filter1")
324
    @Order(1)
325
    public StatFilter statFilter() {
326
        return new StatFilter();
327
    }
328
    
329
    @Bean("filter2") 
330
    @Order(2)
331
    public WallFilter wallFilter() {
332
        return new WallFilter();
333
    }
334
}
335
```
336

337
## Configuration Examples
338

339
### Development Environment
340

341
```yaml
342
spring:
343
  datasource:
344
    druid:
345
      # Enable multiple filters with detailed logging
346
      filter:
347
        stat:
348
          enabled: true
349
          slow-sql-millis: 1000
350
          log-slow-sql: true
351
          merge-sql: true
352
        slf4j:
353
          enabled: true
354
          statement-log-enabled: true
355
          statement-executable-sql-log-enable: true
356
        wall:
357
          enabled: true
358
          config:
359
            delete-allow: true
360
            drop-table-allow: true
361
            truncate-allow: true
362
```
363

364
### Production Environment
365

366
```yaml
367
spring:
368
  datasource:
369
    druid:
370
      # Security-focused filter configuration
371
      filter:
372
        stat:
373
          enabled: true
374
          slow-sql-millis: 3000
375
          log-slow-sql: true
376
          merge-sql: true
377
        wall:
378
          enabled: true
379
          config:
380
            delete-allow: false
381
            drop-table-allow: false
382
            truncate-allow: false
383
            create-table-allow: false
384
            alter-table-allow: false
385
            comment-allow: false
386
            multi-statement-allow: false
387
        config:
388
          enabled: true
389
      # Encrypted password support
390
      connection-properties: config.decrypt=true;config.decrypt.key=${DRUID_DECRYPT_KEY}
391
```
392

393
### Multi-DataSource Filter Configuration
394

395
```properties
396
# Primary DataSource filters
397
spring.datasource.druid.primary.filter.stat.enabled=true
398
spring.datasource.druid.primary.filter.wall.enabled=true
399
spring.datasource.druid.primary.filter.slf4j.enabled=true
400

401
# Secondary DataSource filters (different configuration)
402
spring.datasource.druid.secondary.filter.stat.enabled=true
403
spring.datasource.druid.secondary.filter.stat.slow-sql-millis=5000
404
spring.datasource.druid.secondary.filter.commons-log.enabled=true
405
```