alibaba/druid: a JDBC connection pool with a SQL parser attached

What alibaba/druid solves that a plain JDBC pool does not

A JDBC pool hands out connections. It does not tell you which statement held a connection for four seconds, which table the statement touched, or whether the SQL string was assembled from user input. Druid is built around those three questions. The README describes it as a high-performance database connection pool and SQL parser that integrates JDBC pooling, SQL parsing and analysis, security, and monitoring statistics into one piece. The pool class is DruidDataSource; the SQL parser produces an AST; the WallFilter inspects that AST before execution; the StatFilter collects execution statistics.

The intended audience is Java teams running relational databases behind an application server or a Spring Boot service, including teams on domestic Chinese databases. The README lists a dialect matrix that covers MySQL, PostgreSQL, Oracle, SQL Server, DB2, H2, Informix, DM (Dameng), Oscar, GaussDB, ClickHouse, Doris, StarRocks, Teradata, Redshift, BigQuery, Snowflake, Synapse, Hologres, ODPS (MaxCompute), Hive, Spark, Presto, Impala, Athena, Blink, Databricks, Phoenix, SuperSQL and Transact-SQL. That list is the part of the project most people underestimate: the parser is usable on its own, without the pool, for SQL formatting or table and column extraction.

One caveat about the name. Searching for druid returns tabletop role-playing games, Celtic history and Apache Druid, the analytics database. This article is about the Java library published as com.alibaba:druid. If you arrived looking for wild shape, you are in the wrong repository.

How the pool, the parser and the Filter chain fit together

The architecture is layered rather than monolithic. DruidDataSource sits at the bottom and manages physical connections, with options the README names as physical connection preheating, PSCache and KeepAlive. On top of that sits a Filter chain: a pluggable pipeline where each Filter wraps the connection, statement or result set. StatFilter and WallFilter are two built-in members of that chain, and the repository also documents a filter-guide for writing your own.

The data flow for a monitored statement is: your code asks DruidDataSource for a connection, the Filter chain wraps it, your statement executes, StatFilter records timing and SQL text, and the statistics surface either through the API or through a web monitoring page. WallFilter runs in the same chain but earlier in the decision: it parses the SQL into an AST and applies rules, so injection patterns and dangerous operations can be rejected before they reach the database. The README describes WallFilter as AST-based SQL security protection.

HighAvailableDataSource is a separate component for multi-datasource load balancing, health checks and failover. It is worth reading the ha-datasource document before assuming it replaces your existing routing layer, because the README gives no detail on its consistency model in the summary text.

The SQL parser is independent of all of this. SQLUtils.parseStatements returns a list of SQLStatement objects for a given DbType, SQLUtils.format returns a formatted string, and SchemaStatVisitor collects the tables and columns a statement touches. Each dialect has its own Lexer, Parser, AST and Visitor implementation, which is why the dialect list is long and why a dialect that is not listed is not a configuration change but a code change.

Installing alibaba/druid and running a first query

The Maven coordinates are com.alibaba:druid. The README shows 1.2.24 in its example block, while the releases page lists 1.2.28 as the most recent release, so pick the version your dependency management already resolves rather than copying the README number blindly.

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>druid</artifactId>
    <version>1.2.24</version>
</dependency>

If you are on Spring Boot, the README recommends a starter instead, and the choice depends on your Spring Boot line: druid-spring-boot-starter for 2.x, druid-spring-boot-3-starter for 3.x, druid-spring-boot-4-starter for 4.x. For a Spring Boot 3.x service the dependency looks like this.

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>druid-spring-boot-3-starter</artifactId>
    <version>1.2.24</version>
</dependency>

Configuration goes under spring.datasource.druid in application.yml. The README example sets initial-size, max-active, min-idle and max-wait, then enables the stat and wall filters. After the application starts, StatFilter is active and the pool is sized accordingly; slow SQL logging is driven by log-slow-sql and slow-sql-millis, so statements over 2000 ms are logged.

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb
    username: root
    password: password
    druid:
      initial-size: 5
      max-active: 20
      min-idle: 5
      max-wait: 60000
      filter:
        stat:
          enabled: true
          log-slow-sql: true
          slow-sql-millis: 2000
        wall:
          enabled: true

Without a framework you construct the pool directly. The README's example sets url, username, password, initialSize, maxActive and minIdle, calls init(), and then borrows connections in a try-with-resources block. The init() call is the step people forget: the pool is not usable until it runs.

DruidDataSource dataSource = new DruidDataSource();
dataSource.setUrl("jdbc:mysql://localhost:3306/mydb");
dataSource.setUsername("root");
dataSource.setPassword("password");
dataSource.setInitialSize(5);
dataSource.setMaxActive(20);
dataSource.setMinIdle(5);
dataSource.init();

try (Connection conn = dataSource.getConnection()) {
    // execute SQL
}

To try the parser alone, no database is needed. SQLUtils.parseStatements takes the SQL string and a DbType, and SchemaStatVisitor reports the tables and columns. This is the quickest way to judge whether Druid is worth adopting for your dialect.

String sql = "SELECT id, name FROM users WHERE age > 18 ORDER BY name";
List<SQLStatement> stmts = SQLUtils.parseStatements(sql, DbType.mysql);

String formatted = SQLUtils.format(sql, DbType.mysql);

SchemaStatVisitor visitor = SQLUtils.createSchemaStatVisitor(DbType.mysql);
stmts.get(0).accept(visitor);
System.out.println("Tables: " + visitor.getTables());
System.out.println("Columns: " + visitor.getColumns());

Building from source needs a Java 8+ JDK and Apache Maven 3.6+, per the README.

git clone https://github.com/alibaba/druid.git
cd druid
mvn clean install

Where DruidDataSource and WallFilter become the wrong choice

The most common mistake is enabling WallFilter on a legacy application. WallFilter makes decisions from a parsed AST, so any statement the parser cannot represent is a statement the filter cannot judge. Applications that build SQL dynamically, use vendor-specific syntax outside the supported dialect, or send statements the parser does not model will surface this as blocked or misparsed SQL rather than as a clean error. Turning the filter on in a staging environment with real production query shapes is the only way to find out, and the README does not document a rollback procedure for the filter.

Second, the parser is a Java library. If your service is Go, Python or Node, the pool and the parser are both unavailable, and the Filter chain concept does not transfer. The dialect list is broad but it is a Java implementation, not a wire protocol.

Third, the SQL dialect matrix is not a promise of semantic equivalence. Supporting MySQL and Doris means having a Lexer and Parser for each; it does not mean a statement that parses under one will behave identically under the other, and the README gives no compatibility guarantees across dialects. If you are parsing third-party SQL you did not write, test against the exact dialect rather than the closest one.

Fourth, the documentation is spread across README, a doc/ directory and the GitHub wiki. The README points to architecture, connection-pool, SQL-parser, dialect-support, filter, wall-security, monitoring and HA-datasource documents, plus Chinese and English wiki pages. That is a lot of surface, and the wiki is the place where the FAQ lives. Expect to read more than one page before you understand a configuration key.

Druid against HikariCP and against a SQL proxy

HikariCP is the obvious comparison inside the JVM. It is a connection pool and little else: it does not ship a SQL parser, an AST-based firewall or a monitoring page. The difference in approach is that HikariCP optimizes the pool as a pool, while Druid treats the pool as one component of a database middleware layer and attaches parsing and statistics to it. If you want a small dependency with a narrow job, HikariCP is the smaller surface. If you want slow-SQL attribution, table and column extraction from live traffic, and injection checks at the driver level, Druid is the one that ships those in the same artifact.

The other alternative is a database proxy such as a sidecar or gateway that inspects SQL outside the application. That moves the parsing and the firewall off the JVM and onto the network path, which helps when you have polyglot services that cannot all link a Java library. The trade-off is an extra hop, a separate deployment and a separate failure domain, and the application loses the direct StatFilter view of its own pool. Druid's approach keeps all of it in-process, which is cheaper to operate for a single Java service and useless for a heterogeneous fleet.

For SQL parsing specifically, the realistic alternative is a dedicated parser library for your target dialect. Druid's advantage there is breadth: 30 dialects behind one SQLUtils call and one SQLStatement AST, which matters if you already depend on Druid for the pool and do not want a second parser dependency.

Maintenance, upgrade cost and the Apache-2.0 licence

The repository is not archived and the last push was on 2026-08-01, so it is being touched. Release cadence is uneven: 1.2.22 in March 2024, 1.2.23 in May 2024, then 1.2.28 in March 2026. Anyone who pins a version and expects regular point releases should plan around that spacing rather than assume it.

The upgrade cost has two parts. The pool side is mostly configuration compatible, but the Spring Boot starter artifact changes with the Spring Boot major line, so a Spring Boot 2 to 3 migration means swapping druid-spring-boot-starter for druid-spring-boot-3-starter, and a move to 4.x means druid-spring-boot-4-starter. That is a dependency coordinate change, not a code change, but it does mean your build file has to track two upgrade axes at once. The parser side is the riskier one: dialect implementations are code, so upgrading can change how an edge-case statement parses, and any WallFilter rule that depends on the AST inherits that change.

The project is licensed under Apache License 2.0, and the repository carries a NOTICE file alongside license.txt, which is the normal Apache-2.0 arrangement. That permits commercial use and modification with the usual attribution and notice obligations. It is not a legal opinion; if you redistribute a modified copy, read the NOTICE and SECURITY.md yourself. Security reports are handled through a private channel rather than public issues, per the README.

Editorial conclusion

Adopt alibaba/druid if you run a Java service on MySQL, PostgreSQL, Oracle or a domestic Chinese database and you want connection-pool statistics plus AST-level SQL inspection without adding a separate proxy. Do not adopt it if you only need a minimal pool, or if you are not on the JVM: the SQL parser is a Java library, and the pool is a JDBC DataSource, so Python, Go and Node services have nothing to plug in. Before you commit, verify three things in your own environment: the exact starter artifact for your Spring Boot line (druid-spring-boot-starter, druid-spring-boot-3-starter or druid-spring-boot-4-starter), whether your SQL passes the WallFilter in non-blocking mode first, and which of the 30 listed dialects actually covers your database rather than the nearest relative.

Frequently asked questions

Official sources

1. alibaba/druid on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases