Files
skills/public/swiftdata-persistence.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

921 lines
31 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>swiftdata-persistence</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/swiftdata-persistence.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/swiftdata-persistence">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/swiftdata-persistence.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>swiftdata-persistence</h1><p class="lede">Building iOS/macOS apps with local persistence</p><h1>SwiftData Persistence Patterns</h1>
<p><strong>Use this skill when:</strong></p>
<ul><li>Building iOS/macOS apps with local persistence</li><li>Migrating from Core Data to SwiftData</li><li>Implementing data models with relationships</li><li>Querying and filtering persisted data</li><li>Managing model versions and migrations</li></ul>
<h2>Model Definition</h2>
<h3>Basic Model Class</h3>
<p>Define models with <code>@Model</code> macro:</p>
<pre><code class="lang-swift">import SwiftData
@Model
final class Task {
var title: String
var isCompleted: Bool
var createdAt: Date
var dueDate: Date?
init(title: String, isCompleted: Bool = false, dueDate: Date? = nil) {
self.title = title
self.isCompleted = isCompleted
self.createdAt = Date()
self.dueDate = dueDate
}
}</code></pre>
<h3>Relationships</h3>
<p>Define one-to-many and many-to-many relationships:</p>
<pre><code class="lang-swift">@Model
final class Project {
var name: String
var createdAt: Date
// One-to-many: one project has many tasks
@Relationship(deleteRule: .cascade, inverse: \Task.project)
var tasks: [Task] = []
init(name: String) {
self.name = name
self.createdAt = Date()
}
}
@Model
final class Task {
var title: String
var isCompleted: Bool
// Many-to-one: many tasks belong to one project
var project: Project?
// Many-to-many: task can have multiple tags
var tags: [Tag] = []
init(title: String, project: Project? = nil) {
self.title = title
self.isCompleted = false
self.project = project
}
}
@Model
final class Tag {
@Attribute(.unique) var name: String
var tasks: [Task] = []
init(name: String) {
self.name = name
}
}</code></pre>
<h3>Attributes and Constraints</h3>
<p>Use <code>@Attribute</code> for special properties:</p>
<pre><code class="lang-swift">@Model
final class User {
// Unique constraint
@Attribute(.unique) var email: String
// Spotlight indexing
@Attribute(.spotlight) var name: String
// Prevent from being saved
@Transient var temporaryToken: String?
// Custom transformation
@Attribute(.transformable) var metadata: [String: Any]?
// Original property name for migration
@Attribute(originalName: &quot;userName&quot;) var displayName: String
init(email: String, name: String, displayName: String) {
self.email = email
self.name = name
self.displayName = displayName
}
}</code></pre>
<h2>Container Setup</h2>
<h3>App-Level Configuration</h3>
<p>Configure SwiftData container in your app:</p>
<pre><code class="lang-swift">import SwiftUI
import SwiftData
@main
struct TaskApp: App {
var body: some Scene {
WindowGroup {
ContentView()
}
.modelContainer(for: [Task.self, Project.self, Tag.self])
}
}
// With configuration
@main
struct TaskApp: App {
var container: ModelContainer
init() {
let schema = Schema([Task.self, Project.self, Tag.self])
let configuration = ModelConfiguration(
schema: schema,
isStoredInMemoryOnly: false,
allowsSave: true
)
do {
container = try ModelContainer(
for: schema,
configurations: configuration
)
} catch {
fatalError(&quot;Failed to create container: \(error)&quot;)
}
}
var body: some Scene {
WindowGroup {
ContentView()
}
.modelContainer(container)
}
}</code></pre>
<h3>Multiple Containers</h3>
<p>Use separate containers for different data sets:</p>
<pre><code class="lang-swift">@main
struct MultiContainerApp: App {
let userContainer: ModelContainer
let cacheContainer: ModelContainer
init() {
do {
// Persistent user data
userContainer = try ModelContainer(
for: User.self,
configurations: ModelConfiguration(
isStoredInMemoryOnly: false
)
)
// In-memory cache
cacheContainer = try ModelContainer(
for: CachedItem.self,
configurations: ModelConfiguration(
isStoredInMemoryOnly: true
)
)
} catch {
fatalError(&quot;Container creation failed: \(error)&quot;)
}
}
var body: some Scene {
WindowGroup {
ContentView()
.modelContainer(userContainer)
.modelContainer(cacheContainer)
}
}
}</code></pre>
<h2>Querying Data</h2>
<h3>Using @Query in Views</h3>
<p>Fetch data directly in SwiftUI views:</p>
<pre><code class="lang-swift">struct TaskListView: View {
// Fetch all tasks
@Query private var tasks: [Task]
var body: some View {
List(tasks) { task in
TaskRow(task: task)
}
}
}
// With sorting
struct SortedTasksView: View {
@Query(sort: \Task.createdAt, order: .reverse)
private var tasks: [Task]
var body: some View {
List(tasks) { task in
TaskRow(task: task)
}
}
}
// With filter
struct FilteredTasksView: View {
@Query(filter: #Predicate&lt;Task&gt; { task in
task.isCompleted == false
})
private var incompleteTasks: [Task]
var body: some View {
List(incompleteTasks) { task in
TaskRow(task: task)
}
}
}</code></pre>
<h3>Dynamic Predicates</h3>
<p>Use predicates for complex filtering:</p>
<pre><code class="lang-swift">struct ProjectTasksView: View {
let project: Project
@Query private var tasks: [Task]
init(project: Project) {
self.project = project
// Filter tasks by project
let projectId = project.persistentModelID
_tasks = Query(filter: #Predicate&lt;Task&gt; { task in
task.project?.persistentModelID == projectId
})
}
var body: some View {
List(tasks) { task in
TaskRow(task: task)
}
}
}
// Search functionality
struct SearchableTasksView: View {
@State private var searchText = &quot;&quot;
@Query private var allTasks: [Task]
var filteredTasks: [Task] {
if searchText.isEmpty {
return allTasks
}
return allTasks.filter { task in
task.title.localizedStandardContains(searchText)
}
}
var body: some View {
List(filteredTasks) { task in
TaskRow(task: task)
}
.searchable(text: $searchText)
}
}</code></pre>
<h3>FetchDescriptor for Programmatic Queries</h3>
<p>Use <code>FetchDescriptor</code> in view models:</p>
<pre><code class="lang-swift">@Observable
final class TaskViewModel {
var tasks: [Task] = []
var errorMessage: String?
private let modelContext: ModelContext
init(modelContext: ModelContext) {
self.modelContext = modelContext
}
func loadTasks(filter: TaskFilter) async {
let predicate = switch filter {
case .all:
#Predicate&lt;Task&gt; { _ in true }
case .completed:
#Predicate&lt;Task&gt; { $0.isCompleted == true }
case .incomplete:
#Predicate&lt;Task&gt; { $0.isCompleted == false }
case .overdue:
#Predicate&lt;Task&gt; {
$0.dueDate != nil &amp;&amp; $0.dueDate! &lt; Date() &amp;&amp; !$0.isCompleted
}
}
var descriptor = FetchDescriptor&lt;Task&gt;(
predicate: predicate,
sortBy: [SortDescriptor(\.createdAt, order: .reverse)]
)
// Limit results
descriptor.fetchLimit = 100
do {
tasks = try modelContext.fetch(descriptor)
} catch {
errorMessage = error.localizedDescription
}
}
func searchTasks(query: String) async {
let descriptor = FetchDescriptor&lt;Task&gt;(
predicate: #Predicate&lt;Task&gt; {
$0.title.localizedStandardContains(query)
}
)
do {
tasks = try modelContext.fetch(descriptor)
} catch {
errorMessage = error.localizedDescription
}
}
}</code></pre>
<h2>Creating, Updating, Deleting</h2>
<h3>CRUD Operations</h3>
<p>Perform basic operations with <code>ModelContext</code>:</p>
<pre><code class="lang-swift">struct TaskEditorView: View {
@Environment(\.modelContext) private var modelContext
@State private var title = &quot;&quot;
var body: some View {
Form {
TextField(&quot;Task title&quot;, text: $title)
Button(&quot;Create Task&quot;) {
createTask()
}
}
}
private func createTask() {
let task = Task(title: title)
modelContext.insert(task)
// Changes are auto-saved
// Or explicitly save:
do {
try modelContext.save()
} catch {
print(&quot;Failed to save: \(error)&quot;)
}
}
}
// Update
struct TaskDetailView: View {
@Bindable var task: Task
var body: some View {
Form {
TextField(&quot;Title&quot;, text: $task.title)
Toggle(&quot;Completed&quot;, isOn: $task.isCompleted)
}
// Changes auto-saved when view disappears
}
}
// Delete
struct TaskListView: View {
@Environment(\.modelContext) private var modelContext
@Query private var tasks: [Task]
var body: some View {
List {
ForEach(tasks) { task in
TaskRow(task: task)
}
.onDelete(perform: deleteTasks)
}
}
private func deleteTasks(at offsets: IndexSet) {
for index in offsets {
modelContext.delete(tasks[index])
}
}
}</code></pre>
<h3>Batch Operations</h3>
<p>Perform operations on multiple objects:</p>
<pre><code class="lang-swift">@Observable
final class TaskManager {
private let modelContext: ModelContext
init(modelContext: ModelContext) {
self.modelContext = modelContext
}
func completeAll(in project: Project) {
for task in project.tasks {
task.isCompleted = true
}
do {
try modelContext.save()
} catch {
print(&quot;Failed to save: \(error)&quot;)
}
}
func deleteCompleted() {
let descriptor = FetchDescriptor&lt;Task&gt;(
predicate: #Predicate { $0.isCompleted == true }
)
do {
let completed = try modelContext.fetch(descriptor)
for task in completed {
modelContext.delete(task)
}
try modelContext.save()
} catch {
print(&quot;Failed to delete: \(error)&quot;)
}
}
func archiveOldProjects() {
let cutoffDate = Calendar.current.date(
byAdding: .month,
value: -6,
to: Date()
)!
let descriptor = FetchDescriptor&lt;Project&gt;(
predicate: #Predicate { $0.createdAt &lt; cutoffDate }
)
do {
let oldProjects = try modelContext.fetch(descriptor)
for project in oldProjects {
project.isArchived = true
}
try modelContext.save()
} catch {
print(&quot;Failed to archive: \(error)&quot;)
}
}
}</code></pre>
<h2>Relationships and Cascading</h2>
<h3>Working with Relationships</h3>
<p>Manage related objects:</p>
<pre><code class="lang-swift">@Observable
final class ProjectManager {
private let modelContext: ModelContext
init(modelContext: ModelContext) {
self.modelContext = modelContext
}
func createProjectWithTasks(name: String, taskTitles: [String]) {
let project = Project(name: name)
modelContext.insert(project)
for title in taskTitles {
let task = Task(title: title, project: project)
modelContext.insert(task)
// Relationship automatically maintained
}
do {
try modelContext.save()
} catch {
print(&quot;Failed to save: \(error)&quot;)
}
}
func moveTask(_ task: Task, to project: Project) {
task.project = project
// SwiftData handles relationship updates
}
func addTag(_ tag: Tag, to task: Task) {
if !task.tags.contains(where: { $0.name == tag.name }) {
task.tags.append(tag)
}
}
}</code></pre>
<h3>Delete Rules</h3>
<p>Understand cascade deletion:</p>
<pre><code class="lang-swift">@Model
final class Project {
var name: String
// Cascade: deleting project deletes all tasks
@Relationship(deleteRule: .cascade)
var tasks: [Task] = []
// Nullify: deleting project sets task.project to nil
@Relationship(deleteRule: .nullify)
var owner: User?
// Deny: cannot delete project if it has tasks
@Relationship(deleteRule: .deny)
var criticalDependencies: [Dependency] = []
init(name: String) {
self.name = name
}
}</code></pre>
<h2>Model Versioning and Migration</h2>
<h3>Schema Versions</h3>
<p>Handle model changes:</p>
<pre><code class="lang-swift">// Version 1
@Model
final class Task {
var title: String
var isCompleted: Bool
init(title: String) {
self.title = title
self.isCompleted = false
}
}
// Version 2 - Added priority
@Model
final class Task {
var title: String
var isCompleted: Bool
var priority: Int // New property
init(title: String, priority: Int = 0) {
self.title = title
self.isCompleted = false
self.priority = priority
}
}
// SwiftData handles lightweight migrations automatically
// For complex changes, define custom migration:
enum TaskMigrationPlan: SchemaMigrationPlan {
static var schemas: [VersionedSchema.Type] {
[TaskSchemaV1.self, TaskSchemaV2.self]
}
static var stages: [MigrationStage] {
[migrateV1toV2]
}
static let migrateV1toV2 = MigrationStage.custom(
fromVersion: TaskSchemaV1.self,
toVersion: TaskSchemaV2.self,
willMigrate: { context in
// Pre-migration setup
},
didMigrate: { context in
// Set default priority for existing tasks
let descriptor = FetchDescriptor&lt;Task&gt;()
let tasks = try context.fetch(descriptor)
for task in tasks {
task.priority = 0
}
try context.save()
}
)
}</code></pre>
<h2>Background Operations</h2>
<h3>Background Context</h3>
<p>Perform heavy operations off the main thread:</p>
<pre><code class="lang-swift">actor DataImporter {
private let modelContainer: ModelContainer
init(modelContainer: ModelContainer) {
self.modelContainer = modelContainer
}
func importTasks(from url: URL) async throws {
// Create background context
let context = ModelContext(modelContainer)
// Parse CSV or JSON
let taskData = try parseFile(at: url)
// Insert in batches
for batch in taskData.chunked(into: 100) {
for data in batch {
let task = Task(
title: data.title,
isCompleted: data.isCompleted
)
context.insert(task)
}
try context.save()
}
}
func exportTasks() async throws -&gt; Data {
let context = ModelContext(modelContainer)
let descriptor = FetchDescriptor&lt;Task&gt;(
sortBy: [SortDescriptor(\.createdAt)]
)
let tasks = try context.fetch(descriptor)
// Convert to exportable format
return try JSONEncoder().encode(tasks.map { task in
TaskExportData(
title: task.title,
isCompleted: task.isCompleted,
createdAt: task.createdAt
)
})
}
}</code></pre>
<h2>Testing with SwiftData</h2>
<h3>In-Memory Container for Tests</h3>
<p>Use in-memory storage for tests:</p>
<pre><code class="lang-swift">import Testing
import SwiftData
@Test
func testTaskCreation() async throws {
// Create in-memory container
let config = ModelConfiguration(isStoredInMemoryOnly: true)
let container = try ModelContainer(
for: Task.self,
configurations: config
)
let context = ModelContext(container)
// Test operations
let task = Task(title: &quot;Test Task&quot;)
context.insert(task)
try context.save()
let descriptor = FetchDescriptor&lt;Task&gt;()
let tasks = try context.fetch(descriptor)
#expect(tasks.count == 1)
#expect(tasks.first?.title == &quot;Test Task&quot;)
}
@Test
func testTaskCompletion() async throws {
let container = try ModelContainer(
for: Task.self,
configurations: ModelConfiguration(isStoredInMemoryOnly: true)
)
let context = ModelContext(container)
let task = Task(title: &quot;Test&quot;)
context.insert(task)
task.isCompleted = true
try context.save()
#expect(task.isCompleted == true)
}</code></pre>
<h2>Anti-Patterns to Avoid</h2>
<p><strong>DON&#x27;T fetch in loops:</strong></p>
<pre><code class="lang-swift">// ❌ BAD - Multiple fetches
for projectId in projectIds {
let descriptor = FetchDescriptor&lt;Project&gt;(
predicate: #Predicate { $0.id == projectId }
)
let project = try context.fetch(descriptor).first
}
// ✅ GOOD - Single fetch
let descriptor = FetchDescriptor&lt;Project&gt;(
predicate: #Predicate { projectIds.contains($0.id) }
)
let projects = try context.fetch(descriptor)</code></pre>
<p><strong>DON&#x27;T ignore relationship delete rules:</strong></p>
<pre><code class="lang-swift">// ❌ BAD - Manual deletion
for task in project.tasks {
context.delete(task)
}
context.delete(project)
// ✅ GOOD - Use cascade
@Relationship(deleteRule: .cascade)
var tasks: [Task] = []
// Then just:
context.delete(project) // Tasks deleted automatically</code></pre>
<p><strong>DON&#x27;T use main context for heavy operations:</strong></p>
<pre><code class="lang-swift">// ❌ BAD - Blocks UI
func importData() {
for item in largeDataset {
let task = Task(title: item.title)
modelContext.insert(task)
}
}
// ✅ GOOD - Background context
func importData() async {
let context = ModelContext(modelContainer)
for item in largeDataset {
let task = Task(title: item.title)
context.insert(task)
}
try? context.save()
}</code></pre>
<h2>Related Skills</h2>
<ul><li><strong>swiftui-architecture.md</strong> - Using SwiftData in view models</li><li><strong>swift-concurrency.md</strong> - Async operations with SwiftData</li><li><strong>ios-testing.md</strong> - Testing SwiftData models</li><li><strong>swiftui-navigation.md</strong> - Passing models through navigation</li></ul>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/swiftdata-persistence.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>