How to Integrate ShardingSphere with Spring and Spring Boot

ShardingSphere offers two system‑integration mechanisms with the Spring ecosystem: extending the Spring XML schema (namespace) and creating a custom Spring Boot starter.

1. Namespace‑Based Integration with Spring

By extending Spring's XML schema, developers can define custom tags that map to ShardingSphere components. The process includes:

Creating business objects (e.g., SpringShardingDataSource extending ShardingDataSource).

Defining XSD files that describe tags such as data-source and sharding-rule.

Implementing BeanDefinitionParser classes to parse these tags.

Providing NamespaceHandler implementations (e.g., ShardingNamespaceHandler) that register parsers via registerBeanDefinitionParser.

Adding spring.handlers and spring.schemas entries to map namespaces to handlers and XSD files.

Key classes:

public class SpringShardingDataSource extends ShardingDataSource { ... }

Tag definition example:

public final class ShardingDataSourceBeanDefinitionParserTag {
    public static final String ROOT_TAG = "data-source";
    public static final String SHARDING_RULE_CONFIG_TAG = "sharding-rule";
    // other tag constants …
}

Sample XML configuration:

<sharding:data-source id="shardingDataSource">
    <sharding:sharding-rule data-source-names="ds0,ds1">
        <sharding:table-rules>
            <sharding:table-rule …/>
        </sharding:table-rules>
    </sharding:sharding-rule>
    <sharding:props/>
</sharding:data-source>

2. Custom Starter Integration with Spring Boot

ShardingSphere provides two starters: sharding-jdbc-spring-boot-starter and sharding-jdbc-orchestration-spring-boot-starter. The integration relies on Spring Boot's auto‑configuration mechanism.

The starter includes a META-INF/spring.factories entry mapping EnableAutoConfiguration to

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

. SpringBootConfiguration is annotated with @Configuration, @ComponentScan, @EnableConfigurationProperties, and conditional annotations to create the appropriate DataSource beans.

Key annotations explained: @SpringBootApplication – combines @Configuration, @EnableAutoConfiguration, and @ComponentScan. @EnableTransactionManagement – enables @Transactional support. @ShardingSphereDataSource – custom annotation for ShardingSphere data source configuration.

Example of a Spring Boot configuration class:

@SpringBootApplication
@EnableTransactionManagement
public class SpringBootConfiguration {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootConfiguration.class, args);
    }

    @Bean
    public DataSource dataSource() throws Exception {
        // Assume a sharding YAML file exists
        return YamlShardingSphereDataSourceFactory.createDataSource(new File("path/to/sharding-databases-tables.yaml"));
    }
}

Conditional bean creation uses classes like ShardingRuleCondition that check for master‑slave or encrypt rules before loading the sharding data source.

3. Summary

When building custom frameworks or tools, integrating with mainstream platforms such as Spring reduces learning and maintenance costs. ShardingSphere’s integration steps—whether via XML namespace extensions or Spring Boot starters—provide a repeatable pattern that can be adapted for other projects.

FAQ

Q: What annotations are used on the SpringBootConfiguration class when integrating ShardingSphere with Spring Boot, and what are their purposes?

A: The class typically includes @SpringBootApplication (combines configuration, auto‑configuration, and component scanning), @EnableTransactionManagement (enables declarative transaction handling), and may also use @EnableConfigurationProperties to bind external properties to beans. Additional custom annotations like @ShardingSphereDataSource configure ShardingSphere‑specific data source behavior.