Bundle a Realm File - Swift SDK
On this page
Swift SDK version 10.23.0 introduced the ability to bundle synchronized realms. Before version 10.23.0, you could only bundle local realms.
Realm supports bundling realm files. When you bundle a realm file, you include a database and all of its data in your application download.
This allows users to start applications for the first time with a set of initial data. For synced realms, bundling can avoid a lengthy initial download the first time a user opens your application. Instead, users need only download the synced changes that occurred since you generated the bundled file.
If your application has enabled advanced backend compaction by configuring a client maximum offline time, users could experience a client reset the first time they open the bundled realm file. This can happen if:
- the bundled realm file was generated more than client maximum offline time days before the user syncs the realm for the first time.
Users experiencing a client reset download the full state of the realm from the application backend. This negates the advantages of bundling a realm file. To prevent client resets and preserve the advantages of realm file bundling:
- Avoid using a client maximum offline time in applications that bundle a synchronized realm.
- If your application does use a client maximum offline time, ensure that your application download always includes a recently synced realm file. Generate a new file each application version, and ensure that no version ever stays current for more than client maximum offline time number of days.
Overview
To create and bundle a realm file with your application:
- Create a realm file that contains the data you'd like to bundle.
- Bundle the realm file in your production application.
- In your production application, open the realm from the bundled asset file. For synced realms, you must supply the partition key.
Create a Realm File for Bundling
- Build a temporary realm app that shares the data model of your application.
- Open a realm and add the data you wish to bundle. If using a synchronized realm, allow time for the realm to fully sync.
- Use the writeCopy(configuration:) method to copy the realm to a new file:
let app = App(id: YOUR_REALM_APP_ID) // Log in the user whose realm you want to copy for bundling let seedUser = try await app.login(credentials: Credentials.anonymous) // Create a configuration to open the seed user's realm var config = seedUser.configuration(partitionValue: "Partition You Want to Bundle") config.objectTypes = [Task.self] // Open the realm with the seed user's config let realm = try await Realm(configuration: config, downloadBeforeOpen: .always) print("Successfully opened realm: \(realm)") // Verify there is a task object in the realm whose // owner's name is "Daenerys". When we open the bundled // realm later, we should see the same result. let tasks = realm.objects(Task.self) let daenerysTasks = tasks.where { $0.owner == "Daenerys" } XCTAssertEqual(daenerysTasks.count, 1) // Specify an output directory for the bundled realm // We're using FileManager here for tested code examples, // but this could be a static directory on your computer. guard let outputDir = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first else { return } // Append a file name to complete the path let bundleRealmFilePath = outputDir.appendingPathComponent("seed.realm") // Update the config file path to the path where you want to save the bundled realm config.fileURL = bundleRealmFilePath // Check to see if there is already a realm at the bundled realm file path. If there // is already a realm there, delete it. if Realm.fileExists(for: config) { try Realm.deleteFiles(for: config) print("Successfully deleted existing realm at path: \(bundleRealmFilePath)") } else { print("No file currently exists at path") } // Write a copy of the realm at the URL we specified try realm.writeCopy(configuration: config) // Verify that we successfully made a copy of the realm XCTAssert(FileManager.default.fileExists(atPath: bundleRealmFilePath.path)) print("Successfully made a copy of the realm at path: \(bundleRealmFilePath)") // Verify that opening the realm at the new file URL works. // Don't download changes, because this can mask a copy // that does not contain the expected data. let copiedRealm = try await Realm(configuration: config, downloadBeforeOpen: .never) // Verify that the copied realm contains the data we expect let copiedTasks = copiedRealm.objects(Task.self) let daenerysCopiedTasks = copiedTasks.where { $0.owner == "Daenerys" } XCTAssertEqual(daenerysCopiedTasks.count, 1) print("Copied realm opens and contains this many tasks: \(daenerysCopiedTasks.count)")
writeCopy(configuration: ) automatically compacts your realm to the smallest possible size before copying.
The above example uses a SyncConfiguration
to configure a synchronized
realm. To create a copy of a local realm, configure your realm
with RealmConfiguration
instead.
Bundle a Realm File in Your Production Application
Now that you have a copy of the realm that contains the initial data, bundle it with your production application. At a broad level, this entails:
- Create a new project with the exact same data models as your production app. Open a realm and add the data you wish to bundle. Since realm files are cross-platform, you can do this in a macOS app.
- Drag the compacted copy of your realm file to your production app's Xcode Project Navigator.
- Go to your app target's Build Phases tab in Xcode. Add the realm file to the Copy Bundle Resources build phase.
- At this point, your app can access the bundled realm file. Find its path with Bundle.main.path(forResource:ofType).
You can open the realm at the bundle path directly if the
readOnly
property is set to true
on the
Realm.Configuration. If
you want to modify the bundled realm, first copy the bundled file to
your app's Documents folder with setting seedFilePath
with the URL of the bundled Realm on your Configuration.
See the migration sample app for a complete working app that uses a bundled local realm.
Open a Realm from a Bundled Realm File
Now that you have a copy of the realm included with your production application, you need to add code to use it. Use the seedFilePath method when configuring your realm to open the realm from the bundled file:
let app = App(id: YOUR_REALM_APP_ID) // Log in an app user who will use the bundled realm let user = try await app.login(credentials: Credentials.anonymous) // Create a configuration for the app user's realm // This should use the same partition value as the bundled realm var newUserConfig = user.configuration(partitionValue: "Partition You Want to Bundle") newUserConfig.objectTypes = [Task.self] // Find the path of the seed.realm file in your project let realmURL = Bundle.main.url(forResource: "seed", withExtension: ".realm") print("The bundled realm URL is: \(realmURL)") // When you use the `seedFilePath` parameter, this copies the // realm at the specified path for use with the user's config newUserConfig.seedFilePath = realmURL // Open the synced realm, downloading any changes before opening it. // This starts with the existing data in the bundled realm, but checks // for any updates to the data before opening it in your application. let realm = try await Realm(configuration: newUserConfig, downloadBeforeOpen: .always) print("Successfully opened the bundled realm") // Read and write to the bundled realm as normal let tasks = realm.objects(Task.self) // There should be one task whose owner is Daenerys because that's // what was in the bundled realm. var daenerysTasks = tasks.where { $0.owner == "Daenerys" } XCTAssertEqual(daenerysTasks.count, 1) print("The bundled realm has \(daenerysTasks.count) tasks whose owner is Daenerys") // Write as usual to the realm, and see the object count increment let task = Task(value: ["name": "Banish Ser Jorah", "owner": "Daenerys", "status": "In Progress"]) try realm.write { realm.add(task) } print("Successfully added a task to the realm") daenerysTasks = tasks.where { $0.owner == "Daenerys" } XCTAssertEqual(daenerysTasks.count, 2)
The above example uses a SyncConfiguration
to configure a synchronized
realm. To create a copy of a local realm, configure your realm
with Realm.Configuration
instead.