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

PersistentContainer PersistentContainer

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

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..

Topics

Initializers

Initializes a persistent container from a named model.

Declaration
Swift
public convenience init(
    name: String,
    bundles: [Bundle] = [Bundle.main],
    modelVersionOrder: ModelVersionOrder = .compare,
    logMessageHandler: LogMessage.Handler? = nil)
Parameters
name

The name of the managed object model to use with the container. This name is used as the default name for the first persistent store.
bundles

An array of bundles to search for the container’s model. By default only the app’s main bundle. If the model exists in multiple bundles then the first one in the array is used. If the model exists more than once in the same bundle then it is undefined which is used. These bundles are also used to search for data and mapping models during automatic multi-step store migration.
modelVersionOrder

The ordering algorithm of model versions used to guide automatic multi-step store migration. The default is a numeric string comparison, meaning that MyModel1 precedes MyModel2 precedes MyModel10.
logMessageHandler

A callback to receive log messages from the library suitable for helping debug applications. Calls can occur on any queue. The default performs no logging.

Initializes a persistent container using a managed object model.

Declaration
Swift
public init(
    name: String,
    managedObjectModel model: NSManagedObjectModel,
    bundles: [Bundle] = [Bundle.main],
    modelVersionOrder: ModelVersionOrder = .compare,
    logMessageHandler: LogMessage.Handler?)
Parameters
name

The defaut name for the first persistent store.
model

The managed object model to be used by the persistent container.
bundles

An array of bundles used to search for data models and mapping models during automatic multi-step store migration.
modelVersionOrder

The ordering algorithm of model versions used to guide automatic multi-step store migration. The default is a numeric string comparison, meaning that MyModel1 precedes MyModel2 precedes MyModel10.
logMessageHandler

A callback to receive log messages from the library suitable for helping debug applications. Calls can occur on any queue. The default performs no logging.

Methods

Begin loading and migrating the persistent stores mentioned in persistentStoreDescriptions that have not already been loaded. The completion handler is called once for each such store on the main queue indicating whether the store has been loaded successfully.

If the store description has shouldMigrateStoreAutomatically set then the container automatically attempts multi-step migration. If the store description also has shouldInferMappingModelAutomatically set then the multi-step migration can include the use of inferred mapping models and light-weight migration. Once any multi-step migration is complete, Core Data is invoked to load the store and set up the stack for use.

These flags are both on by default.

If any of the store descriptions have shouldAddStoreAsynchronously set then this routine returns immediately and all migrations occur on a background queue. This flag is off by default.

If the container has multiple stores then the container tries very hard to ensure either all stores are migrated successfully or none are.

Declaration
Swift
open override func loadPersistentStores(
    completionHandler block: @escaping (NSPersistentStoreDescription, Error?) ->
        Void)
Objective-C
- (void)loadPersistentStoresWithCompletionHandler:
    (void (^_Nonnull)(NSPersistentStoreDescription *_Nonnull,
                      NSError *_Nullable))block
Parameters
block

Callback made on the main queue for each store when it has either been loaded successfully or failed to load. The ErrorError here can be anything provided by NSPersistentContainer.loadPersistentStores as well as anything from MigrationError in this package.

Properties

Optional delegate to receive migration progress notifications.

Declaration
Swift
public weak var migrationDelegate: MigrationDelegate?