Implementation:Apache Shardingsphere PushDownMetaDataRefresher SPI

Knowledge Sources	Apache ShardingSphere
Domains	Metadata_Management, DDL_Processing
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete SPI interface definition for type-specific DDL metadata refreshers, provided by the ShardingSphere mode-core module.

Description

PushDownMetaDataRefresher<T extends SQLStatement> is a singleton SPI interface that defines the contract for all type-specific metadata refreshers in the push-down refresh pipeline. Each implementation handles a specific DDL statement class (e.g., CreateTableStatement, AlterTableStatement, DropTableStatement) and is responsible for reloading the affected metadata from the actual database and persisting the changes.

The interface extends TypedSPI, which provides the getType() method used by TypedSPILoader to map SQL statement classes to their corresponding refresher implementations. The @SingletonSPI annotation ensures that each implementation is instantiated once and cached for reuse.

Concrete implementations registered via Java SPI include:

• CreateTablePushDownMetaDataRefresher (handles CreateTableStatement)
• AlterTablePushDownMetaDataRefresher (handles AlterTableStatement)
• DropTablePushDownMetaDataRefresher (handles DropTableStatement)
• Additional refreshers for views, indexes, schemas, and rename operations

Usage

Use this interface when implementing a new DDL metadata refresher. Implement the refresh() method with the specific reload logic for the DDL type, implement getType() to return the SQL statement class, and register the implementation in the SPI service file.

Code Reference

Source Location

• Repository: Apache ShardingSphere
• File: mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/refresher/pushdown/PushDownMetaDataRefresher.java
• Lines: 36-55

Signature

@SingletonSPI
public interface PushDownMetaDataRefresher<T extends SQLStatement> extends TypedSPI {

    void refresh(MetaDataManagerPersistService metaDataManagerPersistService,
                 ShardingSphereDatabase database,
                 String logicDataSourceName,
                 String schemaName,
                 DatabaseType databaseType,
                 T sqlStatement,
                 ConfigurationProperties props) throws SQLException;

    @Override
    Class<T> getType();
}

SPI Loader Call

// How the engine loads a refresher for a given SQL statement class
Optional<PushDownMetaDataRefresher> refresher =
    TypedSPILoader.findService(PushDownMetaDataRefresher.class,
                               sqlStatementContext.getSqlStatement().getClass());

Import

import org.apache.shardingsphere.mode.metadata.refresher.pushdown.PushDownMetaDataRefresher;
import org.apache.shardingsphere.infra.spi.type.typed.TypedSPILoader;

I/O Contract

Inputs (refresh)

Name	Type	Required	Description
metaDataManagerPersistService	MetaDataManagerPersistService	Yes	Service for persisting metadata changes (create, alter, drop tables/views)
database	ShardingSphereDatabase	Yes	The ShardingSphere database containing resource metadata and rules
logicDataSourceName	String	Yes	The logical data source name from the route unit, used for single table registration
schemaName	String	Yes	The target schema name where metadata changes occur
databaseType	DatabaseType	Yes	The actual database type (MySQL, PostgreSQL, Oracle, etc.) for identifier formatting
sqlStatement	T (extends SQLStatement)	Yes	The parsed DDL statement containing table/view/index names and operation details
props	ConfigurationProperties	Yes	System configuration properties passed to the schema builder

Outputs (refresh)

Name	Type	Description
return	void	No return value; metadata is refreshed and persisted as a side effect
exception	SQLException	Thrown if metadata cannot be loaded from the actual database

Outputs (getType)

Name	Type	Description
return	Class<T>	The SQL statement class this refresher handles (e.g., CreateTableStatement.class)

Usage Examples

// Implementing a custom DDL refresher
public final class CreateTablePushDownMetaDataRefresher
        implements PushDownMetaDataRefresher<CreateTableStatement> {

    @Override
    public void refresh(final MetaDataManagerPersistService metaDataManagerPersistService,
                        final ShardingSphereDatabase database,
                        final String logicDataSourceName,
                        final String schemaName,
                        final DatabaseType databaseType,
                        final CreateTableStatement sqlStatement,
                        final ConfigurationProperties props) throws SQLException {
        String tableName = TableRefreshUtils.getTableName(
            sqlStatement.getTable().getTableName().getIdentifier(), databaseType);
        // ... reload table from database and persist
        metaDataManagerPersistService.createTable(database, schemaName, loadedTable);
    }

    @Override
    public Class<CreateTableStatement> getType() {
        return CreateTableStatement.class;
    }
}

Related Pages

Implements Principle

• Principle:Apache_Shardingsphere_SPI_Refresher_Loading

Uses Heuristic

• Heuristic:Apache_Shardingsphere_DDL_Refresher_Superclass_Fallback