SwiftData Custom Schema Migrations

Overview

SwiftData schema migrations move your data safely when models change. Core principle SwiftData's willMigrate sees only OLD models, didMigrate sees only NEW models—you can never access both simultaneously. This limitation shapes all migration strategies.

Requires iOS 17+, Swift 5.9+ Target iOS 26+ (features like propertiesToFetch)

When Custom Migrations Are Required

Lightweight Migrations (Automatic)

SwiftData can migrate automatically for:

• ✅ Adding new optional properties
• ✅ Adding new required properties with default values
• ✅ Removing properties
• ✅ Renaming properties (with @Attribute(originalName:))
• ✅ Changing relationship delete rules
• ✅ Adding new models

Custom Migrations (This Skill)

You need custom migrations for:

• ❌ Changing property types (String → AttributedString, Int → String)
• ❌ Making optional properties required (must populate existing nulls)
• ❌ Complex relationship restructuring
• ❌ Data transformations (splitting/merging fields)
• ❌ Deduplication when adding unique constraints

Example Prompts

These are real questions developers ask that this skill is designed to answer:

1. "I need to change a property from String to AttributedString. How do I migrate existing data with relationships intact?"

→ The skill shows the two-stage migration pattern that works around the willMigrate/didMigrate limitation

2. "My model has a one-to-many relationship with cascade delete. How do I preserve this during a type change migration?"

→ The skill explains relationship prefetching and maintaining inverse relationships across schema versions

3. "I have a many-to-many relationship between Tags and Notes. The migration is failing with 'Expected only Arrays for Relationships'. What's wrong?"

→ The skill covers explicit inverse relationship requirements and iOS 17.0 alphabetical naming bug

4. "I need to rename a model but keep all its relationships intact."

→ The skill shows @Attribute(originalName:) patterns for lightweight migration

5. "My migration works in the simulator but crashes on a real device with existing data."

→ The skill emphasizes real-device testing and explains why simulator success doesn't guarantee production safety

6. "Why do I have to copy ALL my models into each VersionedSchema, even ones that haven't changed?"

→ The skill explains SwiftData's design: each VersionedSchema is a complete snapshot, not a diff

7. "I'm getting 'The model used to open the store is incompatible with the one used to create the store' error."

→ The skill provides debugging steps for schema version mismatches

8. "How do I test my SwiftData migration before releasing to production?"

→ The skill covers migration testing workflow, real device testing requirements, and validation strategies

The willMigrate/didMigrate Limitation

CRITICAL This is the architectural constraint that shapes all SwiftData migration patterns.

What You Can Access

static let migrateV1toV2 = MigrationStage.custom(
    fromVersion: SchemaV1.self,
    toVersion: SchemaV2.self,
    willMigrate: { context in
        // ✅ CAN access: SchemaV1 models (old)
        let v1Notes = try context.fetch(FetchDescriptor<SchemaV1.Note>())

        // ❌ CANNOT access: SchemaV2 models
        // SchemaV2.Note doesn't exist yet
    },
    didMigrate: { context in
        // ✅ CAN access: SchemaV2 models (new)
        let v2Notes = try context.fetch(FetchDescriptor<SchemaV2.Note>())

        // ❌ CANNOT access: SchemaV1 models
        // SchemaV1.Note is gone
    }
)

Why This Matters

You cannot directly transform data from old type to new type in a single migration stage. Example:

// ❌ IMPOSSIBLE - you can't do this in one stage
willMigrate: { context in
    let oldNotes = try context.fetch(FetchDescriptor<SchemaV1.Note>())
    for oldNote in oldNotes {
        let newNote = SchemaV2.Note()  // ❌ Doesn't exist yet!
        newNote.content = oldNote.contentAsAttributedString()
    }
}

Solution Use two-stage migration pattern (covered below).

Core Patterns

Pattern 1: Basic VersionedSchema Setup

Every distinct schema version must be defined as a VersionedSchema.

import SwiftData

enum NotesSchemaV1: VersionedSchema {
    static var versionIdentifier = Schema.Version(1, 0, 0)

    static var models: [any PersistentModel.Type] {
        [Note.self, Folder.self, Tag.self]  // ALL models, even if unchanged
    }

    @Model
    final class Note {
        @Attribute(.unique) var id: String
        var title: String
        var content: String  // Original type
        var createdAt: Date

        @Relationship(deleteRule: .nullify, inverse: \Folder.notes)
        var folder: Folder?

        @Relationship(deleteRule: .nullify, inverse: \Tag.notes)
        var tags: [Tag] = []

        init(id: String, title: String, content: String, createdAt: Date) {
            self.id = id
            self.title = title
            self.content = content
            self.createdAt = createdAt
        }
    }

    @Model
    final class Folder {
        @Attribute(.unique) var id: String
        var name: String

        @Relationship(deleteRule: .cascade)
        var notes: [Note] = []

        init(id: String, name: String) {
            self.id = id
            self.name = name
        }
    }

    @Model
    final class Tag {
        @Attribute(.unique) var id: String
        var name: String

        @Relationship(deleteRule: .nullify)
        var notes: [Note] = []

        init(id: String, name: String) {
            self.id = id
            self.name = name
        }
    }
}

Key patterns

• Complete snapshot All models included, even unchanged ones
• Semantic versioning Use Schema.Version(major, minor, patch)
• Explicit init SwiftData doesn't synthesize initializers
• Inverse relationships Specify on both sides for bidirectional

Pattern 2: Two-Stage Migration for Type Changes

Use when Changing property type (String → AttributedString, Int → String, etc.)

Problem

We want to change Note.content from String to AttributedString, but we can't access both old and new types simultaneously.

Solution

Use an intermediate schema version (V1.1) that has BOTH properties.

// Stage 1: V1 → V1.1 (Add new property alongside old)
enum NotesSchemaV1_1: VersionedSchema {
    static var versionIdentifier = Schema.Version(1, 1, 0)

    static var models: [any PersistentModel.Type] {
        [Note.self, Folder.self, Tag.self]
how to use axiom-swiftdata-migration
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use axiom-swiftdata-migration on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add axiom-swiftdata-migration
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/charleswiltgen/axiom --skill axiom-swiftdata-migrationcopy
The skills CLI fetches axiom-swiftdata-migration from GitHub repository charleswiltgen/axiom and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/axiom-swiftdata-migration
Reload or restart Cursor to activate axiom-swiftdata-migration. Access the skill through slash commands (e.g., /axiom-swiftdata-migration) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?