Principle:Apache Shardingsphere MetaData Context Creation
| Knowledge Sources | |
|---|---|
| Domains | Cluster_Mode, Distributed_Coordination |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
Creating the runtime metadata context by loading or initializing database metadata, rules, and configuration establishes the complete in-memory representation that drives all query routing and execution decisions.
Description
MetaData Context Creation is the principle of assembling a MetaDataContexts object that contains everything ShardingSphere needs to process SQL at runtime: database metadata (schemas, tables, columns), rule configurations (sharding, encryption, read-write splitting), data source configurations, global rules, and system properties.
The creation logic follows a "register center first" strategy: if databases have already been registered in the distributed coordination repository, the factory loads metadata from the repository. If the repository is empty (first-time bootstrap), the factory initializes metadata from the local configuration provided by the bootstrap parameter.
This dual-path strategy enables:
- Cluster Consistency: When a new node joins an existing cluster, it loads the already-persisted metadata from the register center rather than using its own potentially stale local configuration.
- First-Time Bootstrap: When the cluster is being initialized for the first time, the factory uses the local configuration to create metadata, which is then persisted to the register center for future nodes.
- Runtime Rebuilding: The factory also supports creating metadata contexts from altered rules or switched resources, enabling dynamic reconfiguration without restart.
The MetaDataContexts object produced by the factory contains:
| Component | Description |
|---|---|
| ShardingSphereMetaData | Collection of all database metadata, global resource metadata, global rule metadata, and configuration properties |
| ShardingSphereStatistics | Cluster-wide statistics data loaded from the persistence layer |
Usage
Use this principle during cluster-mode initialization (within ClusterContextManagerBuilder.build()) and during dynamic reconfiguration scenarios (rule changes, data source switches). The MetaDataContextsFactory is constructed with a MetaDataPersistFacade and ComputeNodeInstanceContext, then its create() method is called with the bootstrap parameter.
Theoretical Basis
The MetaData Context Creation principle implements a strategy-based factory pattern with persistence-aware branching:
1. Register Center Detection
The factory checks whether any databases have been previously registered in the repository:
FUNCTION create(param):
IF containsRegisteredDatabases(repository):
initFactory = new RegisterCenterMetaDataContextsInitFactory(repository, instanceContext)
ELSE:
initFactory = new LocalConfigurationMetaDataContextsInitFactory(repository, instanceContext, param.props)
RETURN initFactory.create(param)
This decision point is critical: it determines whether the node trusts the register center's state (joining an existing cluster) or bootstraps from its own configuration (starting a fresh cluster).
2. Strategy Pattern for Initialization
Two concrete strategies implement the MetaDataContextsInitFactory interface:
- RegisterCenterMetaDataContextsInitFactory -- loads all database names, data source configurations, rule configurations, and schema metadata from the repository
- LocalConfigurationMetaDataContextsInitFactory -- uses the configurations provided in the bootstrap parameter, then persists them to the repository for future nodes
3. Immutable Context Assembly
Once created, the MetaDataContexts object is treated as effectively immutable. When reconfiguration is needed (rule changes, data source switches), a new MetaDataContexts is created and atomically replaces the old one rather than mutating it in place.
4. Dynamic Reconfiguration Support
The factory provides additional methods for creating metadata contexts from altered rules or switched resources:
FUNCTION createBySwitchResource(databaseName, isLoadFromRegCenter, switchingResource, originalContexts):
changedDatabase = createChangedDatabase(databaseName, isLoadFromRegCenter, switchingResource, originalContexts)
newMetaData = cloneMetaDataWithChangedDatabase(originalContexts.metaData, changedDatabase)
rebuildGlobalRules(newMetaData)
RETURN new MetaDataContexts(newMetaData, statistics)
FUNCTION createByAlterRule(databaseName, isLoadFromRegCenter, ruleConfigs, originalContexts):
changedDatabase = createChangedDatabase(databaseName, isLoadFromRegCenter, ruleConfigs, originalContexts)
newMetaData = cloneMetaDataWithChangedDatabase(originalContexts.metaData, changedDatabase)
rebuildGlobalRules(newMetaData)
RETURN new MetaDataContexts(newMetaData, statistics)
5. Schema Loading Strategy
When loading from the register center, the factory respects the persistSchemasEnabled configuration property. If schema persistence is disabled, it merges persisted schema structure with in-memory table metadata from the original context.