# apache/shardingsphere architecture

> Architecture diagram of the GitHub repository apache/shardingsphere, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apache/shardingsphere
- Repository: https://github.com/apache/shardingsphere

## Overview

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: [`proxy/backend/core/src/main/java/org/apache/shardingsphere/proxy/backend/handler/admin/DatabaseAdminQueryProxyBackendHandler.java`](https://github.com/apache/shardingsphere/blob/master/proxy/backend/core/src/main/java/org/apache/shardingsphere/proxy/backend/handler/admin/DatabaseAdminQueryProxyBackendHandler.java) (Database Proxy), [`infra/route/core/src/main/java/org/apache/shardingsphere/infra/route/engine/SQLRouteEngine.java`](https://github.com/apache/shardingsphere/blob/master/infra/route/core/src/main/java/org/apache/shardingsphere/infra/route/engine/SQLRouteEngine.java) (SQL Router), [`infra/executor/src/main/java/org/apache/shardingsphere/infra/executor/kernel/ExecutorEngine.java`](https://github.com/apache/shardingsphere/blob/master/infra/executor/src/main/java/org/apache/shardingsphere/infra/executor/kernel/ExecutorEngine.java) (Execution Engine), [`infra/parser/src/main/java/org/apache/shardingsphere/infra/parser/SQLParserEngine.java`](https://github.com/apache/shardingsphere/blob/master/infra/parser/src/main/java/org/apache/shardingsphere/infra/parser/SQLParserEngine.java) (SQL Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and Protocol"]
  node_jdbc["JDBC Driver"]
  node_proxy["Database Proxy"]
  node_protocol["Database Protocol"]
  node_database["Database Connector"]
end

subgraph group_kernel["SQL Processing"]
  node_parser["SQL Parser"]
  node_binder["SQL Binder"]
  node_router["SQL Router"]
  node_rewriter["SQL Rewriter"]
  node_executor["Execution Engine"]
  node_merger["Result Merger<br/>[MergeEngine.java]"]
end

subgraph group_governance["Governance and Operations"]
  node_metadata["Metadata Context"]
  node_metadata_persist["Metadata Persistence"]
  node_distsql["DistSQL"]
  node_pipeline["Data Pipeline"]
end

subgraph group_extensions["Pluggable Capabilities"]
  node_agent["Java Agent"]
  node_security["Security Features"]
  node_observability["Observability Plugins"]
end

subgraph group_ecosystem["Ecosystem Integrations"]
  node_mcp["MCP Workflows"]
end

node_application(("Application"))
node_storage[("Heterogeneous Databases")]

node_application -->|"connects through"| node_jdbc
node_application -->|"connects through"| node_proxy
node_proxy -.->|"adapts protocol"| node_protocol
node_jdbc -.->|"processes SQL"| node_parser
node_proxy -.->|"processes SQL"| node_parser
node_parser -.->|"binds statements"| node_binder
node_binder -.->|"routes statements"| node_router
node_router -.->|"rewrites SQL"| node_rewriter
node_rewriter -.->|"executes plans"| node_executor
node_executor -.->|"merges results"| node_merger
node_executor -.->|"accesses storage"| node_database
node_database -.->|"connects to"| node_storage
node_metadata -.->|"persists metadata"| node_metadata_persist
node_proxy -.->|"handles DistSQL"| node_distsql
node_metadata -.->|"supports migration"| node_pipeline
node_agent -.->|"hosts plugins"| node_observability
node_router -.->|"applies security"| node_security
node_mcp -.->|"queries through"| node_proxy

click node_jdbc "https://github.com/apache/shardingsphere/blob/master/jdbc/src/main/java/org/apache/shardingsphere/driver/jdbc/core/driver/ShardingSphereURLLoadEngine.java"
click node_proxy "https://github.com/apache/shardingsphere/blob/master/proxy/backend/core/src/main/java/org/apache/shardingsphere/proxy/backend/handler/admin/DatabaseAdminQueryProxyBackendHandler.java"
click node_protocol "https://github.com/apache/shardingsphere/blob/master/database/protocol/core/src/main/java/org/apache/shardingsphere/database/protocol/codec/DatabasePacketCodecEngine.java"
click node_parser "https://github.com/apache/shardingsphere/blob/master/infra/parser/src/main/java/org/apache/shardingsphere/infra/parser/SQLParserEngine.java"
click node_binder "https://github.com/apache/shardingsphere/blob/master/infra/binder/core/src/main/java/org/apache/shardingsphere/infra/binder/context/segment/select/projection/engine/ProjectionsContextEngine.java"
click node_router "https://github.com/apache/shardingsphere/blob/master/infra/route/core/src/main/java/org/apache/shardingsphere/infra/route/engine/SQLRouteEngine.java"
click node_rewriter "https://github.com/apache/shardingsphere/blob/master/infra/rewrite/core/src/main/java/org/apache/shardingsphere/infra/rewrite/engine/RouteSQLRewriteEngine.java"
click node_executor "https://github.com/apache/shardingsphere/blob/master/infra/executor/src/main/java/org/apache/shardingsphere/infra/executor/kernel/ExecutorEngine.java"
click node_merger "https://github.com/apache/shardingsphere/blob/master/infra/merge/src/main/java/org/apache/shardingsphere/infra/merge/MergeEngine.java"
click node_database "https://github.com/apache/shardingsphere/blob/master/database/connector/core/src/main/java/org/apache/shardingsphere/database/connector/core/DefaultDatabase.java"
click node_metadata "https://github.com/apache/shardingsphere/blob/master/mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/MetaDataContexts.java"
click node_metadata_persist "https://github.com/apache/shardingsphere/blob/master/mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/persist/MetaDataPersistFacade.java"
click node_distsql "https://github.com/apache/shardingsphere/blob/master/infra/distsql-handler/src/main/java/org/apache/shardingsphere/distsql/handler/engine/query/DistSQLQueryExecuteEngine.java"
click node_pipeline "https://github.com/apache/shardingsphere/blob/master/kernel/data-pipeline/core/src/main/java/org/apache/shardingsphere/data/pipeline/core/job/progress/persist/PipelineJobProgressPersistService.java"
click node_agent "https://github.com/apache/shardingsphere/blob/master/agent/core/src/main/java/org/apache/shardingsphere/agent/core/ShardingSphereAgent.java"
click node_security "https://github.com/apache/shardingsphere/blob/master/features/encrypt/core/src/main/java/org/apache/shardingsphere/encrypt/rewrite/condition/EncryptConditionEngine.java"
click node_observability "https://github.com/apache/shardingsphere/blob/master/agent/plugins/metrics/core/src/main/java/org/apache/shardingsphere/agent/plugin/metrics/core/collector/MetricsCollector.java"
click node_mcp "https://github.com/apache/shardingsphere/blob/master/mcp/core/src/main/java/org/apache/shardingsphere/mcp/core/workflow/WorkflowProxyQueryService.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_jdbc,node_proxy,node_protocol,node_database toneBlue
class node_parser,node_binder,node_router,node_rewriter,node_executor,node_merger,node_storage toneAmber
class node_metadata,node_metadata_persist,node_distsql,node_pipeline toneMint
class node_agent,node_security,node_observability toneRose
class node_mcp,node_application toneIndigo
```

## Components

### Access and Protocol

- [JDBC Driver](https://github.com/apache/shardingsphere/blob/master/jdbc/src/main/java/org/apache/shardingsphere/driver/jdbc/core/driver/ShardingSphereURLLoadEngine.java): `jdbc/src/main/java/org/apache/shardingsphere/driver/jdbc/core/driver/ShardingSphereURLLoadEngine.java`
- [Database Proxy](https://github.com/apache/shardingsphere/blob/master/proxy/backend/core/src/main/java/org/apache/shardingsphere/proxy/backend/handler/admin/DatabaseAdminQueryProxyBackendHandler.java): `proxy/backend/core/src/main/java/org/apache/shardingsphere/proxy/backend/handler/admin/DatabaseAdminQueryProxyBackendHandler.java`
- [Database Protocol](https://github.com/apache/shardingsphere/blob/master/database/protocol/core/src/main/java/org/apache/shardingsphere/database/protocol/codec/DatabasePacketCodecEngine.java): `database/protocol/core/src/main/java/org/apache/shardingsphere/database/protocol/codec/DatabasePacketCodecEngine.java`
- [Database Connector](https://github.com/apache/shardingsphere/blob/master/database/connector/core/src/main/java/org/apache/shardingsphere/database/connector/core/DefaultDatabase.java): `database/connector/core/src/main/java/org/apache/shardingsphere/database/connector/core/DefaultDatabase.java`

### SQL Processing

- [SQL Parser](https://github.com/apache/shardingsphere/blob/master/infra/parser/src/main/java/org/apache/shardingsphere/infra/parser/SQLParserEngine.java): `infra/parser/src/main/java/org/apache/shardingsphere/infra/parser/SQLParserEngine.java`
- [SQL Binder](https://github.com/apache/shardingsphere/blob/master/infra/binder/core/src/main/java/org/apache/shardingsphere/infra/binder/context/segment/select/projection/engine/ProjectionsContextEngine.java): `infra/binder/core/src/main/java/org/apache/shardingsphere/infra/binder/context/segment/select/projection/engine/ProjectionsContextEngine.java`
- [SQL Router](https://github.com/apache/shardingsphere/blob/master/infra/route/core/src/main/java/org/apache/shardingsphere/infra/route/engine/SQLRouteEngine.java): `infra/route/core/src/main/java/org/apache/shardingsphere/infra/route/engine/SQLRouteEngine.java`
- [SQL Rewriter](https://github.com/apache/shardingsphere/blob/master/infra/rewrite/core/src/main/java/org/apache/shardingsphere/infra/rewrite/engine/RouteSQLRewriteEngine.java): `infra/rewrite/core/src/main/java/org/apache/shardingsphere/infra/rewrite/engine/RouteSQLRewriteEngine.java`
- [Execution Engine](https://github.com/apache/shardingsphere/blob/master/infra/executor/src/main/java/org/apache/shardingsphere/infra/executor/kernel/ExecutorEngine.java): `infra/executor/src/main/java/org/apache/shardingsphere/infra/executor/kernel/ExecutorEngine.java`
- [Result Merger](https://github.com/apache/shardingsphere/blob/master/infra/merge/src/main/java/org/apache/shardingsphere/infra/merge/MergeEngine.java): `infra/merge/src/main/java/org/apache/shardingsphere/infra/merge/MergeEngine.java`

### Governance and Operations

- [Metadata Context](https://github.com/apache/shardingsphere/blob/master/mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/MetaDataContexts.java): `mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/MetaDataContexts.java`
- [Metadata Persistence](https://github.com/apache/shardingsphere/blob/master/mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/persist/MetaDataPersistFacade.java): `mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/persist/MetaDataPersistFacade.java`
- [DistSQL](https://github.com/apache/shardingsphere/blob/master/infra/distsql-handler/src/main/java/org/apache/shardingsphere/distsql/handler/engine/query/DistSQLQueryExecuteEngine.java): `infra/distsql-handler/src/main/java/org/apache/shardingsphere/distsql/handler/engine/query/DistSQLQueryExecuteEngine.java`
- [Data Pipeline](https://github.com/apache/shardingsphere/blob/master/kernel/data-pipeline/core/src/main/java/org/apache/shardingsphere/data/pipeline/core/job/progress/persist/PipelineJobProgressPersistService.java): `kernel/data-pipeline/core/src/main/java/org/apache/shardingsphere/data/pipeline/core/job/progress/persist/PipelineJobProgressPersistService.java`

### Pluggable Capabilities

- [Java Agent](https://github.com/apache/shardingsphere/blob/master/agent/core/src/main/java/org/apache/shardingsphere/agent/core/ShardingSphereAgent.java): `agent/core/src/main/java/org/apache/shardingsphere/agent/core/ShardingSphereAgent.java`
- [Security Features](https://github.com/apache/shardingsphere/blob/master/features/encrypt/core/src/main/java/org/apache/shardingsphere/encrypt/rewrite/condition/EncryptConditionEngine.java): `features/encrypt/core/src/main/java/org/apache/shardingsphere/encrypt/rewrite/condition/EncryptConditionEngine.java`
- [Observability Plugins](https://github.com/apache/shardingsphere/blob/master/agent/plugins/metrics/core/src/main/java/org/apache/shardingsphere/agent/plugin/metrics/core/collector/MetricsCollector.java): `agent/plugins/metrics/core/src/main/java/org/apache/shardingsphere/agent/plugin/metrics/core/collector/MetricsCollector.java`

### Ecosystem Integrations

- [MCP Workflows](https://github.com/apache/shardingsphere/blob/master/mcp/core/src/main/java/org/apache/shardingsphere/mcp/core/workflow/WorkflowProxyQueryService.java): `mcp/core/src/main/java/org/apache/shardingsphere/mcp/core/workflow/WorkflowProxyQueryService.java`

### Other components

- **Application**
- **Heterogeneous Databases**

## Connections

- Application → JDBC Driver: connects through (evidence: `README.md`)
- Application → Database Proxy: connects through (evidence: `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 (evidence: `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