RecoveryManager Class

Package:

com.microsoft.azure.elasticdb.shard.recovery

• java.lang.Object
• • com.microsoft.azure.elasticdb.shard.recovery.RecoveryManager

public class RecoveryManager

Manages various recovery related tasks for a shard map manager. It helps resolving data corruption issues between shard map information stored locally on the shards and in the global shard map manager database. It also helps with certain 'oops' recovery scenarios where reconstruction of shard maps from database backups or database copies is necessary. Note that some of the recovery methods can cause unrecoverable data loss when not used properly. It is recommend to take backups or copies of all databases that participate in recovery operations.

Constructor Summary

Constructor	Description
RecoveryManager(ShardMapManager shardMapManager)	Constructs an instance of the recovery manager for given shard map manager.

Method Summary

Modifier and Type	Method and Description
void	attachShard(ShardLocation location) Attaches a shard to the shard map manager. Earlier versions of mappings for the same shard map will automatically be updated if more recent versions are found on the shard to be attached. After attaching a shard, DetectMappingDifferences(ShardLocation, string) should be called to check for any inconsistencies that warrant manual conflict resolution.
void	attachShard(ShardLocation location, String shardMapName) Attaches a shard to the shard map manager. Earlier versions of mappings for the same shard map will automatically be updated if more recent versions are found on the shard to be attached. Shard location will be upgraded to latest version of local store as part of this operation. After attaching a shard, DetectMappingDifferences(ShardLocation, string) should be called to check for any inconsistencies that warrant manual conflict resolution.
void	detachShard(ShardLocation location) Detaches the given shard from the shard map manager. Mappings pointing to the shard to be deleted will automatically be removed by this method.
void	detachShard(ShardLocation location, String shardMapName) Detaches the given shard from the shard map manager. Mappings pointing to the shard to be deleted will automatically be removed by this method.
List<RecoveryToken>	detectMappingDifferences(ShardLocation location) Enumerates differences in the mappings between the global shard map manager database and the local shard database in the specified shard location.
List<RecoveryToken>	detectMappingDifferences(ShardLocation location, String shardMapName) Enumerates differences in the mappings between the global shard map manager database and the local shard database in the specified shard location.
Map<ShardRange, MappingLocation>	getMappingDifferences(RecoveryToken token) Returns a dictionary of range-to-location key-value pairs. The location returned is an enumerator stating whether a given range (or point) is present only in the local shard map, only in the global shard map, or both. Ranges not contained in either shard map cannot contain differences so those ranges are not shown.
void	getShardInfo(RecoveryToken token, ReferenceObjectHelper<ShardMapType> mapType, ReferenceObjectHelper<String> shardMapName) Retrieves shard map type and name based on the token returned from DetectMappingDifferences(ShardLocation, string).
void	getShardInfo(RecoveryToken token, ReferenceObjectHelper<ShardMapType> mapType, ReferenceObjectHelper<String> shardMapName, ReferenceObjectHelper<ShardLocation> shardLocation) Retrieves shard map type, name and shard location based on the token returned from DetectMappingDifferences(ShardLocation, string).
ShardLocation	getShardLocation(RecoveryToken token) Returns the shard location of the local shard map processed by DetectMappingDifferences(ShardLocation, string).
String	getShardMapName(RecoveryToken token) Returns the shard map name of the shard map processed by DetectMappingDifferences(ShardLocation, string).
ShardMapType	getShardMapType(RecoveryToken token) Returns the shard map type of the shard map processed by DetectMappingDifferences(ShardLocation, string).
void	rebuildMappingsOnShard(RecoveryToken token, List<ShardRange> ranges) Rebuilds a local range shard map from a list of inconsistent shard ranges detected by DetectMappingDifferences(ShardLocation, string) and then accessed by GetMappingDifferences. The resulting local range shard map will always still be inconsistent with the global shard map in the shard map manager database. A subsequent call to ResolveMappingDifferences is necessary to bring the system back to a healthy state.
void	rebuildMappingsOnShardMapManagerFromShards(List<ShardLocation> shardLocations) Given a collection of shard locations, reconstructs the shard map manager based on mapping information stored in the individual shards. The specified shards need to be registered already in the global shard map. This method only rebuilds mappings. It does not rebuild shard membership within the global shard map. If the information in the individual shard maps is or becomes inconsistent, the behavior is undefined. No cross shard locks are taken, so if any shards become inconsistent during the execution of this method, the final state of the global shard map may be corrupt.
void	rebuildMappingsOnShardMapManagerFromShards(List<ShardLocation> shardLocations, String shardMapName) Given a collection of shard locations, reconstructs the shard map manager based on mapping information stored in the individual shards. The specified shards need to be registered already in the global shard map. This method only rebuilds mappings. It does not rebuild shard membership within the global shard map. If the information in the individual shard maps is or becomes inconsistent, the behavior is undefined. No cross shard locks are taken, so if any shards become inconsistent during the execution of this method, the final state of the global shard map may be corrupt.
void	rebuildMappingsOnShardsFromShardMapManager(List<ShardLocation> shardLocations) Given a collection of shard locations, reconstructs local shard maps based on the mapping information stored in the global shard map. The specified shards need to be registered already in the global shard map. This method only rebuilds mappings. It does not rebuild shard membership within the global shard map.
void	rebuildMappingsOnShardsFromShardMapManager(List<ShardLocation> shardLocations, String shardMapName) Given a collection of shard locations, reconstructs local shard maps based on the mapping information stored in the global shard map. The specified shards need to be registered already in the global shard map. This method only rebuilds mappings. It does not rebuild shard membership within the global shard map.
void	resolveMappingDifferences(RecoveryToken token, MappingDifferenceResolution resolution) Selects one of the shard maps (either local or global) as a source of truth and brings mappings on both shard maps in sync.

Constructor Details

RecoveryManager

public RecoveryManager(ShardMapManager shardMapManager)

Constructs an instance of the recovery manager for given shard map manager.

Parameters:

shardMapManager - Shard map manager being recovered.

Method Details

attachShard

public void attachShard(ShardLocation location)

Attaches a shard to the shard map manager. Earlier versions of mappings for the same shard map will automatically be updated if more recent versions are found on the shard to be attached. After attaching a shard, DetectMappingDifferences(ShardLocation, string) should be called to check for any inconsistencies that warrant manual conflict resolution.

Parameters:

location - Location of the shard being attached. Note that this method can cause unrecoverable data loss. Make sure you have taken backups or copies of your databases and only then proceed with great care.

attachShard

public void attachShard(ShardLocation location, String shardMapName)

Attaches a shard to the shard map manager. Earlier versions of mappings for the same shard map will automatically be updated if more recent versions are found on the shard to be attached. Shard location will be upgraded to latest version of local store as part of this operation. After attaching a shard, DetectMappingDifferences(ShardLocation, string) should be called to check for any inconsistencies that warrant manual conflict resolution.

Parameters:

location - Location of the shard being attached.

shardMapName - Optional string to filter on the shard map name. Note that this method can cause unrecoverable data loss. Make sure you have taken backups or copies of your databases and only then proceed with great care.

detachShard

public void detachShard(ShardLocation location)

Detaches the given shard from the shard map manager. Mappings pointing to the shard to be deleted will automatically be removed by this method.

Parameters:

location - Location of the shard being detached. Note that this method can cause unrecoverable data loss. Make sure you have taken backups or copies of your databases and only then proceed with great care.

detachShard

public void detachShard(ShardLocation location, String shardMapName)

Detaches the given shard from the shard map manager. Mappings pointing to the shard to be deleted will automatically be removed by this method.

Parameters:

location - Location of the shard being detached.

shardMapName - Optional string to filter on shard map name. Note that this method can cause unrecoverable data loss. Make sure you have taken backups or copies of your databases and only then proceed with great care.

detectMappingDifferences

public List detectMappingDifferences(ShardLocation location)

Enumerates differences in the mappings between the global shard map manager database and the local shard database in the specified shard location.

Parameters:

location - Location of shard for which to detect inconsistencies.

Returns:

Collection of tokens to be used for further resolution tasks (see ResolveMappingDifferences).

detectMappingDifferences

public List detectMappingDifferences(ShardLocation location, String shardMapName)

Enumerates differences in the mappings between the global shard map manager database and the local shard database in the specified shard location.

Parameters:

location - Location of shard for which to detect inconsistencies.

shardMapName - Optional parameter to specify a particular shard map.

Returns:

Collection of tokens to be used for further resolution tasks (see ResolveMappingDifferences).

getMappingDifferences

public Map getMappingDifferences(RecoveryToken token)

Returns a dictionary of range-to-location key-value pairs. The location returned is an enumerator stating whether a given range (or point) is present only in the local shard map, only in the global shard map, or both. Ranges not contained in either shard map cannot contain differences so those ranges are not shown.

Parameters:

token - Recovery token returned from DetectMappingDifferences(ShardLocation, string).

Returns:

The set of ranges and their corresponding MappingLocation. This method assumes a previous call to DetectMappingDifferences(ShardLocation, string) that provides the recovery token parameter. The result of this method is typically used in subsequent calls to resolve inconsistencies such as ResolveMappingDifferences or RebuildMappingsOnShard.

getShardInfo

public void getShardInfo(RecoveryToken token, ReferenceObjectHelper mapType, ReferenceObjectHelper shardMapName)

Retrieves shard map type and name based on the token returned from DetectMappingDifferences(ShardLocation, string).

Parameters:

token - Recovery token returned from DetectMappingDifferences(ShardLocation, string).

mapType - Output ShardMap type (Range or List).

shardMapName - Output name of shard map.

getShardInfo

public void getShardInfo(RecoveryToken token, ReferenceObjectHelper mapType, ReferenceObjectHelper shardMapName, ReferenceObjectHelper shardLocation)

Retrieves shard map type, name and shard location based on the token returned from DetectMappingDifferences(ShardLocation, string).

Parameters:

token - Recovery token returned from DetectMappingDifferences(ShardLocation, string).

mapType - Outputs shard map type (Range or List).

shardMapName - Outputs shard map name.

shardLocation - Outputs shard location

getShardLocation

public ShardLocation getShardLocation(RecoveryToken token)

Returns the shard location of the local shard map processed by DetectMappingDifferences(ShardLocation, string).

Parameters:

token - Recovery token returned from DetectMappingDifferences(ShardLocation, string)

Returns:

Location of the shard corresponding to the set of mapping differences detected in DetectMappingDifferences(ShardLocation, string).

getShardMapName

public String getShardMapName(RecoveryToken token)

Returns the shard map name of the shard map processed by DetectMappingDifferences(ShardLocation, string).

Parameters:

token - Recovery token returned from DetectMappingDifferences(ShardLocation, string).

Returns:

The name of the shard map for the given recovery token.

getShardMapType

public ShardMapType getShardMapType(RecoveryToken token)

Returns the shard map type of the shard map processed by DetectMappingDifferences(ShardLocation, string).

Parameters:

token - Recovery token returned from DetectMappingDifferences(ShardLocation, string).

Returns:

The type of shard map (list, range, etc...) corresponding to the recovery token.

rebuildMappingsOnShard

public void rebuildMappingsOnShard(RecoveryToken token, List ranges)

Rebuilds a local range shard map from a list of inconsistent shard ranges detected by DetectMappingDifferences(ShardLocation, string) and then accessed by GetMappingDifferences. The resulting local range shard map will always still be inconsistent with the global shard map in the shard map manager database. A subsequent call to ResolveMappingDifferences is necessary to bring the system back to a healthy state.

Parameters:

token - The recovery token from a previous call to DetectMappingDifferences

ranges - The set of ranges to keep on the local shard when rebuilding the local shard map. Note that this method can cause unrecoverable data loss. Make sure you have taken backups or copies of your databases and only then proceed with great care. Only shard ranges with inconsistencies can be rebuilt using this method. All ranges with no inconsistencies between the local shard and the global shard map will be kept intact on the local shard and are not affected by this call. Subsequent changes to the non-conflicting mappings can be made later using the regular interfaces in the shard map manager. It is not necessary to use the recovery manager to change non-conflicting mappings.

rebuildMappingsOnShardMapManagerFromShards

public void rebuildMappingsOnShardMapManagerFromShards(List shardLocations)

Given a collection of shard locations, reconstructs the shard map manager based on mapping information stored in the individual shards. The specified shards need to be registered already in the global shard map. This method only rebuilds mappings. It does not rebuild shard membership within the global shard map. If the information in the individual shard maps is or becomes inconsistent, the behavior is undefined. No cross shard locks are taken, so if any shards become inconsistent during the execution of this method, the final state of the global shard map may be corrupt.

Parameters:

shardLocations - Collection of shard locations. Note that this method can cause unrecoverable data loss. Make sure you have taken backups or copies of your databases and only then proceed with great care.

rebuildMappingsOnShardMapManagerFromShards

public void rebuildMappingsOnShardMapManagerFromShards(List shardLocations, String shardMapName)

Given a collection of shard locations, reconstructs the shard map manager based on mapping information stored in the individual shards. The specified shards need to be registered already in the global shard map. This method only rebuilds mappings. It does not rebuild shard membership within the global shard map. If the information in the individual shard maps is or becomes inconsistent, the behavior is undefined. No cross shard locks are taken, so if any shards become inconsistent during the execution of this method, the final state of the global shard map may be corrupt.

Parameters:

shardLocations - Collection of shard locations.

shardMapName - Optional name of shard map. If omitted, will attempt to recover from all shard maps present on each shard. Note that this method can cause unrecoverable data loss. Make sure you have taken backups or copies of your databases and only then proceed with great care.

rebuildMappingsOnShardsFromShardMapManager

public void rebuildMappingsOnShardsFromShardMapManager(List shardLocations)

Given a collection of shard locations, reconstructs local shard maps based on the mapping information stored in the global shard map. The specified shards need to be registered already in the global shard map. This method only rebuilds mappings. It does not rebuild shard membership within the global shard map.

Parameters:

shardLocations - Collection of shard locations. Note that this method can cause unrecoverable data loss. Make sure you have taken backups or copies of your databases and only then proceed with great care.

rebuildMappingsOnShardsFromShardMapManager

public void rebuildMappingsOnShardsFromShardMapManager(List shardLocations, String shardMapName)

Given a collection of shard locations, reconstructs local shard maps based on the mapping information stored in the global shard map. The specified shards need to be registered already in the global shard map. This method only rebuilds mappings. It does not rebuild shard membership within the global shard map.

Parameters:

shardLocations - Collection of shard locations.

shardMapName - Optional parameter to filter by shard map name. If omitted, all shard maps will be rebuilt. Note that this method can cause unrecoverable data loss. Make sure you have taken backups or copies of your databases and only then proceed with great care.

resolveMappingDifferences

public void resolveMappingDifferences(RecoveryToken token, MappingDifferenceResolution resolution)

Selects one of the shard maps (either local or global) as a source of truth and brings mappings on both shard maps in sync.

Parameters:

token - Recovery token returned from DetectMappingDifferences(ShardLocation, string).

resolution - The resolution strategy to be used for resolution. Note that this method can cause unrecoverable data loss. Make sure you have taken backups or copies of your databases and only then proceed with great care.