MigrationDelegate
public protocol MigrationDelegate: AnyObject
A delegate that can be provided to PersistentContainer
PersistentContainer
or PersistentCloudKitContainer
PersistentCloudKitContainer
to receive events describing the progress of migrations. These events can be used to update a user
interface or for app internal logging.
All methods are called while PersistentContainer.loadPersistentStores(...)
-[PersistentContainer loadPersistentStoresWithCompletionHandler:]
is active.
If any of the NSPersistentStoreDescription
NSPersistentStoreDescription
s have the shouldAddStoreAsynchronously
flag
set to true
then all methods are called on a private background queue. If all of the store
descriptions have the flag set to false
then the methods are called on the same queue on which
PersistentContainer.loadPersistentStores(...)
-[PersistentContainer loadPersistentStoresWithCompletionHandler:]
was called.
The stores in PersistentContainer.persistentStoreDescriptions
are processed sequentially.
Stores that are not migratable (not on disk) are ignored and do not represent in this delegate.
A store that does not require migration (the normal case!) sees the sequence:
- willConsiderStore
- willNotMigrateStore
A store requiring a 2-step migration sees the sequence:
- willConsiderStore
- willMigrateStore - totalSteps=2
- willSingleMigrateStore - stepsRemaining=2
- willSingleMigrateStore - stepsRemaining=1
- didMigrateStore
Errors can occur at any point following willConsiderStore
for example:
- willConsiderStore
- willMigrateStore - totalSteps=8
- didFailToMigrateStore
Topics
Methods
func persistentContainer(NSPersistentContainer, didFailToMigrateStore: NSPersistentStoreDescription, error: Error)
func persistentContainer(NSPersistentContainer, didFailToMigrateStore: NSPersistentStoreDescription, error: Error)
Has a default implementation.
Called after an error has occurred during or before migrating a store.
The PersistentContainer.loadPersistentStores(...)
-[PersistentContainer loadPersistentStoresWithCompletionHandler:]
error callback will be made later.
Default Implementation
Do nothing.
Declaration
func persistentContainer(
_ container: NSPersistentContainer,
didFailToMigrateStore: NSPersistentStoreDescription,
error: Error)
Parameters
container |
The |
didFailToMigrateStore |
The store that could not be migrated. |
error |
The reason the store could not be migrated, could be from |
func persistentContainer(NSPersistentContainer, didMigrateStore: NSPersistentStoreDescription)
func persistentContainer(NSPersistentContainer, didMigrateStore: NSPersistentStoreDescription)
Has a default implementation.
Called after a successful store migration.
Default Implementation
Do nothing.
Declaration
func persistentContainer(
_ container: NSPersistentContainer,
didMigrateStore: NSPersistentStoreDescription)
Parameters
container |
The |
didMigrateStore |
The store that has been migrated. |
func persistentContainer(NSPersistentContainer, willConsiderStore: NSPersistentStoreDescription)
func persistentContainer(NSPersistentContainer, willConsiderStore: NSPersistentStoreDescription)
Has a default implementation.
Called for each store that might need to be migrated, before deciding whether to migrate it.
Default Implementation
Do nothing.
Declaration
func persistentContainer(
_ container: NSPersistentContainer,
willConsiderStore: NSPersistentStoreDescription)
Parameters
container |
The |
willConsiderStore |
The store that may be migrated. |
func persistentContainer(NSPersistentContainer, willMigrateStore: NSPersistentStoreDescription, sourceModelVersion: String, destinationModelVersion: String, totalSteps: Int)
func persistentContainer(NSPersistentContainer, willMigrateStore: NSPersistentStoreDescription, sourceModelVersion: String, destinationModelVersion: String, totalSteps: Int)
Has a default implementation.
Called for each store that will be migrated, before any migrations start for the store.
Default Implementation
Do nothing.
Declaration
func persistentContainer(
_ container: NSPersistentContainer,
willMigrateStore: NSPersistentStoreDescription,
sourceModelVersion: String,
destinationModelVersion: String,
totalSteps: Int)
Parameters
container |
The |
willMigrateStore |
The store that will be migrated. |
sourceModelVersion |
The model version that the store currently has. |
destinationModelVersion |
The model version that the store will have after all migrations. |
totalSteps |
The number of separate migration steps that will be executed on the store. |
func persistentContainer(NSPersistentContainer, willNotMigrateStore: NSPersistentStoreDescription, storeExists: Bool)
func persistentContainer(NSPersistentContainer, willNotMigrateStore: NSPersistentStoreDescription, storeExists: Bool)
Has a default implementation.
Called for each store that will not be migrated either because it does not exist or because it is already at the latest version.
Default Implementation
Do nothing.
Declaration
func persistentContainer(
_ container: NSPersistentContainer,
willNotMigrateStore: NSPersistentStoreDescription,
storeExists: Bool)
Parameters
container |
The |
willNotMigrateStore |
The store that will not be migrated. |
storeExists |
|
func persistentContainer(NSPersistentContainer, willSingleMigrateStore: NSPersistentStoreDescription, sourceModelVersion: String, destinationModelVersion: String, usingInferredMapping: Bool, withMigrationManager: NSMigrationManager, toTemporaryLocation: URL, stepsRemaining: Int, totalSteps: Int)
func persistentContainer(NSPersistentContainer, willSingleMigrateStore: NSPersistentStoreDescription, sourceModelVersion: String, destinationModelVersion: String, usingInferredMapping: Bool, withMigrationManager: NSMigrationManager, toTemporaryLocation: URL, stepsRemaining: Int, totalSteps: Int)
Has a default implementation.
Called before each migration step.
Default Implementation
Do nothing.
Declaration
func persistentContainer(
_ container: NSPersistentContainer,
willSingleMigrateStore: NSPersistentStoreDescription,
sourceModelVersion: String,
destinationModelVersion: String,
usingInferredMapping: Bool,
withMigrationManager: NSMigrationManager,
toTemporaryLocation: URL,
stepsRemaining: Int,
totalSteps: Int)
Parameters
container |
The |
willSingleMigrateStore |
The store that will be migrated. |
sourceModelVersion |
The model version this step will be from. |
destinationModelVersion |
The model version this step will be to. |
usingInferredMapping |
|
withMigrationManager |
The |
toTemporaryLocation |
The location on disk of the migrated version of the store. |
stepsRemaining |
The number of migration steps remaining for the store, including this step! |
totalSteps |
The total number of migration steps for this store. |