Migraciones y versiones: cambiar sin perder datos

El código de tu app se reemplaza entero en cada actualización; los datos de tus usuarios, jamás. Esa asimetría es la razón de que las migraciones sean el problema más ingrato de la persistencia: se ejecutan una sola vez por dispositivo, sobre datos que no puedes inspeccionar de antemano, sin posibilidad de deshacer y con el usuario esperando en la pantalla de arranque. Y sin embargo son perfectamente domesticables si se tratan como lo que son: código de producción que merece pruebas.

Anatomía de un cambio de esquema

Un cambio es ligero cuando el motor puede deducir la correspondencia sin ambigüedad: añadir una propiedad con valor por defecto, añadir una opcional, añadir una entidad nueva, relajar una restricción. El almacén se reescribe automáticamente al abrirlo y tu código no interviene.

Un cambio es personalizado cuando la correspondencia existe pero requiere una decisión que el motor no puede tomar: renombrar una propiedad, cambiar el tipo de un atributo, derivar el valor de un campo nuevo a partir de los antiguos. Aquí declaras la intención — este campo de aquella versión es este campo de esta — o ejecutas código antes y después de la transformación.

Y un cambio es estructural cuando la propia forma del grafo cambia: partir una entidad en dos, fusionar dos en una, invertir la cardinalidad de una relación. Estos son los casos donde conviene bajar a la capa de Core Data y usar sus modelos de correspondencia, porque la transformación necesita ver el objeto de origen y el de destino a la vez.

Esquemas versionados y etapas

La disciplina que hace manejable todo lo anterior es congelar cada versión del modelo como un tipo propio y no volver a tocarla nunca. Una versión publicada es historia: existe en dispositivos ajenos y modificarla invalida las etapas que parten de ella.

import SwiftData

enum EsquemaV1: VersionedSchema {
    static var versionIdentifier = Schema.Version(1, 0, 0)
    static var models: [any PersistentModel.Type] { [Nota.self] }

    @Model final class Nota {
        var titulo: String = ""
        var cuerpo: String = ""
    }
}

enum EsquemaV2: VersionedSchema {
    static var versionIdentifier = Schema.Version(2, 0, 0)
    static var models: [any PersistentModel.Type] { [Nota.self] }

    @Model final class Nota {
        var titulo: String = ""
        var cuerpo: String = ""
        var etiquetas: [String] = []
        var creada: Date = Date.now
    }
}

enum PlanDeMigracion: SchemaMigrationPlan {
    static var schemas: [any VersionedSchema.Type] {
        [EsquemaV1.self, EsquemaV2.self]
    }

    static var stages: [MigrationStage] {
        [deV1aV2]
    }

    static let deV1aV2 = MigrationStage.custom(
        fromVersion: EsquemaV1.self,
        toVersion: EsquemaV2.self,
        willMigrate: nil,
        didMigrate: { contexto in
            let notas = try contexto.fetch(FetchDescriptor<EsquemaV2.Nota>())
            for nota in notas where nota.etiquetas.isEmpty {
                nota.etiquetas = ["sin clasificar"]
            }
            try contexto.save()
        }
    )
}

let contenedor = try ModelContainer(
    for: EsquemaV2.Nota.self,
    migrationPlan: PlanDeMigracion.self
)

El plan se aplica en cadena: un dispositivo que venía de la primera versión y salta directo a la cuarta ejecuta las tres etapas en orden, una tras otra, en la misma apertura. Eso significa que cada etapa debe funcionar sobre el resultado exacto de la anterior, y que no puedes asumir que el usuario venía de la versión inmediatamente previa. Los usuarios que no abren la app en un año son los que ejercitan los caminos que nadie probó.

flowchart LR
A[Almacen en version 1] --> B[Etapa 1 a 2]
B --> C[Etapa 2 a 3]
C --> D[Etapa 3 a 4]
D --> E[Almacen en version 4]
F[Almacen en version 3] --> D
style E fill:#a6e3a1,color:#11111b

Probar la migración antes de publicar

Una migración sin pruebas es una apuesta sobre datos ajenos. La práctica que la convierte en ingeniería es mantener un corpus: un directorio con almacenes de cada versión publicada, generados con datos representativos — conjuntos vacíos, conjuntos grandes, valores límite, caracteres no latinos, relaciones incompletas — y versionados junto al código.

import Testing

@Test func migracionDesdeV1ConservaLosDatos() throws {
    let origen = Bundle.module.url(forResource: "corpus-v1", withExtension: "store")!
    let trabajo = URL.temporaryDirectory.appending(path: "prueba-\(UUID()).store")
    try FileManager.default.copyItem(at: origen, to: trabajo)

    let contenedor = try ModelContainer(
        for: EsquemaV2.Nota.self,
        migrationPlan: PlanDeMigracion.self,
        configurations: ModelConfiguration(url: trabajo)
    )
    let contexto = ModelContext(contenedor)
    let notas = try contexto.fetch(FetchDescriptor<EsquemaV2.Nota>())

    #expect(notas.count == 250)
    #expect(notas.allSatisfy { !$0.etiquetas.isEmpty })
    #expect(notas.allSatisfy { !$0.titulo.isEmpty })
}

Cada prueba trabaja sobre una copia, nunca sobre el original del corpus, porque una migración es destructiva por definición. Y las aserciones deben cubrir tres cosas distintas: que el conteo se conserva, que los campos derivados tienen el valor esperado, y que ningún dato previo se ha perdido por el camino. Un conteo correcto con campos vacíos es un fallo silencioso.