Realm Persistence
Relevant source files
The following files were used as context for generating this wiki page:
Realm Persistence in the putio-ios project serves as the primary local database for storing user sessions, application configurations, and download states. The system leverages the Realm Swift framework to provide a performant, object-oriented database that supports reactive UI updates and complex data migrations across app versions.
The persistence layer is centered around the PutioRealm helper class, which manages initialization, schema migrations, and high-level operations like user session replacement. It ensures data consistency between the local cache and the remote put.io API while handling edge cases such as incompatible database formats during upgrades.
Sources: Putio/Common/Helpers/Realm.swift, Putio/AppDelegate.swift:51
Core Data Models
The application defines several specialized Realm Object subclasses to represent the persistent state of the user and their activities.
Data Model Schema
| Class | Primary Key | Purpose |
|---|---|---|
User | id | Stores core user identity, email, and associated settings/disk info. |
UserDisk | N/A | Represents storage quotas and current usage metrics. |
UserSettings | N/A | Persists preferences like sorting, history status, and subtitle behavior. |
UserConfig | N/A | Application-level configurations (e.g., Chromecast playback type). |
Download | id | Tracks file downloads, including state, progress, and file metadata. |
Sources: Putio/Common/Models/UserModel.swift:7-70, Putio/Features/Downloads/DownloadModel.swift:7-54
The relationship between these entities is structured to maintain a single user session:
Initialization and Configuration
The PutioRealm class handles the global setup of the Realm environment during app launch.
Database Setup
The setup() function is called in AppDelegate to initialize the default Realm configuration. If an incompatible database format is detected (specifically an upgrade from Realm 3.x to 10.x), the system automatically deletes the old database and sets a recovery flag to rebuild records from UserDefaults.
Sources: Putio/Common/Helpers/Realm.swift:80-108, Putio/AppDelegate.swift:51
Schema Migration
The system uses versioned migrations to update the database schema without losing user data. The current schema version is 12.
| Version | Key Changes |
|---|---|
| < 1 | Enumerate Download objects to set default fileTypeRaw. |
| < 7 | Map UserDisk objects to User and initialize storage usage fields. |
| < 10 | Introduce twoFactorEnabled setting. |
| < 12 | Perform migrateDownloadRawColumns to handle legacy state and file type enums. |
Sources: Putio/Common/Helpers/Realm.swift:113-162
Data Recovery Mechanisms
A critical feature of the persistence layer is its ability to recover download records if the Realm database is deleted or corrupted.
The recovery logic utilizes file references (HLS bookmarks for video or relative paths for audio) preserved in UserDefaults to reconstruct Download objects. Placeholders are initially created with the name "Recovering..." and later enriched with actual metadata via the put.io API.
Sources: Putio/Common/Helpers/Realm.swift:200-247, Putio/Common/Helpers/Realm.swift:330-363
User Session Management
User sessions are managed through the replaceUserSession function. This operation is designed to be atomic: it deletes existing user data and adds new User and UserConfig objects within a single write transaction.
Persistence Utilities
The project includes several utility functions and classes to streamline Realm interactions:
- Thread-Safe Opening:
PutioRealm.open(context:configuration:)provides a safe way to initialize Realm instances with error logging and context tracking. - Write Wrappers:
PutioRealm.write(_:context:updates:)wraps Realm's standard write transactions to provide unified error handling and logging. - Playback Position Tracking: The
VideoPlaybackPositionStore(referenced in tests) usesUserDefaultsfor lightweight persistence of media seek times, separate from the primary Realm database.
Sources: Putio/Common/Helpers/Realm.swift:54-68, Putio/Features/Downloads/DownloadSupport.swift:7-14, PutioTests/PutioRealmTests.swift:129-141
Conclusion
Realm Persistence in putio-ios provides a robust foundation for offline data availability and session management. By combining standard Realm features with custom migration paths and a UserDefaults-backed recovery system, the application ensures that user data—especially ongoing and completed downloads—remains resilient even through significant infrastructure upgrades or local database failures.