<!--
{
  "availability" : [
    "iOS: 17.0.0 -",
    "iPadOS: 17.0.0 -",
    "macCatalyst: 17.0.0 -",
    "macOS: 14.0.0 -",
    "tvOS: 17.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 10.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "CoreData",
  "identifier" : "/documentation/CoreData/NSCustomMigrationStage",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Core Data"
    ],
    "preciseIdentifier" : "c:objc(cs)NSCustomMigrationStage"
  },
  "title" : "NSCustomMigrationStage"
}
-->

# NSCustomMigrationStage

An object that enables you to participate in the migration between two versions of the same model.

```
class NSCustomMigrationStage
```

## Overview

Use [`NSCustomMigrationStage`](/documentation/CoreData/NSCustomMigrationStage) when you have two versions of a model that Core Data can’t automatically migrate. Custom migration stages enable you to participate in the migration process by assigning handlers that the stage invokes before and after it runs. The handlers provide an opportunity to prepare the persistent store’s data for the upcoming changes before the stage runs, and perform any cleanup tasks afterward.

For example, to support a migration that changes an optional attribute to be nonoptional, you might assign a handler to the stage’s [`willMigrateHandler`](/documentation/CoreData/NSCustomMigrationStage/willMigrateHandler-5wead) property that sets any `nil` instances of that attribute to a default value, thereby ensuring the migration succeeds. To access the store you’re migrating, use the [`container`](/documentation/CoreData/NSStagedMigrationManager/container) property of the migration manager that Core Data provides to every handler.

## Topics

### Creating a custom migration stage

[`init(migratingFrom:to:)`](/documentation/CoreData/NSCustomMigrationStage/init(migratingFrom:to:))

Creates a custom migration stage with the specified source and destination model references.

[`-  initWithCurrentModelReference:nextModelReference:`](/documentation/CoreData/NSCustomMigrationStage/initWithCurrentModelReference:nextModelReference:)

Creates a custom migration stage with the specified source and destination model references.

[`NSManagedObjectModelReference`](/documentation/CoreData/NSManagedObjectModelReference)

An object that describes a specific version of an object model.

### Accessing model references

[`currentModel`](/documentation/CoreData/NSCustomMigrationStage/currentModel)

The reference that represents the migration’s source model.

[`nextModel`](/documentation/CoreData/NSCustomMigrationStage/nextModel)

The reference that represents the migration’s destination model.

### Assigning event handlers

[`willMigrateHandler`](/documentation/CoreData/NSCustomMigrationStage/willMigrateHandler-5wead)

The handler to execute before the stage runs.

[`didMigrateHandler`](/documentation/CoreData/NSCustomMigrationStage/didMigrateHandler-2zbss)

The handler to execute after the stage runs.

[`willMigrateHandler`](/documentation/CoreData/NSCustomMigrationStage/willMigrateHandler-72p73)

The handler to execute before the stage runs.

[`didMigrateHandler`](/documentation/CoreData/NSCustomMigrationStage/didMigrateHandler-36uhx)

The handler to execute after the stage runs.

## Relationships

### Inherits From

[`NSMigrationStage`](/documentation/CoreData/NSMigrationStage)

### Conforms To

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`Hashable`](/documentation/Swift/Hashable)

[`CVarArg`](/documentation/Swift/CVarArg)

[`Equatable`](/documentation/Swift/Equatable)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)