Docs Menu

Open & Close a Realm - Node.js SDK

On this page

  • Open a Local Realm
  • Open a Synced Realm
  • Open a Synced Realm While Online
  • Open a Synced Realm While Offline
  • 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);
}

If you're opening a synced realm, the configuration you use depends on whether or not the user's device is connected to the Internet. Learn how to handle different connection states in the Open a Synced Realm While Online and Open a Synced Realm While Offline sections.

To open a synced realm while online, call Realm.open(). Pass in a Configuration object, which must include the sync property defining a SyncConfiguration object.

The default behavior for realm is to sync all data from the server before returning. In the SyncConfiguration, you must include include the user and partitionValue.

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, configure your SyncConfiguration to include newRealmFileBehavior and existingRealmFileBehavior each with the same OpenRealmBehaviorConfiguration.

Set the OpenRealmBehaviorConfiguration to have type: 'downloadBeforeOpen', timeOut: <time in milliseconds> and timeOutBehavior: 'openLocalRealm'. These properties make Realm.open() return at the end of the timeOut period, and open a local realm. Syncing between local data and the server 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. The client attempts to sync until the end of the the timeOut period, and then opens the local realm, even if the it never connects to the server.

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);
}
Warning

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

Refer to the Open a Synced Realm While Offline documentation for more information about connecting to your offline realm.

If a user's device is not connected to the Internet or you're not certain if it's connected, you must use a a OpenRealmBehaviorConfiguration that includes newRealmFileBehavior and existingRealmFileBehavior properties.

Create a OpenRealmBehaviorConfiguration object and set its type to "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.

const OpenRealmBehaviorConfiguration = {
type: "openImmediately",
};

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 fields of the SyncConfiguration.

const config = {
schema: [DogSchema], // predefined schema
sync: {
user: app.currentUser,
partitionValue: "MyPartitionValue",
// The behavior to use when this is the first time opening a realm.
newRealmFileBehavior: OpenRealmBehaviorConfiguration,
// The behavior to use when a realm file already exists locally,
// i.e. you have previously opened the realm.
existingRealmFileBehavior: OpenRealmBehaviorConfiguration,
},
};

Finally, call Realm.open() to open the local realm and attempt syncing with the server in the background.

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

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

About

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