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

Main APIs

These types form the main API.

Topics

A container for a Core Data stack that provides automatic multi-step shortest-path persistent store migration.

This is a drop-in replacement for NSPersistentContainerNSPersistentContainer that automatically detects and performs multi-step store migration as part of the loadPersistentStores(...)-[PersistentContainer loadPersistentStoresWithCompletionHandler:] method.

The container searches for models and mapping models, then constructs the best sequence in which to migrate stores. It prefers to use explicit mapping models over inferred mapping models when there is a choice. Progress and status can be reported back to the client code.

See the user guide for more details.

See PersistentCloudKitContainerPersistentCloudKitContainer for a version capable of managing both CloudKit-backed and non-cloud stores..

Declaration
Swift
open class PersistentContainer: NSPersistentContainer,
    PersistentContainerMigratable, PersistentContainerProtocol,
    LogMessageEmitter, Sendable
Objective-C
@interface PersistentContainer : NSPersistentContainer

A container for a Core Data stack that provides automatic multi-step shortest-path persistent store migration, capable of managing both CloudKit-backed and non-cloud stores.

This is a drop-in replacement for NSPersistentCloudKitContainerNSPersistentCloudKitContainer that automatically detects and performs multi-step store migration as part of the loadPersistentStores(...)-[PersistentCloudKitContainer loadPersistentStoresWithCompletionHandler:] method.

The container searches for models and mapping models, then constructs the best sequence in which to migrate stores. It prefers to use explicit mapping models over inferred mapping models when there is a choice. Progress and status can be reported back to the client code.

See the user guide for more details.

See PersistentContainerPersistentContainer for a version that does not support CloudKit-backed stores.

Declaration
Swift
open class PersistentCloudKitContainer: NSPersistentCloudKitContainer,
    PersistentContainerMigratable, PersistentContainerProtocol,
    LogMessageEmitter, Sendable
Objective-C
@interface PersistentCloudKitContainer : NSPersistentCloudKitContainer

A rule for ordering model versions. The persistent container performs automatic multi-step migration in the direction defined by this rule, which operates on the names of the model version. Note that the model version here is the part of its filename before ‘.xcdatamodel’ – not the optional ‘Model Version Identifier’ that you can set in the model’s properties panel.

Declaration
Swift
public enum ModelVersionOrder: Sendable

extension ModelVersionOrder: CustomStringConvertible

Errors that can occur preventing persistent store loading, passed into the callback given to PersistentContainer.loadPersistentStores(...)-[PersistentContainer loadPersistentStoresWithCompletionHandler:] or PersistentCloudKitContainer.loadPersistentStores(...)-[PersistentCloudKitContainer loadPersistentStoresWithCompletionHandler:].

When any of these unusual conditions occurs, the persistent container provides a lot of human-readable (-ish) information to the logging interface. The first step to debugging one of these errors is to read that text and try to make sense of it.

Declaration
Swift
public enum MigrationError: Error, Sendable

extension MigrationError: CustomStringConvertible

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
Declaration
Swift
public protocol MigrationDelegate: AnyObject