skip to content

In Core Data, version 2 renames Album's title attribute to name; why do titles vanish after lightweight migration, and how does a renaming identifier keep them?

level: middleimportance: should knowfreq 48%

answer

  1. a rename looks like delete plus add
  2. inference pairs properties by name
  3. a field in the property inspector
  4. set on the destination model
  5. the first name stays the canonical one

basics

~20 s

An inferred mapping pairs attributes by name, so a renamed attribute looks like one removed and one added: migration succeeds and the values are dropped. Setting the new attribute's renaming identifier to its old name makes Core Data copy them across.

solid answer

~40 s

An inferred mapping model pairs source and destination properties by name. If `title` simply becomes `name`, Core Data sees `title` removed and an optional `name` added; both are inferable, so the store opens without an error and every album's `name` is `nil`. The fix is the **renaming identifier**: in the version 2 model, select `name` and set its renaming ID in the property inspector to `title` (in code, `renamingIdentifier`). Inference then maps `title` to `name` and keeps the values. The identifier acts as a canonical name, so if version 3 renames `name` to `albumTitle`, its identifier stays `title`, and stores at version 1 or 2 both migrate. Entities and relationships rename the same way. The optional `year` added in version 2 needs nothing: existing albums get `nil`.

code

swift · 19 lines
swift
import CoreData

// Version 2 of a model built in code: "title" became "name", and "year" is new.
func albumEntityV2() -> NSEntityDescription {
    let name = NSAttributeDescription()
    name.name = "name"
    name.type = .string
    name.renamingIdentifier = "title"   // the attribute's name in version 1

    let year = NSAttributeDescription()
    year.name = "year"
    year.type = .integer16
    year.isOptional = true              // nothing to backfill

    let album = NSEntityDescription()
    album.name = "Album"
    album.properties = [name, year]
    return album
}

go deeper

for a junior

Know that renaming an attribute without telling Core Data quietly drops its values, and that the renaming ID field fixes it.

for a middle

Explain that inference pairs properties by name, that the identifier goes on the destination model, and why a second rename keeps the first name.

for a senior

Show you catch it in review and in an upgrade test that checks values, since a lost rename produces no error at all.

for a principal

Make a rename without an identifier a blocking review finding, because the data loss cannot be undone by a later release.

## How an inferred mapping pairs properties A **lightweight migration** builds an **inferred mapping model** from the differences between the store's model version and the current one. To find differences it has to decide which property in the old model corresponds to which property in the new one, and by default it pairs them **by name**. That works for every attribute that keeps its name, and it is exactly what goes wrong when one is renamed. ## What a rename without an identifier does Take a record-collection app whose version 1 `Album` entity has a `title` attribute. Version 2 renames it to `name` and adds an optional `year`. With nothing else said, the inference sees: 1. `title` exists in the source and not in the destination: **an attribute was removed**. 2. `name` exists in the destination and not in the source: **an optional attribute was added**. 3. `year` is new and optional: **another attribute was added**. All three are on Apple's list of changes lightweight migration handles, so `loadPersistentStores` succeeds, the app launches, and every album's `name` is `nil`. No error is reported, because from Core Data's point of view nothing failed. `NSMappingModel.inferredMappingModel(forSourceModel:destinationModel:)` returns a mapping model for this pair too: inferable and lossless are different properties. ## Setting the renaming identifier The **renaming identifier** tells the inference that a property is the same one under a new name. - In Xcode, select the renamed attribute **in the destination version** (version 2), and in the property inspector set its renaming ID to the source name, `title`. - In a model built in code, set `renamingIdentifier` on the `NSAttributeDescription`. - Entities have the same field: renaming an `LP` entity to `Album` takes a renaming identifier of `LP` on the version 2 entity. - Relationships rename the same way, as Apple's lightweight migration documentation states. With the identifier in place, the inferred mapping pairs `title` with `name`, and the values survive. The new optional `year` needs no help: existing rows simply hold `nil`. Had `year` been non-optional, it would need a default value for the existing rows. ## Renaming the same property twice Apple's documentation calls the renaming identifier a **canonical name**: set it to the source property's name unless that property already carries an identifier, in which case keep that one. | Version | Attribute name | Renaming identifier | |---|---|---| | 1 | `title` | none | | 2 | `name` | `title` | | 3 | `albumTitle` | `title` | With `title` carried forward, a store at version 2 and a store still at version 1 both migrate to version 3 with their values. Setting version 3's identifier to `name` instead looks reasonable and loses the values: version 2's attribute is already known by its canonical name `title`, so nothing matches `name`. ## What a renaming identifier does not cover The identifier answers one question, which old property a new one continues, and nothing else. - **It does not make a type change inferable.** Renaming `title` to `released` and changing it from String to Integer 32 in the same version still fails to load with error 134140: the pairing is now known, but the types are incompatible and no mapping can be inferred. - **It does not compute values.** Splitting an `artist` string into `firstName` and `lastName` cannot be expressed as a rename of either; that needs migration code. - **It is per property.** Each renamed attribute or relationship needs its own identifier, even when its entity is renamed in the same version. ## Checking a rename before it ships - Keep a store saved by the previous release and open it with the new model in a test; assert that the values are still there, not just that loading succeeded. - Review every model diff for a property or entity that disappeared in the same change as a new one appeared: that pattern is either a deliberate delete plus add or a rename missing its identifier. - Remember the identifier lives on the destination model, so it has to be set in the version being added, before release; a later version cannot recover values an earlier migration already dropped. A rename is the cheapest migration Core Data offers, but only when the model says it is a rename.

  • In Core Data, can lightweight migration rename a relationship as well as an attribute?
    Yes. Apple's lightweight migration documentation says relationships can be renamed with a renaming identifier exactly like attributes, and entities can be renamed the same way. Set the identifier on the relationship in the destination model to its name in the source model, and the existing links are carried over instead of being dropped and recreated empty.
  • In Core Data, a rename shipped without an identifier and users already migrated; can the next version restore the values?
    Not from the store: the migration that ran already wrote `nil` into the new attribute and discarded the old attribute's values, so the next model has nothing to map. The values can come back only from somewhere else, such as a server copy. That is why the identifier has to be in the version that performs the rename.

A renaming identifier is like a company keeping its original registration number through every rebrand. The records office matches files by that number, not by the trading name, so the new name finds the old file. Without the number, the clerk opens an empty file for the new name and archives the old one.

  • A rename makes lightweight migration fail, so you will see an error at launch.
  • Put the renaming identifier on the attribute in the old model version.
  • On a second rename, replace the first renaming identifier with the previous version's name.
  • Renaming needs a mapping model; inferred migration only handles additions.