Guide to Setting Up ShardingSphere with Docker for Database Sharding, Read‑Write Splitting, and SpringBoot Integration

Software versions: Docker 26.1.3, MySQL 8.4.0, ShardingSphere 5.5.0.

Sharding (Database Partitioning)

1. Create two MySQL containers using Docker Compose:

services:
  mysql:
    image: mysql:8.4.0
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: abc123
    volumes:
      - ./data:/var/lib/mysql
      - ./config:/etc/mysql/conf.d
    restart: always

2. Create test databases and tables in each MySQL instance (SQL DDL for demo.t_address, demo.t_order_0, demo.t_order_item_0, demo.t_order_1, demo.t_order_item_1).

-- demo.t_address definition
CREATE TABLE `t_address` (
  `user_id` bigint NOT NULL AUTO_INCREMENT,
  `name` varchar(100) NOT NULL,
  PRIMARY KEY (`user_id`)
) ENGINE=InnoDB AUTO_INCREMENT=2 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;

-- demo.t_order_0 definition
CREATE TABLE `t_order_0` (
  `order_id` bigint NOT NULL,
  `user_id` bigint NOT NULL,
  `name` varchar(100) NOT NULL,
  PRIMARY KEY (`order_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;

-- demo.t_order_item_0 definition
CREATE TABLE `t_order_item_0` (
  `order_item_id` bigint NOT NULL,
  `order_id` bigint NOT NULL,
  `user_id` bigint NOT NULL,
  `name` varchar(100) NOT NULL,
  PRIMARY KEY (`order_item_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;

-- demo.t_order_1 definition
CREATE TABLE `t_order_1` (
  `order_id` bigint NOT NULL,
  `user_id` bigint NOT NULL,
  `name` varchar(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL,
  PRIMARY KEY (`order_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;

-- demo.t_order_item_1 definition
CREATE TABLE `t_order_item_1` (
  `order_item_id` bigint NOT NULL,
  `order_id` bigint NOT NULL,
  `user_id` bigint NOT NULL,
  `name` varchar(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL,
  PRIMARY KEY (`order_item_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;

3. Write a docker-compose.yml for ShardingSphere‑Proxy:

services:
  shardingsphere:
    image: apache/shardingsphere-proxy:5.5.0
    ports:
      - "3307:3307"
    volumes:
      - ./conf:/opt/shardingsphere-proxy/conf
      - ./ext-lib:/opt/shardingsphere-proxy/ext-lib
    restart: always

4. Place the MySQL driver JAR ( mysql-connector-java-5.1.49.jar or mysql-connector-java-8.0.11.jar ) into the ext-lib directory.

5. Add sharding configuration to conf/database-sharding.yaml (data sources, sharding rules, algorithms, key generators, broadcast tables).

databaseName: demo
dataSources:
  ds_0:
    url: jdbc:mysql://192.168.1.111:3306/demo?allowPublicKeyRetrieval=true
    username: root
    password: abc123
    connectionTimeoutMilliseconds: 30000
    idleTimeoutMilliseconds: 60000
    maxLifetimeMilliseconds: 1800000
    maxPoolSize: 50
    minPoolSize: 1
  ds_1:
    url: jdbc:mysql://192.168.1.112:3306/demo?allowPublicKeyRetrieval=true
    username: root
    password: abc123
    connectionTimeoutMilliseconds: 30000
    idleTimeoutMilliseconds: 60000
    maxLifetimeMilliseconds: 1800000
    maxPoolSize: 50
    minPoolSize: 1
rules:
  - !SHARDING
    tables:
      t_order:
        actualDataNodes: ds_${0..1}.t_order_${0..1}
        tableStrategy:
          standard:
            shardingColumn: order_id
            shardingAlgorithmName: t_order_inline
        keyGenerateStrategy:
          column: order_id
          keyGeneratorName: snowflake
      t_order_item:
        actualDataNodes: ds_${0..1}.t_order_item_${0..1}
        tableStrategy:
          standard:
            shardingColumn: order_id
            shardingAlgorithmName: t_order_item_inline
        keyGenerateStrategy:
          column: order_item_id
          keyGeneratorName: snowflake
    bindingTables:
      - t_order,t_order_item
    defaultDatabaseStrategy:
      standard:
        shardingColumn: user_id
        shardingAlgorithmName: database_inline
    defaultTableStrategy:
      none:
    shardingAlgorithms:
      database_inline:
        type: INLINE
        props:
          algorithm-expression: ds_${user_id % 2}
          allow-range-query-with-inline-sharding: true
      t_order_inline:
        type: INLINE
        props:
          algorithm-expression: t_order_${order_id % 2}
          allow-range-query-with-inline-sharding: true
      t_order_item_inline:
        type: INLINE
        props:
          algorithm-expression: t_order_item_${order_id % 2}
          allow-range-query-with-inline-sharding: true
    keyGenerators:
      snowflake:
        type: SNOWFLAKE
  - !BROADCAST
    tables:
      - t_address

6. Start ShardingSphere‑Proxy; the default connection URL is jdbc:mysql://127.0.0.1:3307/demo with username/password root .

Read‑Write Splitting

1. Prepare two MySQL servers with master‑slave replication.

2. Use the same ShardingSphere‑Proxy container as above.

3. Add the MySQL driver JAR to ext-lib as before.

4. Add read‑write splitting configuration to conf/database-readwrite-splitting.yaml (write_ds, read_ds, rules).

databaseName: demo
dataSources:
  write_ds:
    url: jdbc:mysql://192.168.1.113:3306/demo?allowPublicKeyRetrieval=true
    username: root
    password: abc123
    connectionTimeoutMilliseconds: 30000
    idleTimeoutMilliseconds: 60000
    maxLifetimeMilliseconds: 1800000
    maxPoolSize: 50
    minPoolSize: 1
  read_ds:
    url: jdbc:mysql://192.168.1.114:3306/demo?allowPublicKeyRetrieval=true
    username: root
    password: abc123
    connectionTimeoutMilliseconds: 30000
    idleTimeoutMilliseconds: 60000
    maxLifetimeMilliseconds: 1800000
    maxPoolSize: 50
    minPoolSize: 1
rules:
  - !READWRITE_SPLITTING
    dataSources:
      readwrite_ds:
        writeDataSourceName: write_ds
        readDataSourceNames:
          - read_ds
        loadBalancerName: random
    loadBalancers:
      random:
        type: RANDOM
  - !SINGLE
    tables:
      - readwrite_ds.*

5. Start the proxy; the same default URL/credentials apply.

JDBC Integration with SpringBoot 2.x

1. Add Maven dependencies for shardingsphere-jdbc , snakeyaml , and mysql-connector-j .

<dependency>
    <groupId>org.apache.shardingsphere</groupId>
    <artifactId>shardingsphere-jdbc</artifactId>
    <version>5.5.0</version>
    <exclusions>
        <exclusion>
            <groupId>org.apache.shardingsphere</groupId>
            <artifactId>shardingsphere-test-util</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.yaml</groupId>
    <artifactId>snakeyaml</artifactId>
    <version>2.2</version>
</dependency>
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>

2. Configure SpringBoot datasource to use ShardingSphere driver and point to the YAML file.

spring.datasource.driver-class-name=org.apache.shardingsphere.driver.ShardingSphereDriver
spring.datasource.url=jdbc:shardingsphere:classpath:database-sharding.yaml

3. Place the same database-sharding.yaml (as shown earlier) under src/main/resources .

4. Run the application; the database operations work the same as with a regular MySQL connection, and MyBatis can be added for ORM.