How apache/shardingsphere works
ShardingSphere is a database enhancement layer for connecting applications to heterogeneous databases. Its principal workflow has two entry modes—JDBC and Proxy—then SQL parsing, routing/rewrite, execution, and result merging. Other major branches include governance and metadata persistence, DistSQL, data migration, MCP-based workflows, and pluggable security and observability features. The README describes these capabilities at product level; sampled sources are selective, so links without direct evidence are omitted or marked unverified.
Main entry points: DatabaseAdminQueryProxyBackendHandler.java Database Proxy · SQLRouteEngine.java SQL Router · ExecutorEngine.java Execution Engine · SQLParserEngine.java SQL Parser
Components 20
Access and Protocol
- JDBC Driver
jdbc/src/main/java/org/apache/shardingsphere/driver/jdbc/core/driver/ShardingSphereURLLoadEngine.java - Database Proxy
proxy/backend/core/src/main/java/org/apache/shardingsphere/proxy/backend/handler/admin/DatabaseAdminQueryProxyBackendHandler.java - Database Protocol
database/protocol/core/src/main/java/org/apache/shardingsphere/database/protocol/codec/DatabasePacketCodecEngine.java - Database Connector
database/connector/core/src/main/java/org/apache/shardingsphere/database/connector/core/DefaultDatabase.java
SQL Processing
- SQL Parser
infra/parser/src/main/java/org/apache/shardingsphere/infra/parser/SQLParserEngine.java - SQL Binder
infra/binder/core/src/main/java/org/apache/shardingsphere/infra/binder/context/segment/select/projection/engine/ProjectionsContextEngine.java - SQL Router
infra/route/core/src/main/java/org/apache/shardingsphere/infra/route/engine/SQLRouteEngine.java - SQL Rewriter
infra/rewrite/core/src/main/java/org/apache/shardingsphere/infra/rewrite/engine/RouteSQLRewriteEngine.java - Execution Engine
infra/executor/src/main/java/org/apache/shardingsphere/infra/executor/kernel/ExecutorEngine.java - Result Merger
infra/merge/src/main/java/org/apache/shardingsphere/infra/merge/MergeEngine.java
Governance and Operations
- Metadata Context
mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/MetaDataContexts.java - Metadata Persistence
mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/persist/MetaDataPersistFacade.java - DistSQL
infra/distsql-handler/src/main/java/org/apache/shardingsphere/distsql/handler/engine/query/DistSQLQueryExecuteEngine.java - Data Pipeline
kernel/data-pipeline/core/src/main/java/org/apache/shardingsphere/data/pipeline/core/job/progress/persist/PipelineJobProgressPersistService.java
Pluggable Capabilities
- Java Agent
agent/core/src/main/java/org/apache/shardingsphere/agent/core/ShardingSphereAgent.java - Security Features
features/encrypt/core/src/main/java/org/apache/shardingsphere/encrypt/rewrite/condition/EncryptConditionEngine.java - Observability Plugins
agent/plugins/metrics/core/src/main/java/org/apache/shardingsphere/agent/plugin/metrics/core/collector/MetricsCollector.java
Ecosystem Integrations
- MCP Workflows
mcp/core/src/main/java/org/apache/shardingsphere/mcp/core/workflow/WorkflowProxyQueryService.java
Other components
- Application
- Heterogeneous Databases
Connections 18
- Application → JDBC Driver: connects through
README.md - Application → Database Proxy: connects through
README.md - Database Proxy → Database Protocol: adapts protocol
- JDBC Driver → SQL Parser: processes SQL
- Database Proxy → SQL Parser: processes SQL
- SQL Parser → SQL Binder: binds statements
- SQL Binder → SQL Router: routes statements
- SQL Router → SQL Rewriter: rewrites SQL
- SQL Rewriter → Execution Engine: executes plans
- Execution Engine → Result Merger: merges results
- Execution Engine → Database Connector: accesses storage
- Database Connector → Heterogeneous Databases: connects to
- Metadata Context → Metadata Persistence: persists metadata
mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/MetaDataContexts.java - Database Proxy → DistSQL: handles DistSQL
- Metadata Context → Data Pipeline: supports migration
- Java Agent → Observability Plugins: hosts plugins
- SQL Router → Security Features: applies security
- MCP Workflows → Database Proxy: queries through