AvdLee/Core-Data-Agent-Skill / core-data-expert
core-data-expert
VerifiedExpert Core Data guidance (iOS/macOS): stack setup, fetch requests & NSFetchedResultsController, saving/merge conflicts, threading & Swift Concurrency, batch operations & persistent history, migrations, performance, and NSPersistentCloudKitContainer/CloudKit sync.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.8 KB |
| references/_index.md | markdown | 4.0 KB |
| references/batch-operations.md | markdown | 14.4 KB |
| references/cloudkit-integration.md | markdown | 6.2 KB |
| references/concurrency.md | markdown | 12.5 KB |
| references/fetch-requests.md | markdown | 17.1 KB |
| references/glossary.md | markdown | 5.6 KB |
| references/migration.md | markdown | 10.6 KB |
| references/model-configuration.md | markdown | 14.2 KB |
| references/performance.md | markdown | 6.2 KB |
| references/persistent-history.md | markdown | 17.1 KB |
| references/project-audit.md | markdown | 2.1 KB |
| references/saving.md | markdown | 13.7 KB |
| references/stack-setup.md | markdown | 17.5 KB |
| references/testing.md | markdown | 7.8 KB |
| references/threading.md | markdown | 14.1 KB |
references/model-configuration.md
View on GitHub# Model Configuration
Core Data's data model offers powerful configuration options beyond basic attributes and relationships. This guide covers constraints, derived attributes, transformables, validation, and lifecycle events.
## Constraints
Constraints ensure uniqueness of attribute values. When combined with the correct merge policy, Core Data automatically handles duplicates.
### Setting Up Constraints
In Xcode's Data Model Editor:
1. Select your entity
2. In the Data Model Inspector, find "Constraints"
3. Click "+" and add attribute names
**Example:** Make `name` unique in the `Category` entity.
### Required Merge Policy
```swift
viewContext.mergePolicy = NSMergeByPropertyStoreTrumpMergePolicy
```
**Without this merge policy, constraint violations will crash your app.**
### How Constraints Work
```swift
// First save
let category1 = Category(context: context)
category1.name = "Swift"
try context.save() // Saves successfully
// Duplicate attempt
let category2 = Category(context: context)
category2.name = "Swift" // Same name
try context.save() // With correct merge policy: keeps first, discards second
```
### Multiple Constraints
```swift
// Constraints on multiple attributes
// In model: constraints = ["email", "username"]
// Both must be unique
user1.email = "test@example.com"
user1.username = "testuser"
```
### Compound Constraints
```swift
// Unique combination of attributes
// In model: constraints = ["firstName,lastName"]
// These are different (unique combinations)
person1.firstName = "John"
person1.lastName = "Doe"
person2.firstName = "John"
person2.lastName = "Smith" // Different combination, allowed
```
## Derived Attributes
Derived attributes are computed from other attributes or relationships and stored in the database. They're calculated on save or refresh.
### Benefits
- No need to manually update computed values
- Better performance than accessing relationships
- Optimized for queries
### Common Derivations
#### 1. Count of Relationships
```swift
// In Data Model Editor:
// Derived attribute: articlesCount
// Derivation: articles.@count
```
**Why this is better than `articles.count`:**
- Doesn't fire faults
- Faster queries
- Always up-to-date after save
#### 2. Related Object Property
```swift
// Derived attribute: categoryName
// Derivation: category.name
```
**Use case:** Avoid firing faults when displaying list views.
#### 3. Current Timestamp
```swift
// Derived attribute: lastModified
// Derivation: now()
```
**Automatically updates on every save.**
#### 4. Canonical String (Search Optimization)
```swift
// Derived attribute: searchName
// Derivation: canonical:(name)
```
**What it does:**
- Converts to lowercase
- Removes diacritics
- Perfect for case-insensitive, diacritic-insensitive searches
**Example:**
```swift
// name = "Café"
// searchName = "cafe"
// Search query
fetchRequest.predicate = NSPredicate(format: "searchName CONTAINS %@", "cafe")
// Matches "Café", "CAFE", "café", etc.
```
#### 5. Sum of Related Values
```swift
// Derived attribute: totalViews
// Derivation: @sum.articles.views
```
### Important Notes
- Derived attributes are calculated **on save** or **refresh**
- In-memory changes don't update derived attributes until saved
- Can't be set manually (they're computed)
### Example Usage
```swift
class Article: NSManagedObject {
@NSManaged var name: String
@NSManaged var category: Category?
// Derived from category.name
@NSManaged var categoryName: String?
// Derived from canonical:(name)
@NSManaged var searchName: String?
}
// Usage
article.name = "Core Data Best Practices"
try context.save()
// After save, derived attributes are updated
print(article.searchName) // "core data best practices"
print(article.categoryName) // "Swift"
```
## Transformables
Transformables allow storing custom types that aren't natively supported by Core Data.
### Creating a Value Transformer
```swift
import UIKit
@objc(ColorTransformer)
class ColorTransformer: ValueTransformer {
override class func transformedValueClass() -> AnyClass {
return NSData.self
}
override class func allowsReverseTransformation() -> Bool {
return true
}
override func transformedValue(_ value: Any?) -> Any? {
guard let color = value as? UIColor else { return nil }
do {
let data = try NSKeyedArchiver.archivedData(
withRootObject: color,
requiringSecureCoding: true
)
return data
} catch {
print("Failed to transform color: \(error)")
return nil
}
}
override func reverseTransformedValue(_ value: Any?) -> Any? {
guard let data = value as? Data else { return nil }
do {
let color = try NSKeyedUnarchiver.unarchivedObject(
ofClass: UIColor.self,
from: data
)
return color
} catch {
print("Failed to reverse transform color: \(error)")
return nil
}
}
}
```
### Registering the Transformer
```swift
// In your stack setup, before loading stores
ValueTransformer.setValueTransformer(
ColorTransformer(),
forName: NSValueTransformerName("ColorTransformer")
)
```
### Configuring in Data Model
1. Select the attribute
2. Set Type to "Transformable"
3. Set "Custom Class" to your type (e.g., `UIColor`)
4. Set "Transformer" to your transformer name (e.g., `ColorTransformer`)
### Using Transformable Attributes
```swift
class Article: NSManagedObject {
@NSManaged var color: UIColor?
}
// Usage
article.color = .systemBlue
try context.save()
// Retrieval
let color = article.color // UIColor
```
### NSSecureCoding Requirement
Modern Core Data requires secure coding:
```swift
// Make your custom type conform to NSSecureCoding
extension CustomType: NSSecureCoding {
static var supportsSecureCoding: Bool { return true }
func encode(with coder: NSCoder) {
// Encode properties
}
required init?(coder: NSCoder) {
// Decode properties
}
}
```
## Validation
Core Data provides built-in validation that runs before saving.
### Model-Level Validation
Set in Data Model Editor:
**String Validation:**
- Minimum Length
- Maximum Length
- Regular Expression
**Numeric Validation:**
- Minimum Value
- Maximum Value
**Example:**
```
Attribute: name
Type: String
Min Length: 3
Max Length: 100
```
### Code-Level Validation
Override validation methods in your `NSManagedObject` subclass:
```swift
class Article: NSManagedObject {
@NSManaged var name: String?
// Validate before insert
override func validateForInsert() throws {
try super.validateForInsert()
try validateName()
}
// Validate before update
override func validateForUpdate() throws {
try super.validateForUpdate()
try validateName()
}
// Validate before delete
override func validateForDelete() throws {
try super.validateForDelete()
// Example: Can't delete if has related objects
if let attachments = attachments, !attachments.isEmpty {
throw NSError(
domain: "ArticleValidation",
code: 1001,
userInfo: [NSLocalizedDescriptionKey: "Cannot delete article with attachments"]
)
}
}
// Custom validation
private func validateName() throws {
guard let name = name, !name.isEmpty else {
throw NSError(
domain: "ArticleValidation",
code: 1000,
userInfo: [NSLocalizedDescriptionKey: "Name cannot be empty"]
)
}
// Check for protected names
let protectedNames = ["Admin", "System", "Root"]
if protectedNames.contains(name) {
throw NSError(
domain: "ArticleValidation",
code: 1002,
userInfo: [NSLocalizedDescriptionKey: "'\(name)' is a protected name"]
)
}
}
}
```
### Property-Level Validation
```swift
class Article: NSManagedObject {
@NSManaged var name: String?
override func validateName(_ value: AutoreleasingUnsafeMutablePointer<AnyObject?>) throws {
guard let name = value.pointee as? String, !name.isEmpty else {
throw NSError(
domain: "ArticleValidation",
code: 1000,
userInfo: [NSLocalizedDescriptionKey: "Name cannot be empty"]
)
}
}
}
```
### Handling Validation Errors
```swift
do {
try context.save()
} catch let error as NSError {
if error.domain == NSCocoaErrorDomain {
switch error.code {
case NSValidationStringTooShortError:
print("String too short")
case NSValidationStringTooLongError:
print("String too long")
case NSManagedObjectValidationError:
print("Validation failed")
default:
print("Other error: \(error.localizedDescription)")
}
}
}
```
## Lifecycle Events
Override lifecycle methods to perform actions at specific points in an object's life.
### awakeFromInsert()
Called once when object is first inserted into context.
```swift
override func awakeFromInsert() {
super.awakeFromInsert()
// Set default values
setPrimitiveValue(Date(), forKey: #keyPath(Article.creationDate))
setPrimitiveValue(Date(), forKey: #keyPath(Article.lastModified))
setPrimitiveValue(0, forKey: #keyPath(Article.views))
}
```
**Use `setPrimitiveValue` to avoid:**
- KVO notifications
- Marking object as changed
- Infinite loops
### willSave()
Called before every save. Use for updating modification dates or cleaning up.
```swift
override func willSave() {
super.willSave()
// Update modification date
setPrimitiveValue(Date(), forKey: #keyPath(Article.lastModified))
// Delete local files if object is deleted
if isDeleted, let localResource = localResourceURL {
try? FileManager.default.removeItem(at: localResource)
}
}
```
**Caution:** Don't call `save()` inside `willSave()` - infinite loop!
### didSave()
Called after save completes.
```swift
override func didSave() {
super.didSave()
// Post notification, update cache, etc.
NotificationCenter.default.post(
name: .articleDidSave,
object: self
)
}
```
### prepareForDeletion()
Called when object is marked for deletion (before save).
```swift
override func prepareForDeletion() {
super.prepareForDeletion()
// Cancel ongoing operations
downloadTask?.cancel()
// Don't delete files here! Use willSave() instead
// (prepareForDeletion is called even if save is rolled back)
}
```
**Important:** Don't delete files in `prepareForDeletion()`. The deletion might be rolled back, leaving your data inconsistent.
### awakeFromFetch()
Called when object is fetched from store.
```swift
override func awakeFromFetch() {
super.awakeFromFetch()
// Initialize transient properties
setupObservers()
}
```
### Complete Lifecycle Example
```swift
class Article: NSManagedObject {
@NSManaged var name: String?
@NSManaged var creationDate: Date?
@NSManaged var lastModified: Date?
@NSManaged var localResourceURL: URL?
override func awakeFromInsert() {
super.awakeFromInsert()
// Set creation date once
setPrimitiveValue(Date(), forKey: #keyPath(Article.creationDate))
setPrimitiveValue(Date(), forKey: #keyPath(Article.lastModified))
}
override func willSave() {
super.willSave()
// Update modification date on every save
if !isDeleted && changedValues().keys.contains("name") {
setPrimitiveValue(Date(), forKey: #keyPath(Article.lastModified))
}
// Clean up files when deleted
if isDeleted, let url = localResourceURL {
try? FileManager.default.removeItem(at: url)
}
}
override func prepareForDeletion() {
super.prepareForDeletion()
// Cancel ongoing operations
// Don't delete files here!
}
}
```
## Common Pitfalls
### ❌ Not Setting Merge Policy with Constraints
```swift
// Constraint violation will crash
let category = Category(context: context)
category.name = "Duplicate"
try context.save() // CRASH!
```
### ❌ Manually Setting Derived Attributes
```swift
// Derived attributes are read-only
article.categoryName = "Swift" // Ignored!
```
### ❌ Using KVO Methods in Lifecycle Events
```swift
override func awakeFromInsert() {
super.awakeFromInsert()
// ❌ Triggers KVO, marks as changed
self.creationDate = Date()
// ✅ Use primitive values
setPrimitiveValue(Date(), forKey: #keyPath(Article.creationDate))
}
```
### ❌ Deleting Files in prepareForDeletion
```swift
override func prepareForDeletion() {
super.prepareForDeletion()
// ❌ Bad: Deletion might be rolled back
try? FileManager.default.removeItem(at: fileURL)
}
```
### ✅ Correct Approaches
```swift
// Set merge policy
viewContext.mergePolicy = NSMergeByPropertyStoreTrumpMergePolicy
// Let derived attributes compute themselves
article.name = "New Name"
try context.save()
print(article.searchName) // Automatically updated
// Use primitive values in lifecycle events
setPrimitiveValue(Date(), forKey: #keyPath(Article.creationDate))
// Delete files in willSave when isDeleted
override func willSave() {
super.willSave()
if isDeleted {
try? FileManager.default.removeItem(at: fileURL)
}
}
```
## Summary
1. **Use constraints for uniqueness** - Requires NSMergeByPropertyStoreTrumpMergePolicy
2. **Use derived attributes** - Better performance than accessing relationships
3. **Use canonical: for search** - Case and diacritic insensitive
4. **Use transformables for custom types** - With NSSecureCoding
5. **Validate in code** - For complex business rules
6. **Use awakeFromInsert for defaults** - Called once on creation
7. **Use willSave for updates** - Called before every save
8. **Use setPrimitiveValue** - Avoid KVO in lifecycle events
9. **Delete files in willSave** - When isDeleted is true
10. **Don't save in willSave** - Causes infinite loop
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |