SwiftData skill for Codex

Done well means: every shipped schema is captured as a VersionedSchema, each release’s changes migrate existing stores on a real upgrade path without data loss, queries filter in the store (not in Swift after fetching everything), and heavy writes happen off the main actor.

Inspect first

cat AGENTS.md 2>/dev/null
grep -rnE '@Model|ModelContainer|VersionedSchema|SchemaMigrationPlan|NSPersistentContainer' \
  --include='*.swift' . | head -40
grep -rn 'IPHONEOS_DEPLOYMENT_TARGET' *.xcodeproj/project.pbxproj | sort -u
grep -rn 'iCloud\|CloudKit' *.entitlements 2>/dev/null

Answer three questions before writing code: has any version of this schema shipped to users (then migrations are mandatory), is CloudKit sync on (then the model rules below apply), and what is the deployment target (#Unique, #Index and history need iOS 18; model inheritance needs iOS 26).

Models

import SwiftData

@Model
final class Trip {
    #Unique<Trip>([\.remoteID])
    #Index<Trip>([\.startDate], [\.name])

    var remoteID: String
    var name: String
    var startDate: Date
    var statusRaw: String = TripStatus.planned.rawValue      // store enums as raw values
    @Attribute(.externalStorage) var coverImage: Data?
    @Relationship(deleteRule: .cascade, inverse: \Stop.trip) var stops: [Stop] = []
    @Transient var isSelected = false

    var status: TripStatus {
        get { TripStatus(rawValue: statusRaw) ?? .planned }
        set { statusRaw = newValue.rawValue }
    }

    init(remoteID: String, name: String, startDate: Date) {
        self.remoteID = remoteID
        self.name = name
        self.startDate = startDate
    }
}

@Model
final class Stop {
    var title: String
    var trip: Trip?
    init(title: String) { self.title = title }
}

• Delete rules: .cascade for owned children, .nullify (default) for references, .deny to block deleting a parent with children.
• Declare the inverse on one side only; SwiftData links the other.
• .externalStorage for blobs over roughly 100 KB so rows stay small.
• Predicates cannot reliably compare enum cases or computed properties: persist raw values and query those.
• #Unique makes inserts with a duplicate key update the existing row (upsert). Before iOS 18 use @Attribute(.unique) on a single property.

Container and contexts

@main
struct TripsApp: App {
    let container: ModelContainer = {
        let schema = Schema(versionedSchema: SchemaV2.self)
        let config = ModelConfiguration(schema: schema)
        do {
            return try ModelContainer(for: schema, migrationPlan: TripsMigrationPlan.self,
                                      configurations: config)
        } catch {
            fatalError("Store failed to open: \(error)")       // log and surface in real apps
        }
    }()

    var body: some Scene {
        WindowGroup { ContentView() }.modelContainer(container)
    }
}

• @Environment(\.modelContext) in views gives the main context (autosaves on UI events). Call try context.save() explicitly after important writes rather than relying on autosave timing.
• Previews and tests: ModelConfiguration(isStoredInMemoryOnly: true).

Queries

struct UpcomingTrips: View {
    @Query private var trips: [Trip]

    init(after date: Date) {
        _trips = Query(
            filter: #Predicate<Trip> { $0.startDate >= date && $0.statusRaw != "cancelled" },
            sort: [SortDescriptor(\.startDate)]
        )
    }

    var body: some View {
        List(trips) { Text($0.name) }
    }
}

Dynamic filters (search text, toggles) go through the view’s init like above; the parent passes the changing value. Outside views:

var descriptor = FetchDescriptor<Trip>(
    predicate: #Predicate { $0.name.localizedStandardContains(search) },
    sortBy: [SortDescriptor(\.startDate, order: .reverse)]
)
descriptor.fetchLimit = 50
descriptor.fetchOffset = page * 50
descriptor.propertiesToFetch = [\.name, \.startDate]
let trips = try context.fetch(descriptor)
let total = try context.fetchCount(FetchDescriptor<Trip>())

• Capture external values in local constants before the predicate; predicates cannot call arbitrary methods or reference self.
• Optional relationships: compare through optional chaining ($0.trip?.name == name). If the macro rejects the expression or it fails at runtime, try $0.trip.flatMap { $0.name == name } == true or query from the other side of the relationship. Test every non-trivial predicate against a real store; some compile and still throw when executed.
• Bulk delete: try context.delete(model: Trip.self, where: #Predicate { $0.statusRaw == "cancelled" }).

Background work

@ModelActor
actor TripImporter {
    func importTrips(_ dtos: [TripDTO]) throws {
        for (i, dto) in dtos.enumerated() {
            modelContext.insert(Trip(remoteID: dto.id, name: dto.name, startDate: dto.start))
            if i % 500 == 0 { try modelContext.save() }
        }
        try modelContext.save()
    }
}

let importer = TripImporter(modelContainer: container)
try await importer.importTrips(dtos)

Model objects are not Sendable. Pass PersistentIdentifiers between actors and re-fetch with modelContext.model(for: id) (or registeredModel(for:)) on the other side.

Schema changes and migrations

Rule: the first time you ship, wrap the schema in SchemaV1: VersionedSchema. Every later change adds a new version and a stage in the plan. Lightweight stages cover added properties with defaults, added optional properties, renames with @Attribute(originalName:), and new models; anything that transforms or de-duplicates data needs a custom stage.

For full versioned-schema code, custom stages, de-duplication before adding #Unique, and how to test an upgrade from an old store, read references/migrations.md whenever a model property, type, uniqueness rule or relationship changes in a schema that has shipped.

CloudKit sync rules

If the container syncs with CloudKit (ModelConfiguration(cloudKitDatabase: .automatic) or iCloud entitlement present):

• No #Unique / .unique attributes.
• Every property optional or with a default value; every relationship optional.
• No .deny delete rule.
• Schema changes deployed to the production CloudKit container are additive only. Deploy the schema in the CloudKit Console before release; that step affects all users, so confirm it with the user.

Gotchas

• Changing a model without a migration plan on a shipped app makes the store fail to open; the common “fix” of deleting the store destroys user data. Never do that without explicit user confirmation and a stated reason.
• @Query re-runs when any matching model changes; very large unbounded queries in frequently rendered views hurt. Add fetchLimit via Query(descriptor).
• Inserting a child and setting parent.children.append(child) before inserting the parent can crash or duplicate; insert parents first, then relate.
• Autosave hides errors. Call save() in a do/catch where failures matter.
• Default values in init vs property declarations: migrations use the property declaration default, so give new non-optional properties a declared default.

Verification

• Unit tests with an in-memory container for queries and delete rules.
• Upgrade test: keep a store file created by the previous release (or create one with the previous schema version in a test), open it with the new container and plan, and assert counts and key values (see the migrations reference).
• xcodebuild test -scheme App -destination 'platform=iOS Simulator,name=iPhone 17' -derivedDataPath build/DerivedData
• Install the previous App Store or TestFlight build on a simulator, add data, then install the new build over it and confirm the data survives.

Report template

**Schema:** V2 -> V3 (Trip.notes added, Stop.order renamed from position)
**Migration:** lightweight V2->V3; upgrade test from V1 and V2 fixtures passes
**CloudKit:** off
**Queries changed:** UpcomingTrips filters in store, fetchLimit 200
**Checks:** 18 persistence tests green; manual upgrade from TestFlight 3.1 build kept 240 trips