Configure & Open a Realm - Swift SDK

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

@MainActor
func mainThreadFunction() async throws {
    // These are identical: the async init produces a
    // MainActor-isolated Realm if no actor is supplied
    let realm1 = try await Realm()
    let realm2 = try await Realm(actor: MainActor.shared)
    
    try await useTheRealm(realm: realm1)
}

actor RealmActor {
    // An implicitly-unwrapped optional is used here to let us pass `self` to
    // `Realm(actor:)` within `init`
    var realm: Realm!
    init() async throws {
        realm = try await Realm(actor: self)
    }
    var count: Int {
        realm.objects(Todo.self).count
    }
    
    func createTodo(name: String, owner: String, status: String) async throws {
        try await realm.asyncWrite {
            realm.create(Todo.self, value: [
                "_id": ObjectId.generate(),
                "name": name,
                "owner": owner,
                "status": status
            ])
        }
    }
    
    func updateTodo(_id: ObjectId, name: String, owner: String, status: String) async throws {
        try await realm.asyncWrite {
            realm.create(Todo.self, value: [
                "_id": _id,
                "name": name,
                "owner": owner,
                "status": status
            ], update: .modified)
        }
    }
    
    func deleteTodo(todo: Todo) async throws {
        try await realm.asyncWrite {
            realm.delete(todo)
        }
    }
    
    func close() {
        realm = nil
    }
    
}

// A simple example of a custom global actor
@globalActor actor BackgroundActor: GlobalActor {
    static var shared = BackgroundActor()
}
@BackgroundActor
func backgroundThreadFunction() async throws {
    // Explicitly specifying the actor is required for anything that is not MainActor
    let realm = try await Realm(actor: BackgroundActor.shared)
    try await realm.asyncWrite {
        _ = realm.create(Todo.self, value: [
            "name": "Pledge fealty and service to Gondor",
            "owner": "Pippin",
            "status": "In Progress"
        ])
    }
    // Thread-confined Realms would sometimes throw an exception here, as we
    // may end up on a different thread after an `await`
    let todoCount = realm.objects(Todo.self).count
    print("The number of Realm objects is: \(todoCount)")
}
@MainActor
func mainThreadFunction() async throws {
    try await backgroundThreadFunction()
}

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

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 your lazy 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.

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.