Implementation:Apache Shardingsphere ShadowRule GetShadowDataSourceMappings

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

Overview

Concrete tools for resolving production-to-shadow data source name mappings from the shadow rule configuration, provided by the ShardingSphere shadow module.

Description

ShadowRule is a final class implementing DatabaseRule. It manages the complete shadow routing configuration including shadow algorithms, data source rules, table rules, and rule attributes. Three methods on this class are responsible for data source mapping resolution:

getShadowDataSourceMappings(String tableName) (lines 213-220): Returns the production-to-shadow data source mappings for a specific shadow table. It looks up the ShadowTableRule for the given table name, iterates over its logical data source names, and for each one retrieves the corresponding ShadowDataSourceRule from the dataSourceRules map. The result is a LinkedHashMap mapping each production data source name to its shadow counterpart. This method is annotated with @HighFrequencyInvocation.

getAllShadowDataSourceMappings() (lines 228-235): Returns all production-to-shadow data source mappings across the entire shadow configuration, regardless of table association. It iterates over all entries in the dataSourceRules map and builds a LinkedHashMap from production to shadow data source names. This is used when a default shadow algorithm matches or when global shadow routing is needed. This method is annotated with @HighFrequencyInvocation.

findProductionDataSourceName(String logicDataSourceName) (lines 244-247): Performs a reverse lookup to determine whether a given data source name corresponds to a known production data source in the shadow configuration. It looks up the dataSourceRules map using the provided logical data source name. If a ShadowDataSourceRule is found, it returns Optional.of(dataSourceRule.getProductionDataSource()); otherwise, it returns Optional.empty(). This method is annotated with @HighFrequencyInvocation and is called by ShadowSQLRouter.decorateRouteContext for every route unit.

The dataSourceRules map is stored as a CaseInsensitiveMap, constructed during ShadowRule initialization from ShadowDataSourceConfiguration entries. Each entry contains a logical name, a production data source name, and a shadow data source name.

Usage

These methods are used internally by the shadow routing pipeline:

• getShadowDataSourceMappings is called by hint and column retrievers when a table-specific shadow match is found
• getAllShadowDataSourceMappings is called when a default/global shadow match is found
• findProductionDataSourceName is called by ShadowSQLRouter.decorateRouteContext to identify which route units correspond to shadow-configured production data sources

Code Reference

Source Location

• Repository: Apache ShardingSphere
• File: features/shadow/core/src/main/java/org/apache/shardingsphere/shadow/rule/ShadowRule.java

Signature: getShadowDataSourceMappings

• Lines: 213-220

@HighFrequencyInvocation
public Map<String, String> getShadowDataSourceMappings(final String tableName)

Signature: getAllShadowDataSourceMappings

• Lines: 228-235

@HighFrequencyInvocation
public Map<String, String> getAllShadowDataSourceMappings()

Signature: findProductionDataSourceName

• Lines: 244-247

@HighFrequencyInvocation
public Optional<String> findProductionDataSourceName(final String logicDataSourceName)

Import

import org.apache.shardingsphere.shadow.rule.ShadowRule;

I/O Contract

Inputs: getShadowDataSourceMappings

Name	Type	Required	Description
tableName	String	Yes	The name of the shadow table whose data source mappings should be resolved

Outputs: getShadowDataSourceMappings

Name	Type	Description
return	Map<String, String>	An ordered map from production data source name to shadow data source name, containing entries for each logical data source associated with the given table

Inputs: getAllShadowDataSourceMappings

Name	Type	Required	Description
(none)			This method takes no parameters

Outputs: getAllShadowDataSourceMappings

Name	Type	Description
return	Map<String, String>	An ordered map from production data source name to shadow data source name for all configured shadow data sources

Inputs: findProductionDataSourceName

Name	Type	Required	Description
logicDataSourceName	String	Yes	The logical data source name to look up in the shadow data source rules (case-insensitive)

Outputs: findProductionDataSourceName

Name	Type	Description
return	Optional<String>	The production data source name if the logical name matches a configured shadow data source rule, or Optional.empty() if no match is found

Usage Examples

Table-Specific Mapping Resolution

// Retrieve shadow mappings for a specific table
// Configuration: t_order -> logicDataSource "shadow_ds"
//   shadow_ds -> production="ds_prod", shadow="ds_shadow"
Map<String, String> mappings = shadowRule.getShadowDataSourceMappings("t_order");
// Result: {"ds_prod" -> "ds_shadow"}

Global Mapping Resolution

// Retrieve all shadow data source mappings (used for default algorithm matches)
Map<String, String> allMappings = shadowRule.getAllShadowDataSourceMappings();
// Result: {"ds_prod_1" -> "ds_shadow_1", "ds_prod_2" -> "ds_shadow_2", ...}

Production Data Source Identification

// Check if a data source is a known production data source
Optional<String> productionName = shadowRule.findProductionDataSourceName("shadow_ds");
// Result: Optional.of("ds_prod") if shadow_ds is a configured logical data source
// Result: Optional.empty() if shadow_ds is not recognized

// Used in ShadowSQLRouter.decorateRouteContext:
for (RouteUnit each : routeContext.getRouteUnits()) {
    String actualName = each.getDataSourceMapper().getActualName();
    Optional<String> prodName = rule.findProductionDataSourceName(actualName);
    if (prodName.isPresent()) {
        // This route unit targets a shadow-configured production data source
        // Look up shadow mapping and potentially redirect
    }
}

Related Pages

Implements Principle

• Principle:Apache_Shardingsphere_Data_Source_Mapping_Resolution