ShardingSphere Overview, Core Concepts, and Horizontal Sharding Example with Spring Boot

Apache ShardingSphere is an open‑source distributed database middleware ecosystem composed of three independent products: ShardingSphere‑JDBC, ShardingSphere‑Proxy, and the planned ShardingSphere‑Sidecar. All provide standardized data sharding, distributed transactions, and governance, suitable for Java or heterogeneous language environments and cloud‑native deployments.

1. ShardingSphere‑JDBC

ShardingSphere‑JDBC is a lightweight Java framework that enhances the JDBC layer. It runs as a client‑side JAR, requires no extra deployment, and is fully compatible with JDBC and ORM frameworks such as JPA, Hibernate, MyBatis, and Spring JDBC Template. It supports any JDBC‑compatible connection pool (e.g., DBCP, C3P0, Druid, HikariCP) and databases that implement the SQL‑92 standard, including MySQL, Oracle, SQLServer, and PostgreSQL.

2. ShardingSphere‑Proxy

ShardingSphere‑Proxy acts as a transparent database proxy that speaks the native binary protocol of MySQL or PostgreSQL, allowing any compatible client (MySQL Command Client, Workbench, Navicat, etc.) to connect without code changes. It is DBA‑friendly and supports both read‑write splitting and sharding.

3. ShardingSphere‑Sidecar

ShardingSphere‑Sidecar is a Kubernetes‑native sidecar proxy that provides a zero‑intrusion, mesh‑style database access layer (Database Mesh), enabling seamless interaction between applications and multiple databases.

4. Mixed Architecture

By combining ShardingSphere‑JDBC (lightweight OLTP) and ShardingSphere‑Proxy (static entry point, heterogeneous language support), users can build flexible architectures that suit various scenarios while sharing a unified sharding configuration via a common registry.

5. Core Concepts & Features

Data sharding addresses performance bottlenecks of single‑node databases and reduces operational costs. Two main sharding strategies are vertical (splitting tables by business domain) and horizontal (splitting rows across tables/databases using a sharding key). Horizontal sharding distributes data based on a column value (e.g., order_id % 2) and is the standard solution for scaling.

Key concepts include:

Data node – the smallest sharding unit (e.g., ds_0.t_order_0).

Sharding key – the column used to determine the target shard.

Sharding algorithm – defines how the key maps to a specific node; supports =, >=, <=, >, <, BETWEEN, IN, and custom implementations.

Sharding strategy – combination of sharding key and algorithm; ShardingSphere provides five built‑in strategies.

Row expression – inline expression syntax such as ${begin..end} or ${[v1,v2]} for generating multiple tables or databases.

Distributed primary key – default Snowflake algorithm generating 64‑bit IDs (1‑bit sign, 41‑bit timestamp, 10‑bit worker ID, 12‑bit sequence).

SQL usage norms list supported statements (full compatibility for MySQL, DML/DDL/DCL/TCL, pagination, sorting, grouping, aggregation, joins without cross‑database) and unsupported features (CASE WHEN, HAVING, UNION ALL, limited sub‑queries).

6. Read/Write Splitting

Read/write splitting improves throughput and availability but introduces data consistency challenges between master and replica nodes, as well as added complexity when combined with sharding.

7. Practical Example – Horizontal Sharding with Spring Boot

The following Maven dependencies are required:

<dependency>
    <groupId>org.apache.shardingsphere</groupId>
    <artifactId>sharding-jdbc-core</artifactId>
    <version>${sharding-sphere.version}</version>
</dependency>

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

Key Java classes (kept unchanged):

package com.cjs.example.sharding.entity;
import lombok.Data;
import javax.persistence.*;
import java.io.Serializable;

@Data
@Entity
@Table(name = "t_order")
public class OrderEntity implements Serializable {
    @Id
    @Column(name = "order_id")
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long orderId;
    private Integer userId;
    private Integer status = 1;
}

package com.cjs.example.sharding.repository;
import com.cjs.example.sharding.entity.OrderEntity;
import org.springframework.data.jpa.repository.JpaRepository;

public interface OrderRepository extends JpaRepository<OrderEntity, Long> {}

package com.cjs.example.sharding.service;
import com.cjs.example.sharding.entity.OrderEntity;
import com.cjs.example.sharding.repository.OrderRepository;
import org.springframework.stereotype.Service;
import javax.annotation.Resource;

@Service
public class OrderService {
    @Resource
    private OrderRepository orderRepository;
    public void save(OrderEntity entity) {
        orderRepository.save(entity);
    }
}

package com.cjs.example.sharding.controller;
import com.cjs.example.sharding.entity.OrderEntity;
import com.cjs.example.sharding.service.OrderService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/order")
public class OrderController {
    @Autowired
    private OrderService orderService;
    @GetMapping("/save")
    public String save(@RequestParam("userId") Integer userId) {
        OrderEntity entity = new OrderEntity();
        entity.setUserId(userId);
        orderService.save(entity);
        return "ok";
    }
}

package com.cjs.example.sharding;
import org.springframework.boot.*;
import org.springframework.boot.autoconfigure.*;
import org.springframework.boot.autoconfigure.transaction.jta.JtaAutoConfiguration;
import javax.annotation.Resource;
import javax.sql.DataSource;

@SpringBootApplication(exclude = JtaAutoConfiguration.class)
public class ShardingJdbcDemoApplication implements CommandLineRunner {
    public static void main(String[] args) {
        SpringApplication.run(ShardingJdbcDemoApplication.class, args);
    }
    @Resource
    private DataSource dataSource;
    @Override
    public void run(String... args) throws Exception {
        System.out.println(dataSource);
    }
}

Configuration in application.properties defines two real data sources (ds0, ds1) and the sharding rule for table t_order:

# Data sources
spring.shardingsphere.datasource.names=ds0,ds1
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
spring.shardingsphere.datasource.ds0.username=root
spring.shardingsphere.datasource.ds0.password=123456

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
spring.shardingsphere.datasource.ds1.username=root
spring.shardingsphere.datasource.ds1.password=123456

# Sharding rule for t_order
spring.shardingsphere.sharding.tables.t_order.actual-data-nodes=ds$->{0..1}.t_order_$->{0..1}
spring.shardingsphere.sharding.tables.t_order.table-strategy.inline.sharding-column=order_id
spring.shardingsphere.sharding.tables.t_order.table-strategy.inline.algorithm-expression=t_order_$->{order_id % 2}
spring.shardingsphere.sharding.tables.t_order.key-generator.type=SNOWFLAKE
spring.shardingsphere.sharding.tables.t_order.key-generator.column=order_id
spring.shardingsphere.sharding.tables.t_order.database-strategy.inline.sharding-column=user_id
spring.shardingsphere.sharding.tables.t_order.database-strategy.inline.algorithm-expression=ds$->{user_id % 2}

spring.shardingsphere.props.sql.show=true

Running the application and accessing http://localhost:8080/order/save?userId=123 inserts a record into the appropriate shard, as demonstrated by the screenshots in the original article.

8. Final Remarks

The primary entry class for Spring Boot integration is

org.apache.shardingsphere.shardingjdbc.spring.boot.SpringBootConfiguration

. While ShardingSphere‑JDBC offers many features, the most commonly used are horizontal sharding and read/write splitting, typically together. Developers should be aware of SQL limitations (mandatory sharding key, no cross‑database joins) and consider using Elasticsearch for heavy query workloads when appropriate.