Docs Menu

Open & Close a Realm - React Native SDK

On this page

  • Open a Local Realm
  • Open an In-Memory Realm
  • Open a Synced Realm
  • Sync All Data before Opening
  • Open After Timeout with Background Sync
  • Open Immediately with Background Sync
  • Close a Realm

To open a local (non-synced) realm, pass a Realm.Configuration object to the asynchronous method Realm.open().

Note
Accessing the Default Realm Path

If the path property is not specified in your Configuration object, the default path is used. You can access and change the default Realm path using the Realm.defaultPath global property.

const Car = {
name: "Car",
properties: {
make: "string",
model: "string",
miles: "int",
},
};
// Open a local realm file with a particular path & predefined Car schema
try {
const realm = await Realm.open({
schema: [Car],
});
realm.close();
} catch (err) {
console.error("Failed to open the realm", err.message);
}

To create a realm that runs entirely in memory without being written to a file, add inMemory: true to your Realm.Configuration object:

const realm = await Realm.open({
inMemory: true,
schema: [Car],
});
Note

In-memory realms may use disk space if memory is running low, but files created by an in-memory realm are deleted when you close the realm.

To open a synced realm, call Realm.open(). Pass in a Configuration object, which must include the sync property defining a SyncConfiguration object. In the SyncConfiguration, you must include include user and partitionValue.

When opening a synced realm, the configuration you use depends on the initial sync behavior you want. You can connect to a synced realm in the following ways:

Warning

When attempting to synchronize a realm while not connected to the Internet, you must pass Realm.open() a Configuration object that contains the newRealmFileBehavior and existingRealmFileBehavior properties. If you don't include these properties, Realm.open() continues trying to connect to the server indefinitely without opening.

For more information about connecting to your synced realm while offline, see Open Immediately with Background Sync.

By default, Realm syncs all data from the server before returning.

Example

The following example shows how to open a synced realm with with a SyncConfiguration object that uses a predefined CarSchema schema, the currently logged in user, and a partition value of "myPartition".

const config = {
schema: [Car], // predefined schema
sync: {
user: app.currentUser, // already logged in user
partitionValue: "myPartition",
},
};
try {
const realm = await Realm.open(config);
realm.close();
} catch (err) {
console.error("failed to open realm", err.message);
}

If you don't need to sync all data before before returning the realm, configure the newRealmFileBehavior and existingRealmFileBehavior properties of your SyncConfiguration to automatically open the realm after a timeout period elapses. You can use a single OpenRealmBehaviorConfiguration for both newRealmFileBehavior and existingRealmFileBehavior that contains the following property values:

  • type: "downloadBeforeOpen"
  • timeOut: <time in milliseconds>
  • timeOutBehavior: "openLocalRealm"

These properties force the Realm.open() method to return an open realm after timeOut milliseconds, or when the realm has completely downloaded, whichever comes first. If the realm doesn't finish downloading before the timeout, the initial realm sync continues in the background. For example:

const realmFileBehavior = {
type: "downloadBeforeOpen",
timeOut: 1000,
timeOutBehavior: "openLocal",
};
const config = {
schema: [Car], // predefined schema
sync: {
user: app.currentUser, // already logged in user
partitionValue: "myPartition",
existingRealmFileBehavior: realmFileBehavior,
newRealmFileBehavior: realmFileBehavior,
},
};

This configuration is also useful if you're attempting to sync in an environment where it's uncertain if the user has an Internet connection.

Example

The following example shows opening a synced realm with a Configuration object using a predefined Car schema, the currently logged in user, a partition value of "myPartition", and a SyncConfiguration. The SyncConfiguration includes existingRealmFileBehavior and newRealmFileBehavior set to allow the user to work with the local realm if the device is doesn't fully sync within the timeOut period of 1000 milliseconds.

const realmFileBehavior = {
type: "downloadBeforeOpen",
timeOut: 1000,
timeOutBehavior: "openLocal",
};
const config = {
schema: [Car], // predefined schema
sync: {
user: app.currentUser, // already logged in user
partitionValue: "myPartition",
existingRealmFileBehavior: realmFileBehavior,
newRealmFileBehavior: realmFileBehavior,
},
};
try {
const realm = await Realm.open(config);
realm.close();
} catch (err) {
console.error("failed to open realm", err.message);
}

When you want to connect to the realm immediately and sync data from the server in the background, you must use a OpenRealmBehaviorConfiguration that includes the newRealmFileBehavior and existingRealmFileBehavior properties. This configuration is useful if a user's device is not connected to the Internet or you're not certain if it's connected.

Create a OpenRealmBehaviorConfiguration object and set the type property to a value of "openImmediately". This configuration opens a local realm immediately without attempting to sync with the server. The client continues attempting to connect with the server in the background.

Then create a Configuration object, which must include the sync property defining a SyncConfiguration object. Set this OpenRealmBehaviorConfiguration object as the value for the newRealmFileBehavior and existingRealmFileBehavior properties of the SyncConfiguration.

const OpenRealmBehaviorConfiguration = {
type: "openImmediately",
};
const config = {
schema: [Car], // predefined schema
sync: {
user: app.currentUser,
partitionValue: "myPartition",
newRealmFileBehavior: OpenRealmBehaviorConfiguration,
existingRealmFileBehavior: OpenRealmBehaviorConfiguration,
},
};

It is important to remember to call the close() method when done with a realm instance to avoid memory leaks.

realm.close();
Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.