Principle:Apache Shardingsphere Configuration Validation

Knowledge Sources	Apache ShardingSphere ShardingSphere Shadow Docs
Domains	Configuration_Management, Shadow_Testing
Last Updated	2026-02-10 00:00 GMT

Overview

Multi-stage validation of rule configuration to ensure referential integrity between data sources, tables, and algorithms.

Description

Configuration Validation is a systematic process that verifies the correctness and internal consistency of a rule configuration before it is used to construct runtime rule objects. In a shadow rule configuration, multiple entities reference each other: tables reference data source names and algorithm names, the default algorithm must be of a specific type, and all referenced data sources must actually exist in the database's data source map. Validation ensures that these cross-references are consistent and that missing or invalid references are caught early with descriptive error messages.

The validation process is multi-stage, checking different aspects in sequence:

• Algorithm Type Verification: Each declared shadow algorithm configuration must resolve to a valid SPI implementation. The algorithm type string and its properties are checked against the registered ShadowAlgorithm SPI services.
• Default Algorithm Constraint: If a default shadow algorithm is specified, it must be of the SQL_HINT type. This constraint ensures that the default algorithm can operate without table-specific column configuration.
• Data Source Existence: Both the production data source and the shadow data source referenced in each shadow data source mapping must exist in the actual data source map provided by the database metadata.
• Table-to-DataSource Referential Integrity: Each data source name referenced by a shadow table configuration must correspond to a declared shadow data source mapping.
• Table-to-Algorithm Referential Integrity: Each algorithm name referenced by a shadow table must exist in the declared shadow algorithms map, and every table must reference at least one algorithm.

An additional empty-check stage determines whether the configuration is substantively empty (no data sources or no tables), which signals that the rule should not be built at all.

Usage

Use Configuration Validation after the YAML configuration has been deserialized and swapped into a domain configuration object, but before the rule builder constructs the runtime rule. Validation is also invoked when configuration is modified at runtime via DistSQL, to prevent invalid configurations from being applied.

Theoretical Basis

The multi-stage validation pattern follows this logic:

FUNCTION validateConfiguration(databaseName, ruleConfig, dataSourceMap):
    // Stage 1: Verify all algorithms are valid SPI types
    FOR EACH algorithmConfig IN ruleConfig.shadowAlgorithms:
        checkSPIService(ShadowAlgorithm, algorithmConfig.type, algorithmConfig.props)

    // Stage 2: Verify default algorithm constraint
    IF ruleConfig.defaultShadowAlgorithmName IS NOT NULL:
        algo = ruleConfig.shadowAlgorithms[defaultShadowAlgorithmName]
        ASSERT algo IS NOT NULL AND algo.type == "SQL_HINT"

    // Stage 3: Verify data source existence
    FOR EACH dsConfig IN ruleConfig.dataSources:
        ASSERT dsConfig.productionDataSourceName IN dataSourceMap
        ASSERT dsConfig.shadowDataSourceName IN dataSourceMap

    // Stage 4: Verify table -> data source references
    validDataSourceNames = ruleConfig.dataSources.map(ds -> ds.name)
    FOR EACH (tableName, tableConfig) IN ruleConfig.tables:
        FOR EACH dsName IN tableConfig.dataSourceNames:
            ASSERT dsName IN validDataSourceNames

    // Stage 5: Verify table -> algorithm references
    FOR EACH tableConfig IN ruleConfig.tables:
        ASSERT tableConfig.shadowAlgorithmNames IS NOT EMPTY
        FOR EACH algoName IN tableConfig.shadowAlgorithmNames:
            ASSERT algoName IN ruleConfig.shadowAlgorithms
END FUNCTION

Each assertion failure throws a specific, descriptive exception:

• MissingRequiredProductionDataSourceException when a production data source is not found
• MissingRequiredShadowDataSourceException when a shadow data source is not found
• ShadowDataSourceMappingNotFoundException when a table references a non-existent data source mapping
• MissingRequiredAlgorithmException when a table references a non-existent algorithm or has no algorithms
• NotImplementHintShadowAlgorithmException when the default algorithm is not of type SQL_HINT

Related Pages

Implemented By

• Implementation:Apache_Shardingsphere_ShadowRuleConfigurationChecker_Check