Bundle a Realm File - Java SDK
On this page
SDK version 10.9.0 introduced the ability to bundle synchronized realms. Before version 10.9.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 must 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 the
/<app name>/src/main/assetsfolder of 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 writeCopyTo() method to copy the realm to a new file:
writeCopyTo()automatically compacts your realm to the smallest possible size before copying.TipDifferences Between Synced Realms and Local-only RealmsThe above example uses a
SyncConfigurationto configure a synchronized realm. To create a copy of a local realm, configure your realm withRealmConfigurationinstead.
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.
- Search your application logs to find the location of the realm file copy you just created.
- Using the "Device File Explorer" widget in the bottom right of your Android Studio window, navigate to the file.
- Right click on the file and select "Save As". Navigate to the
/<app name>/src/main/assetsfolder of your production application. Save a copy of the realm file there.
If your application does not already contain an asset folder, you can
create one by right clicking on your top-level application
folder (<app name>) in Android Studio and selecting
New > Folder > Assets Folder in the menu.
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 assetFile() method when configuring your realm to open the realm from the bundled file:
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.