Implementation:Apache Shardingsphere DatabaseMetaDataPersistFacade Persist

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

Overview

Concrete tool for persisting refreshed metadata to the cluster repository with version tracking and differential updates, provided by the ShardingSphere mode-core module.

Description

DatabaseMetaDataPersistFacade is a facade class that coordinates metadata persistence across four sub-services:

• DatabaseMetaDataPersistService (database field): Handles database-level metadata operations.
• SchemaMetaDataPersistService (schema field): Handles schema creation, deletion, and delegates to table/view services.
• TableMetaDataPersistService (table field): Handles table metadata persistence with version tracking. In cluster mode, uses TableMetaDataPersistEnabledService (versioned); in standalone mode, uses TableMetaDataPersistDisabledService.
• ViewMetaDataPersistService (view field): Handles view metadata persistence.

The facade is constructed with a PersistRepository and a VersionPersistService. The persistSchemasEnabled flag controls whether versioned or unversioned table persistence is used. This flag is typically true in cluster mode and false in standalone mode.

Key methods:

• persistReloadDatabase(): Compares a reloaded database against the current state using GenericSchemaManager to compute differential additions and removals, then persists only the changes.
• persistAlteredTables(): Rebuilds specific tables from the database via GenericSchemaBuilder and persists added/changed tables.
• renameSchema(): Persists all tables and views under a new schema name and drops the old schema.
• unregisterStorageUnits(): After storage unit removal, drops tables that no longer exist in the rebuilt schema.
• persistCreatedDatabaseSchemas(): Persists all schemas of a newly created database.

Usage

This facade is used by the MetaDataManagerPersistService implementations and the mode manager to persist metadata changes after DDL operations, storage unit changes, or database lifecycle events.

Code Reference

Source Location

• Repository: Apache ShardingSphere
• File: mode/core/src/main/java/org/apache/shardingsphere/mode/metadata/persist/metadata/DatabaseMetaDataPersistFacade.java
• Lines: 50-167

Signature

@Getter
public final class DatabaseMetaDataPersistFacade {

    private final DatabaseMetaDataPersistService database;
    private final SchemaMetaDataPersistService schema;
    private final TableMetaDataPersistService table;
    private final ViewMetaDataPersistService view;

    public DatabaseMetaDataPersistFacade(final PersistRepository repository,
                                         final VersionPersistService versionPersistService,
                                         final boolean persistSchemasEnabled)

    public void persistReloadDatabase(final String databaseName,
                                      final ShardingSphereDatabase reloadDatabase,
                                      final ShardingSphereDatabase currentDatabase)

    public void renameSchema(final ShardingSphereMetaData metaData,
                             final ShardingSphereDatabase database,
                             final String schemaName,
                             final String renameSchemaName)

    public void unregisterStorageUnits(final String databaseName,
                                       final MetaDataContexts reloadMetaDataContexts)

    public Map<String, Collection<ShardingSphereTable>> persistAlteredTables(
        final String databaseName,
        final MetaDataContexts reloadMetaDataContexts,
        final Collection<String> needReloadTables)

    public void persistCreatedDatabaseSchemas(final ShardingSphereDatabase database)
}

Import

import org.apache.shardingsphere.mode.metadata.persist.metadata.DatabaseMetaDataPersistFacade;

I/O Contract

Inputs (Constructor)

Name	Type	Required	Description
repository	PersistRepository	Yes	The governance repository (ZooKeeper, etcd, etc.) for storing metadata
versionPersistService	VersionPersistService	Yes	Service for managing metadata version tracking
persistSchemasEnabled	boolean	Yes	Whether versioned persistence is enabled (true in cluster mode)

Inputs (persistReloadDatabase)

Name	Type	Required	Description
databaseName	String	Yes	Name of the database being reloaded
reloadDatabase	ShardingSphereDatabase	Yes	The freshly reloaded database containing updated schemas
currentDatabase	ShardingSphereDatabase	Yes	The current in-memory database to compare against

Outputs (persistReloadDatabase)

Name	Type	Description
return	void	No return value; differential changes are persisted to the repository

Inputs (persistAlteredTables)

Name	Type	Required	Description
databaseName	String	Yes	Name of the database containing altered tables
reloadMetaDataContexts	MetaDataContexts	Yes	Reloaded metadata contexts with updated database state
needReloadTables	Collection<String>	Yes	Names of tables that need to be reloaded from the database

Outputs (persistAlteredTables)

Name	Type	Description
return	Map<String, Collection<ShardingSphereTable>>	Map of schema names to their altered tables
exception	LoadTableMetaDataFailedException	Thrown if table metadata cannot be loaded from the database

Usage Examples

// Construct the facade (typically done during mode initialization)
DatabaseMetaDataPersistFacade facade = new DatabaseMetaDataPersistFacade(
    repository, versionPersistService, true);

// After reloading a database, persist only the differential changes
facade.persistReloadDatabase("my_db", reloadedDatabase, currentDatabase);

// Persist altered tables after storage unit registration
Map<String, Collection<ShardingSphereTable>> alteredTables =
    facade.persistAlteredTables("my_db", reloadMetaDataContexts,
        Arrays.asList("orders", "customers"));

// Rename a schema (copies all tables/views to new name, drops old)
facade.renameSchema(metaData, database, "old_schema", "new_schema");

Related Pages

Implements Principle

• Principle:Apache_Shardingsphere_Metadata_Repository_Persistence