Implementation:Apache Shardingsphere ShadowSQLRouter DecorateRouteContext
| Knowledge Sources | |
|---|---|
| Domains | Database_Routing, Shadow_Testing |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
Concrete tool for intercepting and decorating an existing route context with shadow data source redirections, provided by the ShardingSphere shadow module.
Description
ShadowSQLRouter is a final class implementing the DecorateSQLRouter<ShadowRule> interface. It is annotated with @HighFrequencyInvocation, indicating that it lies on the critical execution path for every SQL statement processed by the shadow feature. The decorateRouteContext method is the sole routing entry point: it receives an already-populated RouteContext (from prior routing stages such as sharding), resolves shadow data source mappings via ShadowDataSourceMappingsRetrieverFactory, and then iterates over each RouteUnit to replace production data source references with their shadow counterparts when a mapping is found.
The method builds two separate collections (toBeRemovedRouteUnit and toBeAddedRouteUnit) to avoid modifying the route units collection during iteration. For each route unit, it looks up the actual data source name against the shadow rule to find the corresponding production name. If a production name is found and a shadow mapping exists for it, the route unit is rewritten to point to the shadow data source. If the shadow mapping returns null (no shadow match), the route unit is rewritten to point to the production data source. Route units whose actual data source does not correspond to any known production data source are left unchanged.
The method returns Type.DATA_SOURCE from getType(), signifying that it operates at the data source routing level. Its execution order is governed by ShadowOrder.ORDER.
Usage
This method is invoked automatically by the ShardingSphere routing engine when a ShadowRule is configured in the database. It requires no direct invocation by application code. It activates whenever:
- The ShardingSphere configuration includes shadow data source mappings
- A SQL statement is being routed through the kernel routing pipeline
- The shadow feature module is present on the classpath
Code Reference
Source Location
- Repository: Apache ShardingSphere
- File: features/shadow/core/src/main/java/org/apache/shardingsphere/shadow/route/ShadowSQLRouter.java
- Lines: 43-62
Signature
@Override
public void decorateRouteContext(final RouteContext routeContext, final QueryContext queryContext, final ShardingSphereDatabase database,
final ShadowRule rule, final Collection<String> tableNames, final ConfigurationProperties props)
Import
import org.apache.shardingsphere.shadow.route.ShadowSQLRouter;
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| routeContext | RouteContext | Yes | The mutable route context produced by prior routing stages; modified in place to reflect shadow data source decisions |
| queryContext | QueryContext | Yes | Contains the parsed SQL statement context and hint value context used to determine shadow data source mappings |
| database | ShardingSphereDatabase | Yes | The metadata for the current ShardingSphere database (not directly used in this method but required by the interface) |
| rule | ShadowRule | Yes | The shadow rule containing data source mappings, table rules, and shadow algorithm configurations |
| tableNames | Collection<String> | Yes | The collection of table names involved in the current SQL statement (not directly used in this method but required by the interface) |
| props | ConfigurationProperties | Yes | Global configuration properties (not directly used in this method but required by the interface) |
Outputs
| Name | Type | Description |
|---|---|---|
| (void) | void | The method modifies routeContext in place: route units referencing production data sources are replaced with units pointing to either the corresponding shadow data source or the production data source, depending on whether a shadow mapping was resolved |
Usage Examples
Basic Usage
// ShadowSQLRouter is invoked automatically by the ShardingSphere routing engine.
// The following illustrates the conceptual flow within the routing pipeline:
// 1. Prior routing stages populate the RouteContext
RouteContext routeContext = new RouteContext();
routeContext.getRouteUnits().add(new RouteUnit(
new RouteMapper("ds", "ds_prod"), tableMappers));
// 2. The shadow router decorates the route context
ShadowSQLRouter shadowRouter = new ShadowSQLRouter();
shadowRouter.decorateRouteContext(routeContext, queryContext, database, shadowRule, tableNames, props);
// 3. After decoration, route units now point to shadow data sources
// where applicable, e.g., "ds_prod" may become "ds_shadow"
for (RouteUnit unit : routeContext.getRouteUnits()) {
System.out.println(unit.getDataSourceMapper().getActualName());
// Output: "ds_shadow" if shadow mapping was matched, or "ds_prod" if not
}