0
# Druid Spring Boot Starter
1

2
The Druid Spring Boot Starter provides auto-configuration and integration support for the Alibaba Druid database connection pool and monitoring system. It simplifies the integration of Druid into Spring Boot applications by providing automatic configuration based on application properties, enabling developers to easily configure database connection pooling, SQL monitoring, web monitoring filters, and various security and performance features through standard Spring Boot configuration files.
3

4
## Package Information
5

6
- **Package Name**: druid-spring-boot-starter
7
- **Package Type**: maven
8
- **Group ID**: com.alibaba
9
- **Artifact ID**: druid-spring-boot-starter
10
- **Language**: Java
11
- **Installation**: Add Maven dependency:
12

13
```xml
14
<dependency>
15
    <groupId>com.alibaba</groupId>
16
    <artifactId>druid-spring-boot-starter</artifactId>
17
    <version>1.2.25</version>
18
</dependency>
19
```
20

21
For Gradle:
22

23
```gradle
24
implementation 'com.alibaba:druid-spring-boot-starter:1.2.25'
25
```
26

27
## Core Imports
28

29
```java
30
import com.alibaba.druid.spring.boot.autoconfigure.DruidDataSourceBuilder;
31
import com.alibaba.druid.spring.boot.autoconfigure.DruidDataSourceWrapper;
32
import com.alibaba.druid.spring.boot.autoconfigure.properties.DruidStatProperties;
33
```
34

35
## Basic Usage
36

37
**Single DataSource Configuration:**
38

39
1. Add the starter dependency to your Spring Boot project
40
2. Configure basic properties in `application.properties` or `application.yml`:
41

42
```properties
43
spring.datasource.url=jdbc:mysql://localhost:3306/test
44
spring.datasource.username=root
45
spring.datasource.password=password
46
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
47

48
# Druid-specific configuration
49
spring.datasource.druid.initial-size=5
50
spring.datasource.druid.max-active=20
51
spring.datasource.druid.min-idle=5
52
spring.datasource.druid.max-wait=60000
53
```
54

55
The starter will automatically create and configure a `DruidDataSourceWrapper` bean.
56

57
**Multiple DataSource Configuration:**
58

59
```java
60
@Configuration
61
public class DataSourceConfig {
62
    
63
    @Primary
64
    @Bean
65
    @ConfigurationProperties("spring.datasource.druid.primary")
66
    public DataSource primaryDataSource() {
67
        return DruidDataSourceBuilder.create().build();
68
    }
69
    
70
    @Bean
71
    @ConfigurationProperties("spring.datasource.druid.secondary") 
72
    public DataSource secondaryDataSource() {
73
        return DruidDataSourceBuilder.create().build();
74
    }
75
}
76
```
77

78
## Architecture
79

80
The Druid Spring Boot Starter is built around several key components:
81

82
- **Auto-Configuration**: `DruidDataSourceAutoConfigure` automatically configures Druid DataSource when conditions are met
83
- **DataSource Wrapper**: `DruidDataSourceWrapper` extends DruidDataSource with Spring Boot integration features
84
- **Builder Pattern**: `DruidDataSourceBuilder` provides a fluent API for creating DataSource instances
85
- **Configuration Properties**: `DruidStatProperties` provides type-safe configuration binding
86
- **Monitoring Integration**: Automatic setup of StatViewServlet, WebStatFilter, and AOP monitoring when enabled
87
- **Filter Management**: Automatic registration and configuration of various Druid filters
88

89
## Capabilities
90

91
### Auto-Configuration
92

93
Core Spring Boot auto-configuration that automatically sets up Druid DataSource with sensible defaults and property-based configuration.
94

95
```java { .api }
96
@Configuration
97
@ConditionalOnProperty(name = "spring.datasource.type", havingValue = "com.alibaba.druid.pool.DruidDataSource", matchIfMissing = true)
98
@ConditionalOnClass(DruidDataSource.class)
99
@AutoConfigureBefore(DataSourceAutoConfiguration.class)
100
@EnableConfigurationProperties({DruidStatProperties.class, DataSourceProperties.class})
101
public class DruidDataSourceAutoConfigure {
102
    
103
    @Bean
104
    @ConditionalOnMissingBean({DruidDataSourceWrapper.class, DruidDataSource.class, DataSource.class})
105
    public DruidDataSourceWrapper dataSource();
106
}
107
```
108

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

111
### DataSource Management
112

113
DataSource creation, configuration, and lifecycle management with Spring Boot integration.
114

115
```java { .api }
116
@ConfigurationProperties("spring.datasource.druid")
117
public class DruidDataSourceWrapper extends DruidDataSource implements InitializingBean {
118
    
119
    void afterPropertiesSet() throws Exception;
120
    void autoAddFilters(List<Filter> filters);
121
    void setMaxEvictableIdleTimeMillis(long maxEvictableIdleTimeMillis);
122
}
123

124
public class DruidDataSourceBuilder {
125
    
126
    static DruidDataSourceBuilder create();
127
    DruidDataSource build();
128
    
129
    @Deprecated
130
    DruidDataSource build(Environment env, String prefix);
131
}
132
```
133

134
[DataSource Management](./datasource-management.md)
135

136
### Configuration Properties
137

138
Type-safe configuration properties for all Druid settings including connection pool, monitoring, and filter configuration.
139

140
```java { .api }
141
@ConfigurationProperties("spring.datasource.druid")
142
public class DruidStatProperties {
143
    
144
    String[] getAopPatterns();
145
    void setAopPatterns(String[] aopPatterns);
146
    
147
    StatViewServlet getStatViewServlet();
148
    void setStatViewServlet(StatViewServlet statViewServlet);
149
    
150
    WebStatFilter getWebStatFilter();
151
    void setWebStatFilter(WebStatFilter webStatFilter);
152
    
153
    static class StatViewServlet {
154
        boolean isEnabled();
155
        void setEnabled(boolean enabled);
156
        // ... other properties
157
    }
158
    
159
    static class WebStatFilter {
160
        boolean isEnabled();
161
        void setEnabled(boolean enabled);
162
        // ... other properties  
163
    }
164
}
165
```
166

167
[Configuration Properties](./configuration-properties.md)
168

169
### Monitoring Integration
170

171
Web-based monitoring console and statistics collection with configurable security and filtering options.
172

173
```java { .api }
174
@ConditionalOnWebApplication
175
@ConditionalOnProperty(name = "spring.datasource.druid.stat-view-servlet.enabled", havingValue = "true")
176
public class DruidStatViewServletConfiguration {
177
    
178
    @Bean
179
    public ServletRegistrationBean statViewServletRegistrationBean(DruidStatProperties properties);
180
}
181

182
@ConditionalOnWebApplication  
183
@ConditionalOnProperty(name = "spring.datasource.druid.web-stat-filter.enabled", havingValue = "true")
184
public class DruidWebStatFilterConfiguration {
185
    
186
    @Bean
187
    public FilterRegistrationBean webStatFilterRegistrationBean(DruidStatProperties properties);
188
}
189

190
@ConditionalOnProperty("spring.datasource.druid.aop-patterns")
191
public class DruidSpringAopConfiguration {
192
    
193
    @Bean
194
    public Advice advice();
195
    
196
    @Bean  
197
    public Advisor advisor(DruidStatProperties properties);
198
    
199
    @Bean
200
    @ConditionalOnProperty(name = "spring.aop.auto", havingValue = "false")
201
    public DefaultAdvisorAutoProxyCreator advisorAutoProxyCreator();
202
}
203
```
204

205
[Monitoring Integration](./monitoring-integration.md)
206

207
### Filter Configuration
208

209
Automatic configuration and registration of various Druid filters for logging, security, statistics, and encoding.
210

211
```java { .api }
212
public class DruidFilterConfiguration {
213
    
214
    @Bean
215
    @ConfigurationProperties("spring.datasource.druid.filter.stat")
216
    @ConditionalOnProperty(prefix = "spring.datasource.druid.filter.stat", name = "enabled")
217
    public StatFilter statFilter();
218
    
219
    @Bean
220
    @ConfigurationProperties("spring.datasource.druid.filter.wall")
221
    @ConditionalOnProperty(prefix = "spring.datasource.druid.filter.wall", name = "enabled")
222
    public WallFilter wallFilter(WallConfig wallConfig);
223
    
224
    @Bean
225
    @ConfigurationProperties("spring.datasource.druid.filter.config")
226
    @ConditionalOnProperty(prefix = "spring.datasource.druid.filter.config", name = "enabled")
227
    public ConfigFilter configFilter();
228
    
229
    // Additional filter beans: EncodingConvertFilter, Slf4jLogFilter, Log4jFilter, Log4j2Filter, CommonsLogFilter
230
}
231
```
232

233
[Filter Configuration](./filter-configuration.md)
234

235
## Configuration Prefixes
236

237
All configuration properties use the following prefixes:
238

239
- `spring.datasource.druid.*` - Main DataSource configuration
240
- `spring.datasource.druid.filter.stat.*` - StatFilter configuration
241
- `spring.datasource.druid.filter.wall.*` - WallFilter configuration  
242
- `spring.datasource.druid.filter.{name}.*` - Other filter configurations
243
- `spring.datasource.druid.web-stat-filter.*` - WebStatFilter configuration
244
- `spring.datasource.druid.stat-view-servlet.*` - StatViewServlet configuration
245
- `spring.datasource.druid.aop-patterns` - AOP monitoring pattern configuration
246

247
## Supported Database Types
248

249
The following database types are supported for stat and wall filters:
250
db2, postgresql, sqlserver, oracle, AliOracle, mysql, mariadb, hive, h2, lealone, dm, kingbase, tydb, oceanbase, xugu, odps, teradata, log4jdbc, phoenix, edb, kylin, sqlite