Principle:Apache Shardingsphere SQL Statement Interception
| Knowledge Sources | |
|---|---|
| Domains | Database_Routing, Shadow_Testing |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
Intercepting SQL statements at the routing layer to redirect them to shadow databases based on shadow rules, enabling safe full-link stress testing against production-mirrored data sources without affecting actual production data.
Description
SQL Statement Interception is a routing-layer principle in which an intermediary component inspects every SQL statement after its initial route has been determined, and conditionally rewrites the target data source from the production database to a corresponding shadow database. The interception occurs as a decoration step in the routing pipeline: the original route context (produced by earlier routing stages such as sharding or read-write splitting) is taken as input, and each route unit within that context is examined. For every route unit whose actual data source maps to a known production data source, the interceptor consults a set of shadow data source mappings to determine whether the statement should be redirected.
The key problem this solves is enabling full-link stress testing (also called shadow traffic testing) in a production environment. Rather than maintaining an entirely separate testing environment, shadow database routing allows test traffic to flow through the same application infrastructure but land on isolated shadow databases. This means that:
- Production data remains untouched during stress tests
- The test exercises the full production code path, including middleware, connection pooling, and routing logic
- Results are written to shadow databases where they can be independently analyzed
- No changes to application SQL or business logic are required
The interception point is specifically at the DecorateSQLRouter interface, which operates after the primary routing decision has been made. This ensures that shadow routing composes cleanly with other routing features (sharding, encryption, read-write splitting) rather than conflicting with them.
Usage
Use SQL Statement Interception when:
- You need to perform full-link stress testing or shadow traffic validation in a live production environment
- You want to validate database schema changes, migration correctness, or data pipeline behavior against real traffic patterns
- You require a non-invasive mechanism to redirect specific SQL statements to alternative data sources without modifying application code
- You are building a routing decoration layer that must compose with other routing rules (sharding, read-write splitting) in a defined order
Theoretical Basis
The interception algorithm follows a decorate-and-replace pattern applied to each route unit in an existing route context:
FUNCTION interceptAndRedirect(routeContext, queryContext, shadowRule):
shadowMappings = resolveShadowDataSourceMappings(queryContext, shadowRule)
toRemove = empty list
toAdd = empty list
FOR EACH routeUnit IN routeContext.routeUnits:
logicName = routeUnit.dataSourceMapper.logicName
actualName = routeUnit.dataSourceMapper.actualName
productionName = shadowRule.findProductionDataSourceName(actualName)
IF productionName is present:
shadowName = shadowMappings.get(productionName)
toRemove.add(routeUnit)
IF shadowName is not null:
targetName = shadowName // redirect to shadow
ELSE:
targetName = productionName // keep on production
toAdd.add(new RouteUnit(logicName -> targetName, routeUnit.tableMappers))
routeContext.routeUnits.removeAll(toRemove)
routeContext.routeUnits.addAll(toAdd)
The critical design decisions in this algorithm are:
- Non-destructive iteration: The algorithm collects additions and removals in separate lists rather than modifying the route unit collection during iteration, avoiding concurrent modification issues.
- Production-first fallback: When no shadow mapping exists for a production data source (the shadow mapping returns null), the route falls back to the production data source rather than failing. This ensures that only explicitly matched traffic is redirected.
- Mapper preservation: Table mappers from the original route unit are carried forward unchanged, since shadow routing only affects data source selection, not table routing.