Skip to content

existential-birds/beagle / plugins/beagle-ios/skills/swiftdata-code-review

swiftdata-code-review

Verified

Reviews SwiftData code for model design, queries, concurrency, and migrations. Use when reviewing .swift files with import SwiftData, @Model, @Query, @ModelActor, or VersionedSchema.

FileKindSize
SKILL.mdskill md3.0 KB
references/concurrency.mdmarkdown4.3 KB
references/migrations.mdmarkdown4.8 KB
references/model-design.mdmarkdown3.3 KB
references/queries.mdmarkdown3.8 KB

references/migrations.md

View on GitHub
# SwiftData Migrations

## Best Practices

| Practice | Description |
|----------|-------------|
| VersionedSchema from start | Even before shipping, makes future migrations easier |
| Semantic versioning | `Schema.Version(1, 0, 0)` format |
| Typealias for latest | `typealias User = UsersSchemaV2.User` |
| Enums for schema versions | Won't be instantiated directly |
| Stages for ALL versions | Even lightweight ones |
| Chronological order | In `SchemaMigrationPlan.schemas` |
| `@Attribute(originalName:)` | When renaming properties to preserve data |
| Keep originalName annotation | For future installs from old versions |

## VersionedSchema Setup

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

    static var models: [any PersistentModel.Type] { [User.self] }

    @Model
    class User {
        var name: String
        init(name: String) { self.name = name }
    }
}

enum UsersSchemaV2: VersionedSchema {
    static var versionIdentifier = Schema.Version(2, 0, 0)

    static var models: [any PersistentModel.Type] { [User.self] }

    @Model
    class User {
        @Attribute(originalName: "name") var fullName: String  // Renamed
        @Attribute(.unique) var email: String  // Added
        init(fullName: String, email: String) { ... }
    }
}

typealias User = UsersSchemaV2.User
```

## Migration Plan

```swift
enum UsersMigrationPlan: SchemaMigrationPlan {
    static var schemas: [any VersionedSchema.Type] {
        [UsersSchemaV1.self, UsersSchemaV2.self]
    }

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

    // Custom: clean duplicates before adding .unique
    static let migrateV1toV2 = MigrationStage.custom(
        fromVersion: UsersSchemaV1.self,
        toVersion: UsersSchemaV2.self,
        willMigrate: { context in
            let users = try context.fetch(FetchDescriptor<UsersSchemaV1.User>())
            var seen = Set<String>()
            for user in users where seen.contains(user.email) {
                context.delete(user)
            }
            try context.save()
        },
        didMigrate: nil
    )

    // Lightweight: simple changes
    static let migrateV2toV3 = MigrationStage.lightweight(
        fromVersion: UsersSchemaV2.self,
        toVersion: UsersSchemaV3.self
    )
}
```

## ModelContainer Configuration

```swift
let container = try ModelContainer(
    for: User.self,
    migrationPlan: UsersMigrationPlan.self
)
```

## Critical Anti-Patterns

### Renaming Without originalName

```swift
// BAD: Data LOST
var fullName: String  // Was "name", no mapping

// GOOD: Data preserved
@Attribute(originalName: "name") var fullName: String
```

### Adding .unique to Duplicated Data

```swift
// BAD: Crash if duplicates exist
@Attribute(.unique) var email: String

// GOOD: Clean duplicates in willMigrate first
willMigrate: { context in
    // Remove duplicates before schema applies .unique
}
```

### Custom Migrations with CloudKit

```swift
// BAD: Crashes with CloudKit
MigrationStage.custom(willMigrate: { ... }, didMigrate: { ... })

// GOOD: Lightweight only for CloudKit apps
MigrationStage.lightweight(fromVersion:, toVersion:)
// Handle complex logic in app initialization
```

### Wrong Schema in Migration Closure

```swift
// BAD: V2 not available in willMigrate
willMigrate: { context in
    try context.fetch(FetchDescriptor<SchemaV2.User>())  // WRONG
}

// GOOD: V1 in willMigrate, V2 in didMigrate
willMigrate: { context in
    try context.fetch(FetchDescriptor<SchemaV1.User>())  // Correct
}
didMigrate: { context in
    try context.fetch(FetchDescriptor<SchemaV2.User>())  // Correct
}
```

### Missing MigrationPlan

```swift
// BAD: Migration not applied
let container = try ModelContainer(for: User.self)

// GOOD: Migration plan specified
let container = try ModelContainer(
    for: User.self,
    migrationPlan: UsersMigrationPlan.self
)
```

## Lightweight vs Custom

**Lightweight migrations support:**
- Adding properties with default values
- Renaming with `@Attribute(originalName:)`
- Deleting properties
- Adjusting delete rules

**Custom migrations needed for:**
- Data transformation
- Deduplication before `.unique`
- Complex relationship changes
- Default value calculation from existing data

## Review Questions

- [ ] Is every shipped schema wrapped in VersionedSchema?
- [ ] Does each schema have a unique versionIdentifier?
- [ ] Are schemas listed in chronological order?
- [ ] Is there a MigrationStage for each version transition?
- [ ] Is MigrationPlan passed to ModelContainer?
- [ ] Do renamed properties use `@Attribute(originalName:)`?
- [ ] If adding `.unique`, are duplicates handled in willMigrate?
- [ ] Does willMigrate only access old schema models?
- [ ] Is CloudKit enabled? (Custom migrations will crash)
- [ ] Is `context.save()` called in migration closures?
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall