Principle:Apache Shardingsphere Refresh Need Determination
| Knowledge Sources | |
|---|---|
| Domains | Metadata_Management, DDL_Processing |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
A distributed database middleware must determine whether a given SQL statement warrants a metadata refresh before committing resources to reload schema information from the underlying data sources.
Description
When a DDL statement completes execution against the actual database, the middleware must decide whether the in-memory metadata model has become stale and needs to be refreshed. Not every SQL statement affects schema metadata; only DDL operations such as CREATE TABLE, ALTER TABLE, DROP TABLE, CREATE VIEW, ALTER VIEW, DROP VIEW, CREATE INDEX, ALTER INDEX, DROP INDEX, CREATE SCHEMA, ALTER SCHEMA, DROP SCHEMA, and RENAME TABLE require metadata updates.
The determination is performed by checking whether the runtime SQL statement class falls within a predefined set of supported DDL types. This is a fast, constant-time lookup against a static collection. If the statement type is recognized as metadata-affecting, the engine proceeds with the refresh pipeline. Otherwise, no action is taken and execution returns immediately.
This gate-keeping step prevents unnecessary database introspection after DML statements (INSERT, UPDATE, DELETE, SELECT) and other non-schema-altering operations, thereby preserving system performance.
Usage
Use this principle whenever you need to:
- Decide whether post-execution metadata synchronization is required after a SQL statement completes.
- Guard the metadata refresh pipeline so that only DDL operations trigger schema reloading.
- Extend the set of supported DDL types that trigger metadata refresh by adding new statement classes to the supported types collection.
Theoretical Basis
The determination follows a simple membership-test pattern:
SUPPORTED_TYPES = {CreateTable, AlterTable, DropTable, RenameTable,
CreateView, AlterView, DropView,
CreateIndex, AlterIndex, DropIndex,
CreateSchema, AlterSchema, DropSchema}
function isNeedRefresh(sqlStatementContext):
statementClass = sqlStatementContext.getSqlStatement().getClass()
return statementClass IN SUPPORTED_TYPES
function refresh(sqlStatementContext, database, routeUnits, ...):
if NOT isNeedRefresh(sqlStatementContext):
return // no-op for non-DDL statements
refresher = findRefresherBySPI(statementClass)
if refresher is absent:
return // no registered refresher for this DDL type
schemaName = resolveSchemaName(database, sqlStatementContext)
databaseType = resolveDatabaseType(routeUnits, database)
refresher.refresh(database, schemaName, databaseType, sqlStatement, ...)
The key design decisions are:
- Static type set: The supported DDL types are defined as a static final collection, making the check O(1) via HashSet lookup.
- Two-phase guard: First isNeedRefresh() performs the quick type check; then refresh() performs a secondary check by looking up a type-specific refresher via SPI. This layered approach allows callers to short-circuit early.
- Open for extension: New DDL statement types can be added to the supported set without modifying existing refresh logic.