AGENTS.md

1# AGENTS.md — Druid Project Context
2 
3## Project Overview
4 
5Druid is Alibaba's open-source high-performance JDBC connection pool and SQL parser for Java. Version: 1.2.29-SNAPSHOT.
6 
7## Build & Test
8 
9```bash
10mvn clean install              # Full build with tests
11mvn test -pl core              # Core module tests only
12mvn test -pl core -Dtest=<TestClass>  # Single test class
13```
14 
15**Requirements:** Java 8+ JDK, Apache Maven 3.6+
16 
17## Project Structure
18 
19- `core/` — Main library: connection pool, SQL parser, filter chain, wall security, monitoring
20- `druid-spring-boot-starter/` — Spring Boot 2.x auto-configuration
21- `druid-spring-boot-3-starter/` — Spring Boot 3.x auto-configuration
22- `druid-spring-boot-4-starter/` — Spring Boot 4.x auto-configuration
23- `druid-admin/` — Cluster monitoring admin
24- `druid-wrapper/` — Wrapper utilities
25- `openspec/` — Architecture specs and change documentation
26 
27## Key Source Paths
28 
29- `core/src/main/java/com/alibaba/druid/pool/` — Connection pool (`DruidDataSource`)
30- `core/src/main/java/com/alibaba/druid/sql/dialect/` — 30 SQL dialect parsers
31- `core/src/main/java/com/alibaba/druid/sql/parser/` — Core parser infrastructure
32- `core/src/main/java/com/alibaba/druid/sql/ast/` — AST node classes
33- `core/src/main/java/com/alibaba/druid/filter/` — Filter chain implementations
34- `core/src/main/java/com/alibaba/druid/wall/` — SQL firewall (WallFilter)
35- `core/src/main/java/com/alibaba/druid/stat/` — Monitoring statistics
36 
37## Testing Conventions
38 
39- Tests are in `core/src/test/java/com/alibaba/druid/bvt/` (Black-box Verification Test)
40- SQL dialect tests use resource files: `core/src/test/resources/bvt/parser/<dialect>/*.txt`
41- Testing framework: JUnit 5 (migrated from JUnit 4)
42- Surefire pattern: `**/bvt/**/*.java`
43 
44## SQL Dialect Pattern
45 
46Each dialect in `sql/dialect/<name>/` follows this structure:
47- `<Name>Lexer` — Lexical analyzer
48- `<Name>ExprParser` — Expression parser
49- `<Name>StatementParser` — Statement parser
50- `<Name>OutputVisitor` — SQL output visitor
51- `<Name>ASTVisitor` — AST visitor interface
52- `<Name>SchemaStatVisitor` — Schema statistics visitor
53- Config: `META-INF/druid/parser/<name>/dialect.properties` and `builtin_datatypes`
54 
55## Code Style
56 
57- Java 8 compatible (source level 8)
58- Checkstyle enforced: `src/checkstyle/druid-checks.xml`
59- Visitor pattern for AST traversal
60- Filter-Chain (Chain of Responsibility) for JDBC interception
61