Master ShardingSphere: Quick Sharding with Spring Boot and YML

Hello, I am Su San. This article is the third part of the "ShardingSphere 5.x Sharding Principles and Practice" series, introducing basic features and architecture of ShardingSphere and showing how to quickly achieve sharding in a Spring Boot environment using Java code or YML configuration.

1. What is ShardingSphere?

ShardingSphere is an open‑source distributed relational database middleware and an Apache top‑level project. It originated from the independent projects sharding-jdbc and sharding-proxy, which were merged in 2018 and renamed ShardingSphere. The ecosystem now includes three middleware components: sharding-jdbc, sharding-proxy, and sharding-sidecar. sharding-jdbc is the classic entry point for learning sharding.

ShardingSphere is no longer a single framework but a complete technology ecosystem composed of these three open‑source distributed database middleware projects.

2. Why Choose ShardingSphere?

To answer this, we compare ShardingSphere with several popular sharding solutions: Cobar, MyCAT, TDDL, MySQL Fabric, and ShardingSphere itself.

Cobar

Cobar is an Alibaba‑open‑source MySQL‑based distributed database middleware offering sharding, read/write separation, and transaction management. It uses round‑robin and hash algorithms for data partitioning, supports only MySQL, and requires only a Java environment.

MyCAT

MyCAT is a community‑driven fork of Cobar, providing sharding, read/write separation, SQL routing, and data partitioning. It supports many ORM frameworks but only works with MySQL and has relatively low community activity.

TDDL

TDDL, also from Alibaba, supports vertical and horizontal sharding, multiple data sources, and read/write separation. It works with MySQL, Oracle, and SQL Server, but its documentation and community are less active than ShardingSphere.

MySQL Fabric

MySQL Fabric is the official MySQL sharding solution, supporting high availability and load balancing. It only works with MySQL and has limited community support.

ShardingSphere

ShardingSphere’s sharding-jdbc provides sharding, read/write separation, and distributed transactions via a JAR package, but only for Java applications. The independent sharding-proxy middleware implements transparent sharding over the MySQL protocol, supporting multiple languages and frameworks without code changes. It works with MySQL, PostgreSQL, SQL Server, Oracle, and integrates well with Hibernate, MyBatis, JPA, etc., and enjoys a very active open‑source community.

Product Comparison

Overall, ShardingSphere outperforms the other tools in performance, feature richness, and community support. The following table (image) summarizes the main indicators.

3. ShardingSphere Members

The core members are sharding-jdbc and sharding-proxy, representing two different sharding modes.

sharding-jdbc

It is a lightweight Java framework that provides JDBC‑based sharding in a client‑direct mode. Developers can configure sharding with simple YAML or properties files without modifying existing SQL, and it supports many sharding strategies and algorithms.

sharding-proxy

It is a MySQL‑protocol‑based proxy service that provides transparent sharding. It decouples sharding logic from the application, supports multiple data sources, read/write separation, and can run as an independent service.

4. Quick Implementation

We first use sharding-jdbc for a simple sharding scenario. Compared with sharding-proxy, sharding-jdbc does not require extra environment setup. Two implementation methods are shown: YML configuration (recommended) and pure Java coding (cannot coexist).

ShardingSphere official site: https://shardingsphere.apache.org/

Preparation Work

We split the t_order table into two databases ( db1 and db2), each containing three physical tables ( t_order_0, t_order_1, t_order_2).

db0
├── t_order_0
├── t_order_1
└── t_order_2
db1
├── t_order_0
├── t_order_1
└── t_order_2

JAR Package Introduction

The essential dependencies are shardingsphere-jdbc-core-spring-boot-starter and mysql-connector-java. We also add Spring Data JPA for persistence.

<!-- jpa persistence tool -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
    <version>2.7.6</version>
</dependency>
<!-- MySQL driver -->
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.31</version>
</dependency>
<!-- ShardingSphere starter -->
<dependency>
    <groupId>org.apache.shardingsphere</groupId>
    <artifactId>shardingsphere-jdbc-core-spring-boot-starter</artifactId>
    <version>5.2.0</version>
</dependency>

YML Configuration

Place the following configuration in src/main/resources/application.yml to shard the t_order table.

spring:
  shardingsphere:
    datasource:
      names: db0,db1
      db0:
        type: com.zaxxer.hikari.HikariDataSource
        driver-class-name: com.mysql.cj.jdbc.Driver
        jdbc-url: jdbc:mysql://127.0.0.1:3306/shardingsphere-db1?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
        username: root
        password: 123456
      db1:
        type: com.zaxxer.hikari.HikariDataSource
        driver-class-name: com.mysql.cj.jdbc.Driver
        jdbc-url: jdbc:mysql://127.0.0.1:3306/shardingsphere-db0?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
        username: root
        password: 123456
    rules:
      sharding:
        sharding-algorithms:
          database-inline:
            type: INLINE
            props:
              algorithm-expression: db$->{order_id > 4 ?1:0}
          table-inline:
            type: INLINE
            props:
              algorithm-expression: t_order_$->{order_id % 4}
        tables:
          t_order:
            actual-data-nodes: db${0..1}.t_order_${0..3}
            database-strategy:
              standard:
                sharding-column: order_id
                sharding-algorithm-name: database-inline
            table-strategy:
              standard:
                sharding-column: order_id
                sharding-algorithm-name: table-inline
    props:
      sql-show: true

The algorithm-expression uses Groovy syntax to calculate the target database or table based on the sharding key.

Java Coding

If you prefer programmatic configuration, the following Java class creates the same sharding rules via the ShardingSphere API.

@Configuration
public class ShardingConfiguration {
    /** Configure sharding data source */
    @Bean
    public DataSource getShardingDataSource() throws SQLException {
        Map<String, DataSource> dataSourceMap = new HashMap<>();
        dataSourceMap.put("db0", dataSource1());
        dataSourceMap.put("db1", dataSource2());
        ShardingRuleConfiguration shardingRuleConfig = new ShardingRuleConfiguration();
        shardingRuleConfig.setShardingAlgorithms(getShardingAlgorithms());
        ShardingTableRuleConfiguration orderTableRuleConfig = new ShardingTableRuleConfiguration("t_order", "db${0..1}.t_order_${0..2}");
        orderTableRuleConfig.setTableShardingStrategy(new StandardShardingStrategyConfiguration("order_id", "table-inline"));
        orderTableRuleConfig.setDatabaseShardingStrategy(new StandardShardingStrategyConfiguration("order_id", "database-inline"));
        shardingRuleConfig.getTables().add(orderTableRuleConfig);
        Properties properties = new Properties();
        properties.setProperty("sql-show", "true");
        return ShardingSphereDataSourceFactory.createDataSource(dataSourceMap, Collections.singleton(shardingRuleConfig), properties);
    }
    public DataSource dataSource1() {
        HikariDataSource ds = new HikariDataSource();
        ds.setDriverClassName("com.mysql.cj.jdbc.Driver");
        ds.setJdbcUrl("jdbc:mysql://127.0.0.1:3306/shardingsphere-db1?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true");
        ds.setUsername("root");
        ds.setPassword("123456");
        return ds;
    }
    public DataSource dataSource2() {
        HikariDataSource ds = new HikariDataSource();
        ds.setDriverClassName("com.mysql.cj.jdbc.Driver");
        ds.setJdbcUrl("jdbc:mysql://127.0.0.1:3306/shardingsphere-db0?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true");
        ds.setUsername("root");
        ds.setPassword("123456");
        return ds;
    }
    private Map<String, AlgorithmConfiguration> getShardingAlgorithms() {
        Map<String, AlgorithmConfiguration> shardingAlgorithms = new LinkedHashMap<>();
        Properties dbProps = new Properties();
        dbProps.setProperty("algorithm-expression", "db$->{order_id % 2}");
        shardingAlgorithms.put("database-inline", new AlgorithmConfiguration("INLINE", dbProps));
        Properties tableProps = new Properties();
        tableProps.setProperty("algorithm-expression", "t_order_$->{order_id % 3}");
        shardingAlgorithms.put("table-inline", new AlgorithmConfiguration("INLINE", tableProps));
        return shardingAlgorithms;
    }
}

Both approaches achieve the same sharding effect; the YML method is generally more concise and easier to maintain.

Default Data Source

If a table has no sharding rule (e.g., t_user), ShardingSphere uses the first data source listed in datasource.names as the default. Changing the order of the names changes which physical database receives the data.

spring:
  shardingsphere:
    datasource:
      names: db2, db1, db0

Summary

This article introduced ShardingSphere, compared it with other sharding solutions, explained its core components, and demonstrated two quick ways—YML configuration and Java API—to implement database sharding in a Spring Boot project. The next article will cover default sharding strategies, broadcast tables, and binding tables.