Principle:Apache Shardingsphere Data Source Mapping Resolution
| Knowledge Sources | |
|---|---|
| Domains | Database_Routing, Shadow_Testing |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
Resolving production-to-shadow data source mappings based on routing decisions, providing the concrete name translations that allow the routing layer to redirect SQL statements from production databases to their corresponding shadow databases.
Description
Data Source Mapping Resolution is the principle of translating logical and physical data source identifiers between production and shadow databases. In the ShardingSphere shadow routing pipeline, all upstream routing decisions (hint-based, column-based, or default) ultimately produce a mapping from production data source names to shadow data source names. This mapping is the final artifact consumed by the route context decorator to rewrite route units.
The resolution operates at three levels of scope:
1. Table-Specific Mappings
When a shadow algorithm matches for a specific table, the resolution returns only the data source mappings associated with that table. Each shadow table is configured with one or more logical data source names, and each logical data source has a ShadowDataSourceRule that pairs a production data source with a shadow data source. The resolution iterates over the table's logical data source names, looks up the corresponding ShadowDataSourceRule, and constructs a map from production name to shadow name.
2. Global (All) Mappings
When a default shadow algorithm matches (typically for non-DML statements or when no specific shadow table matches), the resolution returns all configured shadow data source mappings. This means every production data source is mapped to its shadow counterpart, regardless of table association.
3. Production Data Source Identification
Before any mapping can be applied, the routing layer must first determine whether a given data source name corresponds to a known production data source. This reverse lookup checks whether any ShadowDataSourceRule claims the given name as its production data source. If found, the production name is returned; if not, the data source is not part of the shadow configuration and should not be modified.
The resolution model uses a case-insensitive map for data source rule storage, ensuring that data source names are matched regardless of case sensitivity differences between database systems. The mappings are returned as LinkedHashMap instances to preserve insertion order.
Usage
Use Data Source Mapping Resolution when:
- You need to translate a production data source name to its corresponding shadow data source name
- You need to retrieve all shadow data source mappings for a global routing decision
- You need to determine whether a given data source name is a known production data source in the shadow configuration
- You are implementing the final step of the shadow routing pipeline that consumes algorithm evaluation results and produces concrete data source name rewrites
Theoretical Basis
Table-Specific Mapping Resolution:
FUNCTION getShadowDataSourceMappings(tableName):
result = new ordered map
tableRule = tableRules.get(tableName)
FOR EACH logicDataSourceName IN tableRule.logicDataSourceNames:
dataSourceRule = dataSourceRules.get(logicDataSourceName)
result.put(dataSourceRule.productionDataSource, dataSourceRule.shadowDataSource)
RETURN result
Global Mapping Resolution:
FUNCTION getAllShadowDataSourceMappings():
result = new ordered map
FOR EACH entry IN dataSourceRules:
dataSourceRule = entry.value
result.put(dataSourceRule.productionDataSource, dataSourceRule.shadowDataSource)
RETURN result
Production Data Source Identification:
FUNCTION findProductionDataSourceName(logicDataSourceName):
dataSourceRule = dataSourceRules.get(logicDataSourceName)
IF dataSourceRule is null:
RETURN empty
ELSE:
RETURN optional(dataSourceRule.productionDataSource)
Key properties of the resolution model:
- Indirection through logical names: Shadow tables reference logical data source names, which are then resolved to ShadowDataSourceRule entries containing the actual production and shadow data source names. This indirection allows multiple tables to share the same data source pair.
- Case-insensitive lookup: The dataSourceRules map uses CaseInsensitiveMap, ensuring that data source name lookups are not affected by casing differences between configuration files and actual database names.
- Ordered output: Results are returned as LinkedHashMap instances, preserving a deterministic ordering of data source mappings.
- Null safety: The findProductionDataSourceName method returns Optional.empty() when the given name does not match any known data source rule, allowing callers to safely skip non-shadow data sources.
- Separation of concerns: The ShadowRule class handles only the resolution of data source mappings from its internal rule model. It does not perform any algorithm evaluation; that responsibility belongs to the determiner classes.