# Repository: apache/shardingsphere
# Stars: 20710

## CLAUDE.md

# CLAUDE.md - ShardingSphere AI Programming Guide

*Professional Guide for AI Programming Assistants - Best Practices for ShardingSphere Code Development*

## 🏗️ ShardingSphere Architecture Overview

### Project Overview
ShardingSphere is an ecosystem of distributed database solutions with JDBC driver, database proxy, and planned Sidecar modes.

### Core Module Architecture
```yaml
module_hierarchy:
  infrastructure_layer:
    - shardingsphere-infra: Common utilities, SPI definitions
    - shardingsphere-parser: SQL parsing (ANTLR4-based)
  engine_layer:
    - shardingsphere-mode: Configuration management
    - shardingsphere-kernel: Core execution engine
  access_layer:
    - shardingsphere-jdbc: Java JDBC driver
    - shardingsphere-proxy: Database proxy
  feature_layer:
    - shardingsphere-sharding: Data sharding
    - shardingsphere-encryption: Data encryption
    - shardingsphere-readwrite-splitting: Read/write splitting
```

### Technology Stack Decisions
- **ANTLR4**: SQL parsing and abstract syntax tree generation
- **Netty**: High-performance network communication (proxy mode)
- **Apache Calcite**: Query optimization and execution plans
- **SPI**: Plugin architecture for hot-pluggable extensions

### JDBC vs Proxy Patterns
- **JDBC**: Zero invasion, Java-only, highest performance
- **Proxy**: Language-agnostic, centralized management, advanced features

### Key Concepts
- **Sharding**: Horizontal data partitioning
- **DistSQL**: Distributed SQL for dynamic configuration
- **SPI Extension**: Algorithm, protocol, and execution extensions
- **Data Pipeline**: Migration and synchronization functionality

### Code Quality Standards
```yaml
self_documenting_code:
  method_naming: "10-15 characters, verb-noun patterns, no comments needed"
  examples: ["isValidEmailAddress()", "calculateOrderTotal()"]
  anti_examples: ["proc()", "getData()", "handle()"]

complex_logic:
  definition: "3+ nested levels or 20+ lines per method"
  handling: "Extract to meaningful private methods"

mock_boundaries:
  no_mock: "Simple objects, DTOs, stateless utilities"
  must_mock: "Database connections, network services, third-party interfaces"
  judgment: "Mock only with external dependencies or high construction cost"
```

## 🚀 AI Programming Best Practices

### How to Obtain High-Quality Code

#### 1. Source Code Development Request Template
```
Please implement [feature description] for [class name], requirements:
1. Follow ShardingSphere project coding standards and constraints
2. Use self-documenting programming, no comments
3. Extract complex logic into private methods
4. 100% test coverage unit tests
5. Pass spotless code formatting checks
6. Use @RequiredArgsConstructor constructor injection
```

#### 2. Unit Test Request Templates

**Basic Style-Consistent Testing**:
```
Please write unit tests for [class name], requirements:
1. Use ShardingSphere project testing style
2. Test method naming with assert*() prefix
3. Use Hamcrest assertion style assertThat(actual, is(expected))
4. Use Mockito for Mocking, follow project boundary principles
5. Maintain clear Given-When-Then structure
```

**Complex Tests for First-Pass Success**:
```
Please write complete unit tests for [complex class name], requirements:
1. First analyze the dependency relationships and complexity of the class under test
2. Identify all external dependencies that need Mocking
3. Gradually build test fixtures, ensure complete Mock chains
4. Write corresponding test methods for each branch
5. Use @BeforeEach to set up common Mocks
6. Use try-with-resources to manage MockedConstruction
7. Ensure all tests can run independently and pass

If you encounter uncertain dependency relationships, please ask me for confirmation.
```

**100% Coverage Testing**:
```
Please implement 100% test coverage for [specific class name] in shardingsphere-[module] module:
1. First generate coverage report to check current status:
   ./mvnw clean test jacoco:report -Djacoco.skip=false -pl [submodule]
   open [submodule]/target/site/jacoco/index.html
2. Identify all branches that need testing (red diamond markers)
3. Write multiple sets of test data for complex conditions
4. Ensure all exception paths have tests
5. Verify final coverage reaches 100%:
   ./mvnw test jacoco:check@jacoco-check -Pcoverage-check -Djacoco.check.class.pattern=[ClassName] -pl [submodule]

If dead code or uncovered branches are found, please explain in detail.
```

**Special Case Handling Testing**:
```
Please write unit tests for [class name], requirements:
1. Make every effort to achieve 100% coverage
2. If you encounter the following situations, please report to me:
   - Truly unreachable dead code (e.g., never-thrown exceptions)
   - Functions dependent on specific runtime environments (e.g., OS-specific functions)
   - Features requiring special hardware or network conditions
   - Protective programming code for extreme cases

Report format:
- Code location: [class name:line number]
- Uncoverage reason: [detailed explanation]
- Suggested solution: [if any]

Let me confirm before skipping coverage requirements for these codes.
```

**SQL Generation Class Testing**:
```
Please write comprehensive tests for [SQLGeneratorClass] in [module], requirements:
1. Use efficient test development workflow:
   - Analyze existing test Mock patterns first (DatabaseTypedSPILoader + TypedSPILoader)
   - Write most complex scenario test first to verify feasibility
   - Run test to get actual SQL output, then correct expected values
   - Batch copy verified patterns to other simple scenarios

2. SQL syntax verification:
   - For Oracle: verify MERGE INTO, ROWNUM, NVL syntax formats
   - For MySQL: verify LIMIT, IFNULL, REPLACE syntax formats
   - Use database-specific official docs for syntax validation

3. Mock dependency reuse:
   - 100% reuse existing test Mock configuration patterns
   - Avoid redesigning Mock chains for SPI loaders
   - Use DatabaseTypedSPILoader.getService(DialectPipelineSQLBuilder.class, databaseType) pattern

4. Branch coverage strategy:
   - Merge simple methods into single tests where possible
   - Focus independent tests on truly complex conditional branches
   - Ensure each boolean/enum branch has at least one dedicated test

5. Quality assurance:
   - Run complete test suite in one batch after all tests written
   - Use Jacoco to verify 100% branch coverage
   - Minimize iterative modifications during development
```

#### 3. Key Points for Best Results
- **Provide complete context**: Tell me the specific class path, module information, and related dependencies
- **Clarify complexity**: If the class is particularly complex, specify which part to test first
- **Progressive development**: For complex features, request step-by-step implementation
- **Quality verification**: Ask me to run actual test commands to verify pass rates

#### 4. Critical Success Factors for Testing Tasks
- **Pattern Analysis First**: Always analyze existing test patterns before writing new tests
- **Validation-Driven Development**: Write tests to discover actual behavior before defining expectations
- **Mock Reuse Principle**: Never redesign Mock configurations when existing patterns work
- **Branch Efficiency**: Focus on conditional branches, not method count, for test coverage
- **Batch Validation**: Run complete test suites at once, avoid frequent incremental checks

## 🤖 AI Usage Guidelines

### Core Principles
- **AI-First Principle**: All content is oriented towards AI programming assistants, not human developers
- **Actionability Priority**: Every instruction must be directly executable by AI, avoid theoretical descriptions
- **Unambiguous Expression**: Use clear instructions and parameterized templates, avoid vague expressions
- **Search Efficiency Priority**: Information organization facilitates AI quick positioning, reduces understanding cost

### Content Standards
- **Accuracy Priority**: All information must be correct and verifiable, no exaggeration or beautification
- **Practicality Priority**: Focus on actual effects, avoid exaggerated expressions
- **Problem-Oriented**: Directly address problem essence, provide actionable solutions
- **Concise and Clear**: Use most direct language to express core information

### Response Style Standards
- **In-depth Analysis**: Conduct deep analysis based on code logic and project specifications, avoid surface-level answers
- **Factual and Realistic**: Present facts and data, do not exaggerate achievements, do not hide problems
- **Reasoned Debate**: When facing programmer's misconceptions, engage in well-reasoned debates based on technical standards and best practices
- **Timely Correction**: When facing AI inference errors, immediately admit mistakes and correct them to maintain technical accuracy

### Quick Search Mapping
- "Create rule change processor" → Code Templates.Rule Change Processor Template
- "Write test methods" → Code Templates.Test Method Template
- "Mock external dependencies" → Code Templates.Mock Configuration Template
- "Coverage check" → Quick Commands Reference.Validation Commands
- "Format code" → Quick Commands Reference.Validation Commands
- "Test style requirements" → AI Programming Best Practices.Unit Test Request Templates

### AI Decision Rules
```yaml
task_type_detection:
  if contains(["src/main/java"], ["*.java"]): "source_code_task"
  if contains(["src/test/java"], ["*Test.java"]): "test_task"
  if contains(["*.md"], ["docs/"]): "documentation_task"

validation_rules:
  source_code_task: ["100% test coverage", "code formatting", "self-documenting"]
  test_task: ["branch coverage", "mock configuration", "assertion correctness"]
  doc_task: ["link validity", "format consistency"]

decision_logic:
  if task_type == "source_code": apply source code task workflow
  if task_type == "test": apply test task workflow
  if involves_external_dependencies: use MockedConstruction template
```

## ⚡ Quick Commands Reference

### Build Commands
```bash
./mvnw install -T1C                           # Full build with parallel execution
./mvnw install -T1C -DskipTests              # Build without tests
./mvnw clean compile                          # Compile only
```

### Code Quality Commands
```bash
./mvnw spotless:apply -Pcheck                 # Format code
./mvnw checkstyle:check                      # Code style checking
./mvnw pmd:check                             # Static code analysis
./mvnw spotbugs:check                        # Bug detection
./mvnw dependency-check                      # Security vulnerability scan
./mvnw archunit:test                         # Architecture rule validation
```

### Testing Commands
```bash
./mvnw test                                  # Run all tests
./mvnw test -Dtest=${TestClassName}          # Run specific test class
./mvnw test -pl ${submodule}                 # Run tests for specific module
./mvnw test jacoco:report -Djacoco.skip=false -pl ${submodule}  # Generate coverage report
./mvnw test jacoco:check@jacoco-check -Pcoverage-check -Djacoco.skip=false \
  -Djacoco.check.class.pattern=${ClassName} -pl ${submodule}  # Coverage check

# Performance Testing
./mvnw jmh:benchmark                         # Run performance benchmarks
```

# Parameters: ${ClassName}, ${TestClassName}, ${submodule}

## 📝 Code Templates

### Rule Change Processor Template
```java
package org.apache.shardingsphere.${module}.rule.changed;

import org.apache.shardingsphere.infra.algorithm.core.processor.AlgorithmChangedProcessor;
import org.apache.shardingsphere.mode.spi.rule.RuleChangedItemType;
import org.apache.shardingsphere.${module}.api.config.${RuleType}RuleConfiguration;
import org.apache.shardingsphere.${module}.rule.${RuleType}Rule;

import java.util.Map;

/**
 * ${AlgorithmType} algorithm changed processor.
 */
public final class ${AlgorithmType}AlgorithmChangedProcessor extends AlgorithmChangedProcessor<${RuleType}RuleConfiguration> {

    public ${AlgorithmType}AlgorithmChangedProcessor() {
        super(${RuleType}Rule.class);
    }

    @Override
    protected ${RuleType}RuleConfiguration createEmptyRuleConfiguration() {
        return new ${RuleType}RuleConfiguration();
    }

    @Override
    protected Map<String, AlgorithmConfiguration> getAlgorithmConfigurations(final ${RuleType}RuleConfiguration currentRuleConfig) {
        return currentRuleConfig.get${AlgorithmType}Algorithms();
    }

    @Override
    public RuleChangedItemType getType() {
        return new RuleChangedItemType("${ruleType}", "${algorithmType}_algorithms");
    }
}
```

### Test Method Template
```java
@Test
void assert${MethodName}With${Condition}Expects${Result}() {
    // Given
    ${MockSetup}

    // When
    ${ActualCall}

    // Then
    assertThat(${actual}, is(${expected}));
}
```

### Mock Configuration Template

**Mock Usage Boundaries:**
- **No Mock**: Simple objects, DTOs, stateless utilities, configuration objects
- **Must Mock**: Database connections, network services, third-party interfaces, SPI services
- **Judgment**: Mock only with external dependencies or high construction cost

**Basic Mock Patterns:**
```java
// Interface method Mock
when(dependency.method(any())).thenReturn(result);

// Constructor Mock with MockedConstruction
try (MockedConstruction<ClassName> mocked = mockConstruction(ClassName.class)) {
    // Test code involving new ClassName()
}
```

**Advanced Mock Patterns:**
```java
// Static method Mocking (avoid UnfinishedStubbingException)
@SneakyThrows(SQLException.class)
private static Array createMockArray(final Object data) {
    Array result = mock(Array.class);
    doReturn(data).when(result).getArray();
    return result;
}

// Deep stubs for complex dependencies
@Mock(answer = Answers.RETURNS_DEEP_STUBS)
private ComplexService complexService;

// MockedStatic for static method calls
try (MockedStatic<UtilityClass> mocked = mockStatic(UtilityClass.class)) {
    when(UtilityClass.staticMethod(any())).thenReturn(value);
    // Test code
}
```

**Example Comparison:**
```java
// ❌ Over-mocking simple objects
String result = mock(String.class);  // Unnecessary

// ✅ Direct creation for simple objects
String result = "testValue";

// ✅ Mock external dependencies
when(dataSource.getConnection()).thenReturn(mockConnection);
```

### SPI Implementation Template
```java
package org.apache.shardingsphere.${module}.spi;

@TypedSPI
public final class ${SPIName}Impl implements ${SPIName}SPI {
    @Override
    public ${ResultType} execute(${ContextType} context) {
        // Implementation logic
        return ${result};
    }

    @Override
    public String getType() {
        return "${type}";
    }
}
```

## 🧪 ShardingSphere Testing Style Guide

### Project Testing Style Summary

#### 1. Naming Conventions
- **Test Classes**: `*Test.java` suffix
- **Test Methods**: `assert*()` prefix with descriptive naming
  - Examples: `assertConnectWithInvalidURL()`, `assertDriverWorks()`, `assertLoadEmptyConfiguration()`
- **Integration Tests**: `*IT.java` suffix

#### 2. Mock Usage Patterns
- **Framework**: Mockito + Mockito Extension
- **Annotations**: `@Mock`, `@InjectMocks`, `@ExtendWith(MockitoExtension.class)`
- **Deep Stubs**: `@Mock(answer = Answers.RETURNS_DEEP_STUBS)`
- **Constructor Mocks**: `MockedConstruction` for complex objects
- **Boundary Principle**: Direct creation for simple objects, Mock only complex dependencies

#### 3. Assertion Styles
- **Primary**: Hamcrest matchers
- **Pattern**: `assertThat(actual, is(expected))`
- **Custom**: `ShardingSphereAssertionMatchers.deepEqual()` for deep equality comparisons

#### 4. Test Structure
- **Single Responsibility**: Each test method focuses on one scenario
- **Given-When-Then**: Clear three-part structure
- **Independence**: Complete isolation between tests
- **Resource Management**: `try-with-resources` for Mock resource management

#### 5. Coverage Requirements
- **Target**: 100% branch coverage
- **Focus**: Algorithm execution paths, boundary conditions, exception handling
- **Method**: Independent testing of each conditional branch

### Module-Specific Testing Patterns

#### JDBC Module Testing
- **Driver Testing**: JDBC driver registration and functionality
- **Connection Testing**: Connection pooling and state management
- **Adapter Testing**: JDBC adapter implementations

#### Proxy Module Testing
- **Configuration Testing**: Proxy configuration loading
- **Protocol Testing**: Database protocol implementations
- **Handler Testing**: Request/response handlers

#### Kernel Module Testing
- **Algorithm Testing**: Core algorithms (sharding, encryption, etc.)
- **Rule Testing**: Business rule implementations
- **Pipeline Testing**: Data pipeline operations

### Advanced Testing Patterns

#### Concurrency Testing
- **Multi-threaded Tests**: Thread safety validation
- **Async Testing**: Asynchronous operation testing with Awaitility
- **Race Condition Testing**: Concurrent access scenarios

#### Integration Testing Patterns
- **YAML Integration**: Configuration serialization/deserialization
- **SPI Integration**: Service provider interface testing
- **Database Integration**: Mocked database interactions for metadata testing

## 🎯 Task Execution Workflow

### Source Code Task Steps
1. **Analyze Task** → Identify as source code task
2. **Coverage Analysis** → Use JaCoCo to find uncovered branches
3. **Design Implementation** → Apply templates from Code Templates
4. **Verify Coverage** → Run tests to ensure 100% coverage
5. **Format Code** → Apply spotless formatting
6. **Complete Validation** → Ensure all quality checks pass

### Test Task Steps

#### Standard Testing Workflow
1. **Analyze Test Scenarios** → Identify branches that need testing
2. **Mock Configuration** → Use Mock Configuration Template
3. **Write Tests** → Apply Test Method Template
4. **Verify Coverage** → Ensure complete branch coverage
5. **Assertion Validation** → Use correct assertion patterns

#### SQL Generation Class Workflow (High-Efficiency)
**Phase 1: Comprehensive Analysis (One-time)**
```
Task agent analysis should include:
- Complete class structure and method listing
- Complexity and branch count for each method
- All existing test patterns and configurations
- Dependency relationships and Mock requirements
- Identification of any non-coverable code
```

**Phase 2: Validation-First Development**
1. **Select most complex scenario** and write one test first
2. **Verify Mock configuration and syntax expectations** by running the test
3. **Batch copy verified patterns** to other simple scenarios
4. **Write dedicated tests only for truly complex conditional branches**

**Phase 3: Quality Assurance**
- Run complete test suite and coverage checks in one batch
- Avoid frequent iterative modifications
- Use Jacoco to verify 100% branch coverage
```

### Documentation Task Steps
1. **Content Review** → Check accuracy and formatting
2. **Link Validation** → Ensure all links are valid
3. **Format Check** → Unify markdown format
4. **Complete Validation** → Ensure documentation quality standards

## 📋 Project Constraint Rules

### Core Design Principles
```yaml
class_design:
  - final classes with final fields
  - constructor injection only
  - @RequiredArgsConstructor for dependencies
  - self-documenting code (no comments)

package_structure:
  service: "org.apache.shardingsphere.{module}.service"
  spi: "org.apache.shardingsphere.{module}.spi"
  config: "org.apache.shardingsphere.{module}.config"
  util: "org.apache.shardingsphere.{module}.util"
```

### Code Patterns
```java
// Self-documenting pattern
if (isValidUserWithPermission()) {
    processPayment();
}

private boolean isValidUserWithPermission() {
    return user.isValid() && user.hasPermission();
}

// Test structure
@Test
void assertMethodWithConditionExpectsResult() {
    // Given
    mockDependencies();

    // When
    Result actual = target.method(input);

    // Then
    assertThat(actual, is(expected));
}
```

### Quality Requirements
- **Test Coverage**: 100% branch coverage
- **Code Formatting**: Spotless applied
- **Mock Strategy**: Mock only external dependencies
- **Naming**: Test methods use assert*() prefix

## 🔍 Quick Search Index

### AI Search Mapping Table
```yaml
quick_search_index:
  "Create rule change processor":
    target: "Code Templates.Rule Change Processor Template"
    description: "Create rule change processor class"

  "Write test methods":
    target: "Code Templates.Test Method Template"
    description: "Write unit test methods"

  "Mock external dependencies":
    target: "Code Templates.Mock Configuration Template"
    description: "Configure external dependency Mock"

  "Coverage check":
    target: "Quick Commands Reference.Validation Commands"
    description: "Run test coverage check"

  "Format code":
    target: "Quick Commands Reference.Validation Commands"
    description: "Apply code formatting"

  "Test style requirements":
    target: "AI Programming Best Practices.Unit Test Request Templates"
    description: "View testing style requirements"

  "Naming rules":
    target: "Project Constraint Rules.class_design.naming_conventions"
    description: "View naming conventions"

  "Package structure":
    target: "Project Constraint Rules.package_naming"
    description: "View package naming rules"

  "Quality issues":
    target: "Troubleshooting Guide"
    description: "Solve common quality issues"

  "ShardingSphere test style":
    target: "ShardingSphere Testing Style Guide"
    description: "Complete project testing style guide"

error_recovery_index:
  "Coverage not met":
    solution: "Check Mock configuration, add branch tests"
    reference: "Code Templates.Mock Configuration Template"

  "Compilation errors":
    solution: "Check dependencies and syntax"
    reference: "Quick Commands Reference.Build Commands"

  "Format errors":
    solution: "Run spotless formatting"
    reference: "Quick Commands Reference.Validation Commands"

  "Test failures":
    solution: "Check Mock configuration and assertion logic"
    reference: "Code Templates.Test Method Template"

  "Complex mock setup":
    solution: "Use Mock boundary judgment and complex dependency handling"
    reference: "ShardingSphere Testing Style Guide.Mock Usage Patterns"
```

## 🛠️ Common Issues & Solutions

### SQL Generation Class Issues

#### Expected SQL Syntax Errors
- **Issue**: Expected SQL assertion doesn't match actual generated SQL
- **Solution**: Run test first to get actual output, then correct expected values
- **Prevention**: Use database official documentation to verify syntax formats
- **Oracle Common Issues**: MERGE INTO ON clause format, ROWNUM positioning, NVL parameter order

#### Mock Configuration Complexity
- **Issue**: Over-engineering Mock configurations for SPI loaders
- **Solution**: 100% reuse existing test Mock patterns instead of redesigning
- **Pattern**: Use `DatabaseTypedSPILoader.getService(DialectPipelineSQLBuilder.class, databaseType)` + `TypedSPILoader.getService(DatabaseType.class, "Oracle")` combination
- **Prevention**: Analyze existing tests completely before writing new ones

#### Branch Coverage Strategy Inefficiency
- **Issue**: Writing too many granular tests for simple methods
- **Solution**: Merge simple method tests, focus independent tests on complex branches only
- **Guideline**: One test per conditional branch, not one test per method
- **Example**: Test all simple SQL formatting methods in one focused test

### Coverage Problems
- **Issue**: Mock configuration incomplete, branches not executed
- **Solution**: Use MockedConstruction, create dedicated test methods for each branch
- **Command**: `./mvnw clean test jacoco:report -pl ${submodule}`

### Mock Configuration Errors
- **Issue**: UnfinishedStubbingException in static methods
- **Solution**: Use `doReturn().when()` instead of `when().thenReturn()`
- **Pattern**: `@SneakyThrows(SQLException.class) private static Array createMockArray()`

### Test Failures
- **Issue**: Mock dependency chain broken
- **Solution**: Verify complete dependency chain, use RETURNS_DEEP_STUBS
- **Check**: Mock calls with `verify(mock).method(params)`

### Compilation Errors
- **Issue**: Dependency conflicts, syntax errors
- **Solution**: Check versions, verify imports, run `./mvnw dependency:tree`

### Quick Reference
```bash
# Generate coverage report
./mvnw clean test jacoco:report -Djacoco.skip=false -pl ${submodule}

# View coverage details
open ${submodule}/target/site/jacoco/index.html

# Check dependencies
./mvnw dependency:tree
```

---

## 📋 Quality Checklist

### Before Starting
- [ ] Task type identified (source/test/docs)
- [ ] Quality requirements understood
- [ ] Relevant templates found

### Before Completing
- [ ] Source: 100% coverage + formatting + self-documenting
- [ ] Test: Complete branch coverage
- [ ] Docs: Valid links + consistent format
- [ ] All: Project constraints satisfied

### Final Verification
- [ ] Build: `./mvnw install -T1C`
- [ ] Coverage: `./mvnw test jacoco:check@jacoco-check -Pcoverage-check`
- [ ] Format: `./mvnw spotless:apply -Pcheck`

## README.md

## [Apache ShardingSphere - Enterprise Distributed Database Ecosystem](https://shardingsphere.apache.org/)

Building the standards and ecosystem on top of heterogeneous databases, empowering enterprise data architecture transformation

**Official Website:** [https://shardingsphere.apache.org/](https://shardingsphere.apache.org/)

[![GitHub Release](https://img.shields.io/github/release/apache/shardingsphere.svg)](https://github.com/apache/shardingsphere/releases)
[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=apache_shardingsphere&metric=ncloc)](https://sonarcloud.io/summary/new_code?id=apache_shardingsphere)

[![CI](https://github.com/apache/shardingsphere/actions/workflows/ci.yml/badge.svg)](https://github.com/apache/shardingsphere/actions/workflows/ci.yml)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=apache_shardingsphere&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=apache_shardingsphere)
[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=apache_shardingsphere&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=apache_shardingsphere)
[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=apache_shardingsphere&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=apache_shardingsphere)
[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=apache_shardingsphere&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=apache_shardingsphere)
[![codecov](https://codecov.io/gh/apache/shardingsphere/branch/master/graph/badge.svg)](https://codecov.io/gh/apache/shardingsphere)

[![OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/projects/5394/badge)](https://bestpractices.coreinfrastructure.org/projects/5394)

[![Slack](https://img.shields.io/badge/%20Slack-ShardingSphere%20Channel-blueviolet)](https://join.slack.com/t/apacheshardingsphere/shared_invite/zt-sbdde7ie-SjDqo9~I4rYcR18bq0SYTg)
[![Gitter](https://badges.gitter.im/shardingsphere/shardingsphere.svg)](https://gitter.im/shardingsphere/Lobby)

[![X](https://img.shields.io/twitter/url/https/twitter.com/ShardingSphere.svg?style=social&label=Follow%20%40ShardingSphere)](https://x.com/ShardingSphere)

<table style="width:100%">
    <tr>
        <th>
            <a href="https://next.ossinsight.io/widgets/official/analyze-repo-stars-map?activity=stars&repo_id=49876476" target="_blank" style="display: block" align="center">
                <picture>
                    <source media="(prefers-color-scheme: dark)" srcset="https://next.ossinsight.io/widgets/official/analyze-repo-stars-map/thumbnail.png?activity=stars&repo_id=49876476&image_size=auto&color_scheme=dark" width="721" height="auto">
                    <img alt="Star Geographical Distribution of apache/shardingsphere" src="https://next.ossinsight.io/widgets/official/analyze-repo-stars-map/thumbnail.png?activity=stars&repo_id=49876476&image_size=auto&color_scheme=light" width="721" height="auto">
                </picture>
            </a>
        </th>
        <th>
            <a href="https://next.ossinsight.io/widgets/official/analyze-repo-stars-map?activity=pull-request-creators&repo_id=49876476" target="_blank" style="display: block" align="center">
                <picture>
                    <source media="(prefers-color-scheme: dark)" srcset="https://next.ossinsight.io/widgets/official/analyze-repo-stars-map/thumbnail.png?activity=pull-request-creators&repo_id=49876476&image_size=auto&color_scheme=dark" width="721" height="auto">
                    <img alt="Pull Request Creator Geographical Distribution of apache/shardingsphere" src="https://next.ossinsight.io/widgets/official/analyze-repo-stars-map/thumbnail.png?activity=pull-request-creators&repo_id=49876476&image_size=auto&color_scheme=light" width="721" height="auto">
                </picture>
            </a>
        </th>
        <th>
            <a href="https://next.ossinsight.io/widgets/official/analyze-repo-stars-map?activity=issue-creators&repo_id=49876476" target="_blank" style="display: block" align="center">
                <picture>
                    <source media="(prefers-color-scheme: dark)" srcset="https://next.ossinsight.io/widgets/official/analyze-repo-stars-map/thumbnail.png?activity=issue-creators&repo_id=49876476&image_size=auto&color_scheme=dark" width="721" height="auto">
                    <img alt="Issue Creator Geographical Distribution of apache/shardingsphere" src="https://next.ossinsight.io/widgets/official/analyze-repo-stars-map/thumbnail.png?activity=issue-creators&repo_id=49876476&image_size=auto&color_scheme=light" width="721" height="auto">
                </picture>
            </a>
        </th>
    </tr>
</table>

### OVERVIEW

<hr>

Apache ShardingSphere is positioned as **Database Plus**, a standard and ecosystem built on top of heterogeneous databases. As an operating system layer above databases, ShardingSphere does not create new databases but focuses on maximizing the computing capabilities of existing databases, providing unified data access and enhanced computing capabilities.

**Database Plus Core Concept**: By building a standardized and scalable enhancement layer above databases, it makes heterogeneous databases as simple to use as a single database, providing unified governance capabilities and distributed computing capabilities for enterprise data architectures.

**Connect, Enhance, and Pluggable** are the three core pillars of Apache ShardingSphere:

- **Connect:** Building database upper-layer standards, quickly connecting applications with multi-modal heterogeneous databases through flexible adaptation of database protocols, SQL dialects, and storage formats, providing unified data access experience;

- **Enhance:** As a database computing enhancement engine, transparently providing enterprise-grade capabilities including distributed computing (data sharding, readwrite-splitting, SQL federation), data security (encryption, masking, audit), traffic control (circuit breaker, rate limiting), and observability (monitoring, tracing, analysis);

- **Pluggable:** Adopting a micro-kernel + 3-layer pluggable architecture to achieve complete decoupling of kernel, functional components, and ecosystem integration. Developers can flexibly customize unique data architecture solutions that meet enterprise needs, just like building with LEGO blocks.

**Differentiation Advantages**:
- **vs Distributed Databases**: More lightweight, protecting existing investments, avoiding vendor lock-in
- **vs Traditional Middleware**: Richer features, more complete ecosystem, more flexible architecture
- **vs Cloud Vendor Solutions**: Support multi-cloud deployment, avoid technology binding, autonomous and controllable

ShardingSphere became an [Apache](https://apache.org/index.html#projects-list) Top-Level Project on April 16, 2020, and has been adopted by [19,000+ projects](https://github.com/search?l=Maven+POM&q=shardingsphere+language%3A%22Maven+POM%22&type=Code) worldwide.

### DUAL-ACCESS ARCHITECTURE DESIGN

<hr>

ShardingSphere adopts a unique dual-access architecture design, providing two access ends - JDBC and Proxy - that can be deployed independently or in hybrid deployment, meeting diverse requirements for different scenarios.

#### ShardingSphere-JDBC: Lightweight Access End

**Positioning**: Lightweight Java framework, enhanced JDBC driver

**Core Features**:
- **Client-side direct connection**: Shares resources with applications, decentralized architecture
- **High performance, low overhead**: Direct database connection with minimal performance loss
- **Complete compatibility**: Compatible with all ORM frameworks (MyBatis, JPA, Hibernate, etc.)
- **Zero additional deployment**: Provided as JAR package, no independent deployment and dependencies required

**Use Cases**: High-performance Java applications, integrated deployment with business applications, pursuing ultimate performance

#### ShardingSphere-Proxy: Enterprise Access End

**Positioning**: Transparent database proxy, independently deployed server-side

**Core Features**:
- **Static entry point**: Independent deployment from applications, providing stable database access entry
- **Heterogeneous language support**: Supports any MySQL/PostgreSQL protocol compatible client
- **DBA friendly**: Database operation and maintenance management interface, convenient for O&M personnel
- **Enterprise-grade features**: Supports cluster deployment, load balancing, failover

**Use Cases**: Heterogeneous language environments, database operation and maintenance management, enterprise applications requiring unified access entry

#### Hybrid Architecture Advantages

By hybridizing ShardingSphere-JDBC and ShardingSphere-Proxy with unified configuration through the same registry center, you can flexibly build application systems suitable for various scenarios:

- **Architectural flexibility**: Architects can freely adjust the optimal system architecture
- **Scenario adaptability**: Select the most suitable access method according to different business scenarios
- **Unified management**: Single configuration, multi-end collaboration, simplifying O&M complexity
- **Progressive evolution**: Support smooth evolution path from JDBC to Proxy

### AI ABSTRACTION

[![DeepWiki](https://img.shields.io/badge/DeepWiki-apache%2Fshardingsphere-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/apache/shardingsphere)
[![zread](https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff)](https://zread.ai/apache/shardingsphere)

### DOCUMENTATION📜

<hr>

[![EN doc](https://img.shields.io/badge/document-English-blue.svg)](https://shardingsphere.apache.org/document/current/en/overview/)
[![CN doc](https://img.shields.io/badge/文档-中文版-blue.svg)](https://shardingsphere.apache.org/document/current/cn/overview/)

For full documentation & more details, visit: [Docs](https://shardingsphere.apache.org/document/current/en/overview/)

### CONTRIBUTION🚀🧑💻

<hr>

For guides on how to get started and setup your environment, contributor & committer guides, visit: [Contribution Guidelines](https://shardingsphere.apache.org/community/en/involved/)

### Team

<hr>

We deeply appreciate [community contributors](https://shardingsphere.apache.org/community/en/team) for their dedication to Apache ShardingSphere.

##

### COMMUNITY & SUPPORT💝🖤

<hr>

:link: [Mailing List](https://shardingsphere.apache.org/community/en/involved/subscribe/). Best for: Apache community updates, releases, changes.

:link: [GitHub Issues](https://github.com/apache/shardingsphere/issues). Best for: design discussions, bug reports, or anything development related.

:link: [Slack channel](https://join.slack.com/t/apacheshardingsphere/shared_invite/zt-sbdde7ie-SjDqo9~I4rYcR18bq0SYTg). Best for: instant communications and online meetings, sharing your applications.

:link: [X](https://x.com/ShardingSphere). Best for: keeping up to date on everything ShardingSphere.

:link: [LinkedIn](https://www.linkedin.com/showcase/apache-shardingsphere/e). Best for: professional networking and career development with other ShardingSphere contributors.

##

### PROJECT STATUS

<hr>

:white_check_mark: **Version 5.5.4-SNAPSHOT**: Actively under development :tada:

🔗 For the release notes, follow this link to the relevant [GitHub page](https://github.com/apache/shardingsphere/blob/master/RELEASE-NOTES.md).

:soon: **Version 5.5.4**

We are currently developing version 5.5.4, which includes multiple security enhancements and performance optimizations.
Keep an eye on the [milestones page](https://github.com/apache/shardingsphere/milestones) of this repo for the latest development progress.

[comment]: <> (##)

[comment]: <> (### NIGHTLY BUILDS:)

[comment]: <> (<hr>)

[comment]: <> (A nightly build of ShardingSphere from the latest master branch is available. )

[comment]: <> (The package is updated daily and is available [here]&#40;http://117.48.121.24:8080&#41;.)

[comment]: <> (##)

[comment]: <> (**‼️ Notice:**)

[comment]: <> (<hr>)

[comment]: <> (Use this nightly build at your own risk! )

[comment]: <> (The branch is not always fully tested. )

[comment]: <> (The nightly build may contain bugs, and there may be new features added which may cause problems with your environment. )

##

### TECHNICAL ARCHITECTURE EVOLUTION

<hr>

Apache ShardingSphere adopts a micro-kernel + 3-layer pluggable architecture, achieving complete decoupling of the kernel, functional components, and ecosystem integration, providing developers with ultimate flexibility and extensibility.

#### Micro-Kernel + 3-Layer Pluggable Model

**Core Layer**:
- Query optimizer: Intelligent SQL routing and execution plan optimization
- Distributed transaction: ACID transaction guarantees and consistency coordination
- Execution engine: Efficient distributed execution and result aggregation

**Feature Layer**:
- Data sharding, readwrite-splitting, federation query
- Data encryption, data masking, SQL audit
- Shadow database, observability, traffic control

**Ecosystem Layer**:
- Database protocol adaptation (MySQL, PostgreSQL, Oracle, etc.)
- Registry center integration (ZooKeeper, ETCD, etc.)
- Configuration management, service discovery, monitoring integration

#### Technical Innovation Highlights

**Complete Decoupling Architecture**:
- Database types completely decoupled, supporting rapid integration of new databases
- Functional modules completely decoupled, supporting on-demand feature combination

Apache ShardingSphere consists of two access ends - JDBC and Proxy - that can be deployed independently or in hybrid deployment, providing unified distributed database solutions for diverse application scenarios including Java isomorphism, heterogeneous languages, and cloud-native environments.

### ShardingSphere-JDBC

<hr>

[![Maven Status](https://img.shields.io/maven-central/v/org.apache.shardingsphere/shardingsphere-jdbc.svg?color=green)](https://mvnrepository.com/artifact/org.apache.shardingsphere/shardingsphere-jdbc)

A lightweight Java framework providing extra services at the Java JDBC layer. 
With the client end connecting directly to the database, it provides services in the form of a jar and requires no extra deployment and dependence.

:link: For more details, follow this [link to the official website](https://shardingsphere.apache.org/document/current/en/overview/#shardingsphere-jdbc).

> **Note**: When using ShardingSphere-JDBC adapter, pay attention to your application's memory configuration. Antlr uses an internal cache to improve performance during SQL parsing. If your application has too many SQL templates, the cache will continue to grow, occupying a large amount of heap memory.
According to feedback from the ANTLR official [issue#4232](https://github.com/antlr/antlr4/issues/4232), this issue has not yet been optimized. When connecting your application to ShardingSphere-JDBC, it is recommended to set a reasonable heap memory size using the `-Xmx` parameter to avoid OOM errors caused by insufficient memory.

### ShardingSphere-Proxy

<hr>

[![Nightly-Download](https://img.shields.io/static/v1?label=nightly-builds&message=download&color=orange)](https://nightlies.apache.org/shardingsphere/)
[![Download](https://img.shields.io/badge/release-download-orange.svg)](https://www.apache.org/dyn/closer.lua/shardingsphere/5.3.2/apache-shardingsphere-5.3.2-shardingsphere-proxy-bin.tar.gz)
[![Docker Pulls](https://img.shields.io/docker/pulls/apache/shardingsphere-proxy.svg)](https://store.docker.com/community/images/apache/shardingsphere-proxy)

A transparent database proxy, providing a database server that encapsulates the database binary protocol to support heterogeneous languages. 
Friendlier to DBAs, the MariaDB, MySQL and PostgreSQL version now provided can use any kind of terminal.

:link: For more details, follow this [link to the official website](https://shardingsphere.apache.org/document/current/en/overview/#shardingsphere-proxy).

### Hybrid Architecture

<hr>

ShardingSphere-JDBC adopts a decentralized architecture, applicable to high-performance light-weight OLTP applications developed with Java. 
ShardingSphere-Proxy provides static entry and all languages support, suitable for an OLAP application and sharding databases management and operation.

Through the combination of ShardingSphere-JDBC & ShardingSphere-Proxy together with a unified sharding strategy by the same registry center, the ShardingSphere ecosystem can build an application system suitable to all kinds of scenarios.

:link: More details can be found following this [link to the official website](https://shardingsphere.apache.org/document/current/en/overview/#hybrid-architecture).

##

### CORE FEATURE MATRIX

<hr>

#### Distributed Database Core Capabilities
- **Data Sharding**: Horizontal sharding, vertical sharding, custom sharding strategies, automatic sharding routing
- **Read/Write Splitting**: Master-slave replication, load balancing, failover, read weight configuration
- **Distributed Transaction**: XA transactions, BASE transactions, transaction propagation

#### Data Security & Governance
- **Data Encryption**: Field-level encryption, transparent encryption, key management, encryption algorithm support
- **Data Masking**: Sensitive data protection, masking strategy customization, dynamic masking rules
- **Access Control**: Fine-grained permissions, access control, SQL firewall, security policies

#### Database Gateway Capabilities
- **Heterogeneous Databases**: MySQL, PostgreSQL, Oracle, SQL Server, Firebird, etc.
- **SQL Dialect Translation**: Cross-database SQL compatibility, dialect adaptation, syntax conversion
- **Protocol Adaptation**: Database protocol conversion, multi-protocol support, communication optimization

#### Full-link Stress Testing & Observability
- **Shadow Database**: Stress testing data isolation, environment separation, real data simulation
- **Observability**: Performance monitoring, distributed tracing, QoS analysis, metrics collection
- **Traffic Analysis**: SQL performance analysis, traffic statistics, bottleneck identification

#### Enterprise-grade Features
- **High Availability**: Cluster deployment, fault recovery, service discovery, health checks
- **Cloud Native**: Containerized deployment, Kubernetes integration, native image support
- **Monitoring & Alerting**: Real-time monitoring, alert notifications, performance metrics, O&M dashboard

##

### Roadmap

<hr>

![Roadmap](https://shardingsphere.apache.org/document/current/img/roadmap_en.png)

##

### How to Build Apache ShardingSphere

<hr>

Check out [Wiki](https://github.com/apache/shardingsphere/wiki) section for details on how to build Apache ShardingSphere and a full guide on how to get started and setup your local dev environment.

##

### Landscapes

<hr>

<p align="center">
<br/><br/>
<img src="https://landscape.cncf.io/images/cncf-landscape-horizontal-color.svg" width="165"/>&nbsp;&nbsp;<img src="https://www.cncf.io/wp-content/uploads/2023/04/cncf-main-site-logo.svg" width="200"/>
<br/><br/>
Apache ShardingSphere enriches the <a href="https://landscape.cncf.io/?category=app-definition-and-development&grouping=category">CNCF CLOUD NATIVE Landscape</a>.
</p>

##