Configure & Open a Realm - Swift SDK
On this page
- Key Concept: Realm Files
- In-Memory Realms
- Default Realm
- Open a Realm Without Sync
- Open a Default Realm or Realm at a File URL
- Open an In-Memory Realm
- Close a Realm
- Handle Errors When Accessing a Realm
- Provide a Subset of Classes to a Realm
- Initialize Properties Using Realm APIs
- Use Realm When the Device Is Locked
A realm is the core data structure used to organize data in Realm Database. A realm is a collection of the objects that you use in your application, called Realm objects, as well as additional metadata that describe the objects. To learn how to define a Realm object, see Define an Object Model.
When you open a realm, you can pass a Realm.Configuration that specifies additional details about how to configure the realm file. This includes things like:
Pass a fileURL or in-memory identifier to customize how the realm is stored on device
Provide a logged-in user and Sync details to use Sync with the realm
Specify the realm use only a subset of your app's classes
Whether and when to compact a realm to reduce its file size
Pass an encryption key to encrypt a realm
Provide a schema version or migration block when making schema changes
Tip
See also:
This page covers how to open a realm file that does not sync data. If you'd like to use Device Sync to sync data with other devices, see: Configure & Open a Synced Realm.
Key Concept: Realm Files
Realm Database stores a binary encoded version of every object and type in a
realm in a single .realm
file. The file is located at a specific
path that you can define when you open the
realm. You can open, view, and edit the contents of these files with
Realm Studio.
Tip
See: Auxiliary Realm Files
Realm Database creates additional files for each realm.
To learn more about these files, see Realm Database Internals. Deleting these files has important implications.
For more information about deleting .realm
or auxiliary files, see:
Delete a Realm
In-Memory Realms
You can also open a realm entirely in memory, which does not create a .realm
file or its associated auxiliary files. Instead the SDK stores objects in memory
while the realm is open and discards them immediately when all instances are
closed.
Tip
See: Open an In-Memory Realm
To open an in-memory realm, see Open an In-Memory Realm.
Default Realm
Calling Realm() or
RLMRealm opens the default realm.
This method returns a realm object that maps to a file named
default.realm
. You can find this file:
iOS: in the Documents folder of your app
macOS: in the Application Support folder of your app
Tip
See: Open a Default Realm
To open a default realm, see Open a Default Realm or Realm at a File URL.
Open a Realm Without Sync
You can open a non-synced local realm with several different configuration options:
No configuration - i.e. default configuration
Specify a file URL for the realm
Open the realm only in memory, without saving a file to the file system
Copy a synced realm to use without Sync
Open a Default Realm or Realm at a File URL
Open an In-Memory Realm
You can open a realm entirely in memory, which will not create a
.realm
file or its associated auxiliary files. Instead the SDK stores objects in memory while the
realm is open and discards them immediately when all instances are
closed.
Important
When all in-memory realm instances with a particular identifier go out of scope, Realm Database deletes all data in that realm. To avoid this, hold onto a strong reference to any in-memory realms during your app's lifetime.
Close a Realm
There is no need to manually close a realm in Swift or Objective-C. When a realm goes out of scope and is removed from memory due to ARC, the realm is closed.
Handle Errors When Accessing a Realm
Provide a Subset of Classes to a Realm
Tip
Operating with Low Memory Constraints
Some applications, such as watchOS apps and iOS app extensions, have tight constraints on their memory footprints. To optimize your data model for low-memory environments, open the realm with a subset of classes.
Initialize Properties Using Realm APIs
You might define properties whose values are initialized using Realm Database APIs. For example:
class SomeSwiftType { let persons = try! Realm().objects(Person.self) // ... }
If this initialization code runs before you set up your Realm
configurations, you might get unexpected behavior. For example, if you
set a migration block for the default realm
configuration in applicationDidFinishLaunching()
, but you create an
instance of SomeSwiftType
before
applicationDidFinishLaunching()
, you might be accessing your
realm before it has been correctly configured.
To avoid such issues, consider doing one of the following:
Defer instantiation of any type that eagerly initializes properties using Realm Database APIs until after your app has completed setting up its realm configurations.
Define your properties using Swift's
lazy
keyword. This allows you to safely instantiate such types at any time during your application's lifecycle, as long as you do not attempt to access yourlazy
properties until after your app has set up its realm configurations.Only initialize your properties using Realm APIs that explicitly take in user-defined configurations. You can be sure that the configuration values you are using have been set up properly before they are used to open realms.
Use Realm When the Device Is Locked
By default, iOS 8 and above encrypts app files using
NSFileProtection
whenever the device is locked. If your app attempts
to access a realm while the device is locked, you might see the
following error:
open() failed: Operation not permitted
To handle this, downgrade the file protection of the folder containing the Realm files. A less strict protection level like NSFileProtectionCompleteUntilFirstUserAuthentication allows file access even when the device is locked.
Tip
If you reduce iOS file encryption, consider using Realm's built-in encryption to secure your data instead.
This example shows how to apply a less strict protection level to the parent directory of the default realm.
let realm = try! Realm() // Get the realm file's parent directory let folderPath = realm.configuration.fileURL!.deletingLastPathComponent().path // Disable file protection for this directory after the user has unlocked the device once try! FileManager.default.setAttributes([FileAttributeKey.protectionKey: FileProtectionType.completeUntilFirstUserAuthentication], ofItemAtPath: folderPath)
Realm may create and delete auxiliary files at any time. Instead of downgrading file protection on the files, apply it to the parent folder. This way, the file protection applies to all relevant files regardless of creation time.