Open & Close a Realm - Node.js SDK

Open a Local Realm

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

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

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

Open a Synced Realm

You can open a Synced realm with a Flexible Sync or Partition-Based Sync. If you have not yet decided or are unsure which to use, read the Choose Your Sync Mode page.

By default, Realm syncs all data from the server before returning. If you want to sync data in the background, read the Open a Synced Realm While Offline section.

const realm = await Realm.open({
  schema: [TaskSchema, TeamSchema],
  sync: {
    user: app.currentUser,
    flexible: true,
  },
});

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

Open a Synced Realm While Offline

When your Realm application authenticates a user, it caches the user's credentials. You can check for existing user credentials to bypass the login flow and access the cached user. Use this to open a realm offline.

// Log the user into the backend app.
// The first time you login, the user must have a network connection.
const getUser = async () => {
  // Check for an existing user.
  // If the user is offline but credentials are
  // cached, this returns the existing user.
  if (app.currentUser) return app.currentUser;
  // If the device has no cached user credentials, log them in.
  const credentials = Realm.Credentials.anonymous();
  return await app.logIn(credentials);
};

The following subsections show how to use background synchronization to access a realm while offline. To do this, use the cached user and an OpenRealmBehaviorConfiguration object.

Within your Sync Configuration, set the optional newRealmFileBehavior and existingRealmFileBehavior fields to your OpenRealmBehaviorConfiguration object to enable background synchronization.

const openRealmBehaviorConfig = {
  type: "openImmediately",
};
const config = {
  schema: [Car], // predefined schema
  sync: {
    user: await getUser(),
    partitionValue: "myPartition",
    newRealmFileBehavior: openRealmBehaviorConfig,
    existingRealmFileBehavior: openRealmBehaviorConfig,
  },
};

const openRealmBehaviorConfig = {
  type: "downloadBeforeOpen",
  timeOut: 1000,
  timeOutBehavior: "openLocalRealm",
};
const config = {
  schema: [Car], // predefined schema
  sync: {
    user: await getUser(), // already logged in user
    partitionValue: "myPartition",
    existingRealmFileBehavior: openRealmBehaviorConfig,
    newRealmFileBehavior: openRealmBehaviorConfig,
  },
};

Copy Data and Open a New Realm

To copy data from an existing realm to a new realm with different configuration options, pass the new configuration the Realm.writeCopyTo() method.

In the new realm's configuration, you must specify the path.

If you write the copied realm to a realm file that already exists, the data is written object by object. The copy operation replaces objects if there already exists objects for given primary keys. The schemas of the realm you copy and the realm you are writing to must be compatible for the copy operation to succeed. Only objects in the schemas of both configurations are copied over.

The configuration change can include modifications to SyncConfiguration:

• Local realm to synced realm

• Synced Realm to local realm

The configuration change can also include changes to encryptionKey property of the Configuration:

• Encrypted realm to unencrypted realm

• Unencrypted realm to encrypted realm

const localConfig = {
  schema: [Car],
  path: "localOnly.realm",
};
const localRealm = await Realm.open(localConfig);
const syncedConfig = {
  schema: [Car], // predefined schema
  path: "copyLocalToSynced.realm", // must include in output configuration
  sync: {
    user: app.currentUser, // already logged in user
    partitionValue: "myPartition",
  },
};
localRealm.writeCopyTo(syncedConfig);
const syncedRealm = await Realm.open(syncedConfig);

You can also combine changes to configuration. For example, you can open a local encrypted realm as a synced unencrypted realm or a unencrypted synced realm as an encrypted synced realm.

const encryptionKey = new Int8Array(64); // Create a secure key
// ... store key ...
const syncedEncryptedConfig = {
  schema: [Car], // predefined schema
  path: "syncedEncrypted.realm", // must include in output configuration
  sync: {
    user: app.currentUser, // already logged in user
    partitionValue: "myPartition",
  },
  encryptionKey,
};
const syncedEncryptedRealm = await Realm.open(syncedEncryptedConfig);
const localUnencryptedConfig = {
  schema: [Car], // predefined schema
  path: "copyLocalUnencrypted.realm", // must include in output configuration
};
syncedEncryptedRealm.writeCopyTo(localUnencryptedConfig);
const localUnencryptedRealm = await Realm.open(syncedEncryptedConfig);

Close a Realm

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

realm.close();