Quick Integration of ShardingSphere for Database Sharding in Spring Boot

Spring Boot, as a mainstream micro‑service framework, has a mature ecosystem and wide market adoption. To help developers, a series of quick‑start guides for common middleware integration (RPC, cache, message queue, sharding, registration center, distributed configuration, etc.) has been compiled.

The rapid growth of the Internet brings massive data storage problems. Traditional single‑database, single‑table relational databases struggle to cope, leading to two main solutions: NoSQL databases that natively support distributed sharding but lack transaction management, and sharding (splitting databases and tables) combined with resource scheduling to create logical tables capable of handling huge data volumes.

This article focuses on how to quickly integrate a sharding framework with Spring Boot for an out‑of‑the‑box experience.

Besides ShardingSphere , other sharding frameworks such as Cobar and MyCat are also mentioned.

ShardingSphere Introduction

ShardingSphere is an open‑source ecosystem of distributed database middleware solutions. It consists of three independent but combinable products, each providing standardized data sharding, distributed transactions, and database governance.

The three sub‑projects are:

1. ShardingSphere‑JDBC : a lightweight Java framework that adds services at the JDBC layer. It works as an enhanced JDBC driver, compatible with all JDBC‑compliant databases and ORM frameworks (JPA, Hibernate, MyBatis, Spring JDBC Template, etc.) and supports various connection pools (Druid, HikariCP, etc.). Currently supports MySQL, Oracle, SQL Server, and PostgreSQL.

2. ShardingSphere‑Proxy : a transparent database proxy that implements the binary protocol of MySQL/PostgreSQL, allowing any compatible client to access the database without changes.

3. ShardingSphere‑Sidecar (planned): a cloud‑native sidecar for Kubernetes that acts as a zero‑intrusion database mesh.

Advantages:

Complete solution integrating client‑side sharding, proxy server, and core distributed database functions.

Developer‑friendly: adding a single JAR enables data sharding, read/write separation, distributed transactions, and governance directly in business code.

Pluggable extensibility: most core features are provided as plugins that can be combined to build custom systems.

Project Example

First, create a new project named spring-boot-bulking-sharding-sphere and add the sharding starter dependency in pom.xml :

<dependency>
    <groupId>org.apache.shardingsphere</groupId>
    <artifactId>sharding-jdbc-spring-boot-starter</artifactId>
    <version>4.0.0-RC1</version>
</dependency>

Data environment preparation

Create two databases ds0 and ds1 . In ds0 create tables user_0 and user_2 :

CREATE TABLE `user_0` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `user_name` varchar(128) NOT NULL DEFAULT '' COMMENT 'username',
  `age` int(11) NOT NULL COMMENT 'age',
  `address` varchar(128) COMMENT 'address',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='User table';

CREATE TABLE `user_2` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `user_name` varchar(128) NOT NULL DEFAULT '' COMMENT 'username',
  `age` int(11) NOT NULL COMMENT 'age',
  `address` varchar(128) COMMENT 'address',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='User table';

In ds1 create tables user_1 and user_3 :

CREATE TABLE `user_1` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `user_name` varchar(128) NOT NULL DEFAULT '' COMMENT 'username',
  `age` int(11) NOT NULL COMMENT 'age',
  `address` varchar(128) COMMENT 'address',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='User table';

CREATE TABLE `user_3` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `user_name` varchar(128) NOT NULL DEFAULT '' COMMENT 'username',
  `age` int(11) NOT NULL COMMENT 'age',
  `address` varchar(128) COMMENT 'address',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='User table';

We use MyBatis as the ORM framework. First define the entity class User , the mapper interface UserMapper , and the corresponding XML SQL file.

@Mapper
public interface UserMapper {

    Long addUser(User user);

    List<User> queryAllUser();

    User queryUserById(Long id);

    Page<User> querUserByPage();
}

Spring Boot follows the principle of "convention over configuration". Bean definitions are moved to application.properties and auto‑configuration is enabled via EnableAutoConfiguration .

Two DataSource objects are created for the two databases and passed to ShardingDataSourceFactory . The following is the application.properties configuration:

server.port=8090
application.name=spring-boot-bulking-sharding-sphere
mybatis.config-location=classpath:config/mybatis-config.xml
spring.shardingsphere.datasource.names=ds0,ds1

# Data sources
spring.shardingsphere.datasource.ds0.type=com.alibaba.druid.pool.DruidDataSource
spring.shardingsphere.datasource.ds0.driver-class-name=com.mysql.jdbc.Driver
spring.shardingsphere.datasource.ds0.url=jdbc:mysql://localhost:3306/ds0?characterEncoding=utf-8
spring.shardingsphere.datasource.ds0.username=root
spring.shardingsphere.datasource.ds0.password=111111
spring.shardingsphere.datasource.ds1.type=com.alibaba.druid.pool.DruidDataSource
spring.shardingsphere.datasource.ds1.driver-class-name=com.mysql.jdbc.Driver
spring.shardingsphere.datasource.ds1.url=jdbc:mysql://localhost:3306/ds1?characterEncoding=utf-8
spring.shardingsphere.datasource.ds1.username=root
spring.shardingsphere.datasource.ds1.password=111111

After configuring the data sources, the sharding and table strategies are set:

# Default data source (no table‑level config)
spring.shardingsphere.sharding.default-data-source-name=ds1

# user table sharding configuration
spring.shardingsphere.sharding.tables.user.actual-data-nodes=ds0.user_$->{[0,2]},ds1.user_$->{[1,3]}
# Database strategy (can use default)
spring.shardingsphere.sharding.tables.user.database-strategy.inline.sharding-column=id
spring.shardingsphere.sharding.tables.user.database-strategy.inline.algorithm-expression=ds$->{id % 2}
# Table strategy
spring.shardingsphere.sharding.tables.user.table-strategy.inline.sharding-column=id
spring.shardingsphere.sharding.tables.user.table-strategy.inline.algorithm-expression=user_$->{id % 4}

ShardingSphere uses InlineShardingStrategyConfiguration , which requires a sharding column (e.g., id ) and an inline algorithm expression. In the example, the id column modulo 2 determines the target database, and modulo 4 determines the target table.

The InlineShardingStrategyConfiguration contains two parameters: shardingColumn (the column name) and algorithmExpression (the inline expression). The example uses the id column modulo 2 to decide which database stores the row.

We split the user table into four physical tables across two databases, using id as the sharding key.

Unit test inserting ten users demonstrates the sharding effect:

@Test
public void addUser() {
    for (long i = 1; i < 11; i++) {
        User user = User.builder().id(i).userName("TomGE").age(29).address("Hangzhou").build();
        userMapper.addUser(user);
        System.out.println("Insert user success, uid=" + user.getId());
    }
}

Records with id=4 and id=8 are stored in the user_0 table of the ds0 database.

Project Source Code

https://github.com/aalansehaiyang/spring-boot-bulking

Module: spring-boot-bulking-sharding-sphere

Recommended reading includes articles on Redis cache design for billion‑scale systems, ten design principles for architects, and Spring Boot integration with Kafka.