Realm Swift

On-device object database for Apple platforms (also cross-platform: Kotlin/.NET/Dart). The deep API reference — models, configuration, CRUD, queries, SwiftUI integration, async writes, notifications, migrations, threading, and best practices — lives in references/guide.md. This file is the decision and discipline layer: read it first, open the guide for specifics.

Status, read this first. Realm Swift is a third-party SDK (Realm → MongoDB) now in community-maintained mode: the local database still works and ships in production, but it gets no active feature investment, and Atlas Device Sync (the cloud sync layer) is end-of-life. For a new Apple-only app, default to SwiftData (first-party, Apple-native — use the swiftdata skill). Choose Realm only with a real reason: maintaining an existing Realm app, cross-platform model parity, or a feature SwiftData lacks. Name the reason before adding the dependency.

Dials

Set these explicitly at the start; they change what "correct" means.

1. WHY_REALM — legacy (maintaining an existing Realm app) · cross-platform (shared model with Kotlin/.NET/Dart) · feature-gap (need something SwiftData lacks). If none apply, stop and use swiftdata instead. No "we already know Realm" — that's not a reason for a new Apple-only app.
2. CONCURRENCY — main-only (all Realm access on @MainActor, default — simplest, no thread bugs) · actors (actor-isolated Realms via await Realm() + observe(on:)) · gcd (manual DispatchQueue + per-thread Realm + autoreleasepool — only for heavy batch writes).
3. ENCRYPTION — none (default) · encrypted (64-byte key in Realm.Configuration(encryptionKey:), key stored in Keychain, never in code/UserDefaults). Turn on for any sensitive user data.

When to use

Building or reviewing Realm models, transactions, queries, SwiftUI data binding, migrations, or threading. If the app is new and Apple-only, first confirm WHY_REALM is satisfied — otherwise route to the swiftdata skill before writing any Realm code.

Core rules