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/persistent-history.md
View on GitHub# Persistent History Tracking
Persistent history tracking enables Core Data to track changes across contexts, app extensions, and batch operations. This is essential for keeping your UI synchronized and supporting multi-target apps.
## Why Persistent History Tracking?
**Without persistent history tracking:**
- Batch operations don't update UI
- App extensions can't notify main app of changes
- Multiple contexts don't stay synchronized
**With persistent history tracking:**
- All changes are recorded in a transaction log
- Changes can be merged into any context
- Works across app targets (main app, extensions, etc.)
## Enabling Persistent History Tracking
### In NSPersistentContainer
```swift
class PersistentContainer: NSPersistentContainer {
override init(name: String, managedObjectModel model: NSManagedObjectModel) {
super.init(name: name, managedObjectModel: model)
guard let description = persistentStoreDescriptions.first else {
fatalError("No store description")
}
// Enable persistent history tracking
description.setOption(true as NSNumber,
forKey: NSPersistentHistoryTrackingKey)
// Enable remote change notifications
description.setOption(true as NSNumber,
forKey: NSPersistentStoreRemoteChangeNotificationPostOptionKey)
loadPersistentStores { description, error in
if let error = error {
fatalError("Failed to load store: \(error)")
}
}
}
}
```
### For App Groups (Extensions)
```swift
let storeURL = FileManager.default.containerURL(
forSecurityApplicationGroupIdentifier: "group.com.example.app"
)?.appendingPathComponent("Shared.sqlite")
let description = NSPersistentStoreDescription(url: storeURL!)
description.setOption(true as NSNumber, forKey: NSPersistentHistoryTrackingKey)
description.setOption(true as NSNumber, forKey: NSPersistentStoreRemoteChangeNotificationPostOptionKey)
container.persistentStoreDescriptions = [description]
```
## The Four Components
Persistent history tracking typically involves four components:
1. **Observer** - Listens for remote change notifications
2. **Fetcher** - Retrieves relevant transactions
3. **Merger** - Merges transactions into view context
4. **Cleaner** - Removes old transactions
## 1. Observer: Listening for Changes
```swift
final class PersistentHistoryObserver {
private let coordinator: NSPersistentStoreCoordinator
private let historyContext: NSManagedObjectContext
private let merger: PersistentHistoryMerger
init(container: NSPersistentContainer, viewContext: NSManagedObjectContext) {
self.coordinator = container.persistentStoreCoordinator
self.historyContext = container.newBackgroundContext()
self.historyContext.name = "PersistentHistoryContext"
self.historyContext.transactionAuthor = "PersistentHistory"
self.merger = PersistentHistoryMerger(historyContext: historyContext, viewContext: viewContext)
NotificationCenter.default.addObserver(
self,
selector: #selector(processStoreRemoteChanges),
name: .NSPersistentStoreRemoteChange,
object: coordinator
)
}
@objc private func processStoreRemoteChanges(_ notification: Notification) {
merger.merge()
}
deinit {
NotificationCenter.default.removeObserver(self)
}
}
```
## 2. Fetcher: Retrieving Transactions
```swift
class PersistentHistoryFetcher {
private let context: NSManagedObjectContext
private let lastToken: NSPersistentHistoryToken?
init(context: NSManagedObjectContext, lastToken: NSPersistentHistoryToken?) {
self.context = context
self.lastToken = lastToken
}
func fetch() throws -> [NSPersistentHistoryTransaction] {
let fetchRequest = createFetchRequest()
guard let historyResult = try context.execute(fetchRequest) as? NSPersistentHistoryResult,
let transactions = historyResult.result as? [NSPersistentHistoryTransaction] else {
return []
}
return transactions
}
private func createFetchRequest() -> NSPersistentHistoryChangeRequest {
let request: NSPersistentHistoryChangeRequest
if let token = lastToken {
request = NSPersistentHistoryChangeRequest.fetchHistory(after: token)
} else {
request = NSPersistentHistoryChangeRequest.fetchHistory(after: Date.distantPast)
}
// Filter out transactions from this app target
if let fetchRequest = request.fetchRequest {
fetchRequest.predicate = NSPredicate(
format: "author != %@",
"MainApp" // Your app's transaction author
)
}
return request
}
}
```
## 3. Merger: Applying Changes
```swift
final class PersistentHistoryMerger {
private let historyContext: NSManagedObjectContext
private let viewContext: NSManagedObjectContext
private var lastToken: NSPersistentHistoryToken?
init(historyContext: NSManagedObjectContext, viewContext: NSManagedObjectContext) {
self.historyContext = historyContext
self.viewContext = viewContext
self.lastToken = loadLastToken()
}
func merge() {
historyContext.perform {
do {
let fetcher = PersistentHistoryFetcher(
context: self.historyContext,
lastToken: self.lastToken
)
let transactions = try fetcher.fetch()
guard !transactions.isEmpty else { return }
self.viewContext.perform {
self.mergeTransactions(transactions)
}
if let newToken = transactions.last?.token {
self.lastToken = newToken
self.saveLastToken(newToken)
}
} catch {
print("Failed to merge history: \(error)")
}
}
}
private func mergeTransactions(_ transactions: [NSPersistentHistoryTransaction]) {
for transaction in transactions {
guard let userInfo = transaction.objectIDNotification().userInfo else { continue }
NSManagedObjectContext.mergeChanges(fromRemoteContextSave: userInfo, into: [viewContext])
}
}
private func loadLastToken() -> NSPersistentHistoryToken? {
guard let data = UserDefaults.standard.data(forKey: "lastHistoryToken") else {
return nil
}
return try? NSKeyedUnarchiver.unarchivedObject(
ofClass: NSPersistentHistoryToken.self,
from: data
)
}
private func saveLastToken(_ token: NSPersistentHistoryToken) {
if let data = try? NSKeyedArchiver.archivedData(
withRootObject: token,
requiringSecureCoding: true
) {
UserDefaults.standard.set(data, forKey: "lastHistoryToken")
}
}
}
```
## 4. Cleaner: Removing Old Transactions
```swift
class PersistentHistoryCleaner {
private let context: NSManagedObjectContext
private let targets: [AppTarget]
enum AppTarget {
case mainApp
case shareExtension
case widgetExtension
var lastTokenKey: String {
switch self {
case .mainApp: return "mainApp.lastHistoryToken"
case .shareExtension: return "shareExtension.lastHistoryToken"
case .widgetExtension: return "widgetExtension.lastHistoryToken"
}
}
}
init(context: NSManagedObjectContext, targets: [AppTarget]) {
self.context = context
self.targets = targets
}
func clean() {
context.perform {
// Find the oldest token across all targets
guard let oldestToken = self.findOldestToken() else { return }
// Delete history before that token
let deleteRequest = NSPersistentHistoryChangeRequest.deleteHistory(before: oldestToken)
do {
try self.context.execute(deleteRequest)
} catch {
print("Failed to clean history: \(error)")
}
}
}
private func findOldestToken() -> NSPersistentHistoryToken? {
var oldestDate: Date?
var oldestToken: NSPersistentHistoryToken?
for target in targets {
guard let token = loadToken(for: target) else { continue }
// Get timestamp from token (requires fetching transaction)
let historyRequest = NSPersistentHistoryChangeRequest.fetchHistory(after: token)
historyRequest.fetchRequest?.fetchLimit = 1
guard let result = try? context.execute(historyRequest) as? NSPersistentHistoryResult,
let transactions = result.result as? [NSPersistentHistoryTransaction],
let transaction = transactions.first else {
continue
}
let date = transaction.timestamp
if oldestDate == nil || date < oldestDate! {
oldestDate = date
oldestToken = token
}
}
return oldestToken
}
private func loadToken(for target: AppTarget) -> NSPersistentHistoryToken? {
guard let data = UserDefaults.standard.data(forKey: target.lastTokenKey) else {
return nil
}
return try? NSKeyedUnarchiver.unarchivedObject(
ofClass: NSPersistentHistoryToken.self,
from: data
)
}
}
```
## Complete Integration Example
```swift
class CoreDataStack {
static let shared = CoreDataStack()
lazy var persistentContainer: NSPersistentContainer = {
let container = NSPersistentContainer(name: "Model")
// Configure store
guard let description = container.persistentStoreDescriptions.first else {
fatalError("No store description")
}
// Enable persistent history tracking
description.setOption(true as NSNumber, forKey: NSPersistentHistoryTrackingKey)
description.setOption(true as NSNumber, forKey: NSPersistentStoreRemoteChangeNotificationPostOptionKey)
container.loadPersistentStores { description, error in
if let error = error {
fatalError("Failed to load store: \(error)")
}
self.setupHistoryTracking(container: container)
}
// Configure view context
container.viewContext.automaticallyMergesChangesFromParent = true
container.viewContext.name = "ViewContext"
container.viewContext.transactionAuthor = "MainApp"
return container
}()
private var historyObserver: PersistentHistoryObserver?
private init() {}
private func setupHistoryTracking(container: NSPersistentContainer) {
historyObserver = PersistentHistoryObserver(container: container, viewContext: container.viewContext)
cleanHistoryPeriodically(container: container)
}
private func cleanHistoryPeriodically(container: NSPersistentContainer) {
Timer.scheduledTimer(withTimeInterval: 3600, repeats: true) { _ in
let context = container.newBackgroundContext()
let cleaner = PersistentHistoryCleaner(
context: context,
targets: [.mainApp, .shareExtension]
)
cleaner.clean()
}
}
}
```
## Transaction Authors
Set unique transaction authors for each app target:
```swift
// Main app
viewContext.transactionAuthor = "MainApp"
// Share extension
viewContext.transactionAuthor = "ShareExtension"
// Widget extension
viewContext.transactionAuthor = "WidgetExtension"
```
**Why this matters:**
- Filter out your own transactions (avoid redundant merges)
- Identify which target made changes
- Debug multi-target issues
## Filtering Transactions
### By Author
```swift
let fetchRequest = NSPersistentHistoryChangeRequest.fetchHistory(after: lastToken)
if let request = fetchRequest.fetchRequest {
request.predicate = NSPredicate(format: "author != %@", "MainApp")
}
```
### By Date
```swift
let cutoffDate = Calendar.current.date(byAdding: .day, value: -7, to: Date())!
let fetchRequest = NSPersistentHistoryChangeRequest.fetchHistory(after: cutoffDate)
```
### By Entity
```swift
let fetchRequest = NSPersistentHistoryChangeRequest.fetchHistory(after: lastToken)
if let request = fetchRequest.fetchRequest {
request.predicate = NSPredicate(format: "ANY changes.changedObjectID.entity.name == %@", "Article")
}
```
## Batch Operations Integration
Persistent history tracking is **required** for batch operations to update the UI:
```swift
// 1. Enable persistent history tracking
description.setOption(true as NSNumber, forKey: NSPersistentHistoryTrackingKey)
// 2. Perform batch operation
let context = container.newBackgroundContext()
context.perform {
let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { object in
// Insert logic
return false
}
try? context.execute(batchInsert)
}
// 3. UI updates automatically via persistent history tracking
// The observer detects the change and merges it into the view context
```
## Testing Persistent History
```swift
func testPersistentHistory() throws {
// Enable persistent history
let description = container.persistentStoreDescriptions.first!
description.setOption(true as NSNumber, forKey: NSPersistentHistoryTrackingKey)
// Create object in background
let backgroundContext = container.newBackgroundContext()
backgroundContext.transactionAuthor = "Test"
let expectation = XCTestExpectation(description: "Save")
backgroundContext.perform {
let article = Article(context: backgroundContext)
article.name = "Test"
try? backgroundContext.save()
expectation.fulfill()
}
wait(for: [expectation], timeout: 5.0)
// Fetch history
let fetchRequest = NSPersistentHistoryChangeRequest.fetchHistory(after: Date.distantPast)
let result = try container.viewContext.execute(fetchRequest) as? NSPersistentHistoryResult
let transactions = result?.result as? [NSPersistentHistoryTransaction]
XCTAssertNotNil(transactions)
XCTAssertFalse(transactions!.isEmpty)
}
```
## Common Pitfalls
### ❌ Not Enabling Remote Change Notifications
```swift
// Only this isn't enough
description.setOption(true as NSNumber, forKey: NSPersistentHistoryTrackingKey)
// Need both!
description.setOption(true as NSNumber, forKey: NSPersistentHistoryTrackingKey)
description.setOption(true as NSNumber, forKey: NSPersistentStoreRemoteChangeNotificationPostOptionKey)
```
### ❌ Not Filtering Own Transactions
```swift
// Merges own transactions (redundant)
let fetchRequest = NSPersistentHistoryChangeRequest.fetchHistory(after: lastToken)
```
### ❌ Not Cleaning Old Transactions
```swift
// History grows unbounded, wastes space
// Always implement cleaning!
```
### ❌ Not Setting Transaction Authors
```swift
// Can't filter transactions by source
context.transactionAuthor = nil // Bad!
```
### ✅ Correct Approach
```swift
// 1. Enable both options
description.setOption(true as NSNumber, forKey: NSPersistentHistoryTrackingKey)
description.setOption(true as NSNumber, forKey: NSPersistentStoreRemoteChangeNotificationPostOptionKey)
// 2. Set transaction author
context.transactionAuthor = "MainApp"
// 3. Filter own transactions
fetchRequest.predicate = NSPredicate(format: "author != %@", "MainApp")
// 4. Clean periodically
let cleaner = PersistentHistoryCleaner(context: context, targets: [.mainApp, .shareExtension])
cleaner.clean()
```
## Performance Considerations
### Clean History Regularly
```swift
// Clean daily
Timer.scheduledTimer(withTimeInterval: 86400, repeats: true) { _ in
cleaner.clean()
}
// Or on app launch
func applicationDidFinishLaunching() {
cleaner.clean()
}
```
### Limit Fetch Range
```swift
// Don't fetch all history
let sevenDaysAgo = Calendar.current.date(byAdding: .day, value: -7, to: Date())!
let fetchRequest = NSPersistentHistoryChangeRequest.fetchHistory(after: sevenDaysAgo)
```
### Batch Merge Changes
```swift
// Merge multiple transactions at once
let transactions = try fetcher.fetch()
for transaction in transactions {
let userInfo = transaction.objectIDNotification().userInfo
NSManagedObjectContext.mergeChanges(
fromRemoteContextSave: userInfo!,
into: [viewContext]
)
}
```
## Summary
1. **Enable persistent history tracking** - Required for batch operations and multi-target apps
2. **Enable remote change notifications** - Required for cross-context updates
3. **Set transaction authors** - Identify change sources
4. **Filter own transactions** - Avoid redundant merges
5. **Implement all four components** - Observer, Fetcher, Merger, Cleaner
6. **Clean history regularly** - Prevent unbounded growth
7. **Use with batch operations** - Essential for UI updates
8. **Test thoroughly** - Verify history tracking works across targets
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 |