TMLPersistentContainer 5.0.1
(100% documented)
Open on GitHub Open in Dash

MigrationDelegate

Not available in Objective-C.
Swift
public protocol MigrationDelegate: AnyObject

A delegate that can be provided to PersistentContainerPersistentContainer or PersistentCloudKitContainerPersistentCloudKitContainer 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 NSPersistentStoreDescriptionNSPersistentStoreDescriptions 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:

  1. willConsiderStore
  2. willNotMigrateStore

A store requiring a 2-step migration sees the sequence:

  1. willConsiderStore
  2. willMigrateStore - totalSteps=2
  3. willSingleMigrateStore - stepsRemaining=2
  4. willSingleMigrateStore - stepsRemaining=1
  5. didMigrateStore

Errors can occur at any point following willConsiderStore for example:

  1. willConsiderStore
  2. willMigrateStore - totalSteps=8
  3. didFailToMigrateStore

Topics

Methods

Note

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
Swift
func persistentContainer(
    _ container: NSPersistentContainer,
    didFailToMigrateStore: NSPersistentStoreDescription,
    error: Error)
Parameters
container

The NSPersistentContainerNSPersistentContainer asked to load the store.
didFailToMigrateStore

The store that could not be migrated.
error

The reason the store could not be migrated, could be from MigrationError.
Note

Has a default implementation.

Called after a successful store migration.

Default Implementation

Do nothing.

Declaration
Swift
func persistentContainer(
    _ container: NSPersistentContainer,
    didMigrateStore: NSPersistentStoreDescription)
Parameters
container

The NSPersistentContainerNSPersistentContainer asked to load the store.
didMigrateStore

The store that has been migrated.
Note

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
Swift
func persistentContainer(
    _ container: NSPersistentContainer,
    willConsiderStore: NSPersistentStoreDescription)
Parameters
container

The NSPersistentContainerNSPersistentContainer asked to load the store.
willConsiderStore

The store that may be migrated.
Note

Has a default implementation.

Called for each store that will be migrated, before any migrations start for the store.

Default Implementation

Do nothing.

Declaration
Swift
func persistentContainer(
    _ container: NSPersistentContainer,
    willMigrateStore: NSPersistentStoreDescription,
    sourceModelVersion: String,
    destinationModelVersion: String,
    totalSteps: Int)
Parameters
container

The NSPersistentContainerNSPersistentContainer asked to load the store.
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.
Note

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
Swift
func persistentContainer(
    _ container: NSPersistentContainer,
    willNotMigrateStore: NSPersistentStoreDescription,
    storeExists: Bool)
Parameters
container

The NSPersistentContainerNSPersistentContainer asked to load the store.
willNotMigrateStore

The store that will not be migrated.
storeExists

true if the store exists on disk at the right version.
Note

Has a default implementation.

Called before each migration step.

Default Implementation

Do nothing.

Declaration
Swift
func persistentContainer(
    _ container: NSPersistentContainer,
    willSingleMigrateStore: NSPersistentStoreDescription,
    sourceModelVersion: String,
    destinationModelVersion: String,
    usingInferredMapping: Bool,
    withMigrationManager: NSMigrationManager,
    toTemporaryLocation: URL,
    stepsRemaining: Int,
    totalSteps: Int)
Parameters
container

The NSPersistentContainerNSPersistentContainer asked to load the store.
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

true if the mapping model for the step has been inferred.
withMigrationManager

The NSMigrationManagerNSMigrationManager that will be used.
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.