Heuristic:Apache Shardingsphere DDL Refresher Superclass Fallback

Knowledge Sources	Apache ShardingSphere PushDown MetaData Refresh Engine
Domains	Metadata_Management, SPI_Design
Last Updated	2026-02-10 02:00 GMT

Overview

SPI refresher lookup strategy that tries the exact vendor-specific SQL statement class first, then falls back to the generic superclass for DDL metadata refresh.

Description

When a DDL statement is executed and ShardingSphere needs to refresh its metadata, the `PushDownMetaDataRefreshEngine` uses a two-level SPI lookup to find the appropriate refresher. It first searches for a refresher registered against the exact SQL statement class (e.g., `MySQLAlterTableStatement`). If no exact match is found, it falls back to searching against the statement's superclass (e.g., `AlterTableStatement`). This allows the system to handle vendor-specific DDL without requiring a refresher for every database dialect.

Usage

Apply this heuristic when:

Adding a new DDL refresher: Register the refresher SPI against the generic statement superclass to cover all database dialects. Only register against a specific subclass if vendor-specific handling is needed.
Debugging metadata refresh failures: If metadata is not refreshed after a DDL statement, check whether the statement class hierarchy has a registered refresher at either the exact or superclass level.
Extending database support: New database dialects automatically get DDL refresh support for standard statements through the superclass fallback.

The Insight (Rule of Thumb)

Action: When implementing DDL metadata refreshers, register against the generic SQL statement superclass (e.g., `CreateTableStatement`) rather than each vendor-specific subclass (e.g., `MySQLCreateTableStatement`, `PostgreSQLCreateTableStatement`).
Value: One refresher implementation covers all supported database dialects.
Trade-off: If a vendor-specific DDL statement has unique metadata behavior, a subclass-specific refresher must be registered to override the superclass behavior.
Scope: Only applies to the 13 supported DDL statement types: CREATE/ALTER/DROP for TABLE, VIEW, INDEX, SCHEMA, plus RENAME TABLE.

Reasoning

ShardingSphere supports multiple database dialects (MySQL, PostgreSQL, Oracle, SQL Server, etc.), each with their own AST class hierarchy. Each dialect's DDL statement class extends a generic base class. For example:

`MySQLCreateTableStatement` extends `CreateTableStatement`
`PostgreSQLAlterTableStatement` extends `AlterTableStatement`

The refresher SPI registrations typically use the generic base class as the key. The superclass fallback ensures that dialect-specific subclasses are automatically handled without requiring N refresher registrations for N supported dialects.

The 13 supported DDL types are maintained in a static set for fast O(1) lookup before attempting the SPI search.

Code evidence from `PushDownMetaDataRefreshEngine.java:99-102`:

@SuppressWarnings("rawtypes")
private Optional<PushDownMetaDataRefresher> findPushDownMetaDataRefresher(
        final SQLStatementContext sqlStatementContext) {
    Optional<PushDownMetaDataRefresher> refresher = TypedSPILoader.findService(
        PushDownMetaDataRefresher.class,
        sqlStatementContext.getSqlStatement().getClass());
    return refresher.isPresent()
        ? refresher
        : TypedSPILoader.findService(
            PushDownMetaDataRefresher.class,
            sqlStatementContext.getSqlStatement().getClass().getSuperclass());
}

Supported refresh types from `PushDownMetaDataRefreshEngine.java:58-61`:

private static final Collection<Class<?>> SUPPORTED_REFRESH_TYPES =
    new HashSet<>(Arrays.asList(
        CreateViewStatement.class, AlterViewStatement.class, DropViewStatement.class,
        CreateIndexStatement.class, AlterIndexStatement.class, DropIndexStatement.class,
        CreateSchemaStatement.class, AlterSchemaStatement.class, DropSchemaStatement.class,
        CreateTableStatement.class, AlterTableStatement.class, DropTableStatement.class,
        RenameTableStatement.class));

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment