Docs Menu

Docs Home → Develop Applications → Atlas Device SDKs

Configure & Open a Realm - C++ SDK

On this page

  • Realm Files
  • Auxiliary Files
  • Synced Realms
  • Synced Realms vs. Non-Synced Realms
  • Open a Non-Sync Realm
  • Open the Default Realm
  • Open a Realm at a File Path
  • Open a Synced Realm
  • Set Custom HTTP Headers When Using a Synced Realm
  • Provide a Subset of Models to a Realm
  • Close a Realm

A realm is the core data structure used to organize data in Realm. A realm is a collection of the objects that you use in your application, called Realm objects, as well as additional metadata that describe the objects.

When opening a realm, you must specify a db_config. The db_config may contain information such as:

  • An optional path where the realm is stored on device

  • An optional list of models that the realm should manage

  • An optional scheduler if you need to customize the run loop

  • A sync_config if you want to use the realm with Device Sync

You can use the default db_config constructor if you do not need to specify a realm file path, a Device Sync configuration, or other configuration details.

Realm Files

Realm stores a binary encoded version of every object and type in a realm in a single .realm file. The file is located at a specific path that you can define when you open the realm. You can open, view, and edit the contents of these files with Realm Studio.

Auxiliary Files

The SDK creates additional files for each realm:

  • realm files, suffixed with "realm", e.g. default.realm: contain object data.

  • lock files, suffixed with "lock", e.g. default.realm.lock: keep track of which versions of data in a realm are actively in use. This prevents realm from reclaiming storage space that is still used by a client application.

  • note files, suffixed with "note", e.g. default.realm.note: enable inter-thread and inter-process notifications.

  • management files, suffixed with "management", e.g. default.realm.management: internal state management.

Synced Realms

You can configure a realm to automatically synchronize data between many devices that each have their own local copy of the data. Synced realms need a sync_config and require an Atlas App Services backend to handle the synchronization process.

Applications can always create, modify, and delete synced realm objects locally, even when offline. Whenever a network connection is available, the Realm SDK opens a connection to an application server and syncs changes to and from other clients. The Atlas Device Sync protocol and server-side operational transforms guarantee that all fully synced instances of a realm see exactly the same data, even if some changes occurred offline and/or were received out of order.

Synced Realms vs. Non-Synced Realms

Synced realms differ from non-synced local Realm in a few ways:

  • Synced realms attempt to sync changes with your backend App Services App, whereas non-synced realms do not.

  • Synced realms can only be accessed by authenticated users, while non-synced realms have no concept of users or authentication.

  • With synced realms, you can download updates before opening a realm. However, requiring changes to download before opening the realm requires the user to be online. Non-synced realms can always be used offline.

You can manually copy data from a non-synced realm to a synced realm, and vice versa, but you cannot sync a non-synced realm.

Open a Non-Sync Realm

You can open a realm in the current directory using the default constructor. Or you can construct a db_config with a specific file path to open the realm in a specific location.

Open the Default Realm

Opening a realm without specifying an optional path opens the default realm in the current directory.

When opening a realm, the C++ SDK can automatically infer which models are available in the project. You don't need to manually specify the available models unless you are opening a realm to sync data unidirectionally with asymmetric objects. For more information, refer to Open a Synced Realm on this page.

auto config = realm::db_config();
auto realm = realm::db(std::move(config));

Tip

Building an Android App

When building an Android app that uses the Realm C++ SDK, you must pass the filesDir.path to the path parameter in the db_config constructor. For more information, refer to: Build an Android App.

Open a Realm at a File Path

You can use set_path() to specify a path for the db_config to use when opening the realm.

auto relative_realm_path_directory = "custom_path_directory/";
std::filesystem::create_directories(relative_realm_path_directory);
// Construct a path
std::filesystem::path path =
    std::filesystem::current_path().append(relative_realm_path_directory);
// Add a name for the database file
path = path.append("employee_objects");
// Add the .realm extension
path = path.replace_extension("realm");
// Set the path on the config, and open the database at the path
auto config = realm::db_config();
config.set_path(path);
auto realmInstance = realm::db(std::move(config));

Tip

Building an Android App

When building an Android app that uses the Realm C++ SDK, you must pass the filesDir.path as the path parameter in the db_config constructor. For more information, refer to: Build an Android App.

Open a Synced Realm

You must have an Atlas App Services App that you have configured for Flexible Sync in order to sync data between devices.

To open a synced realm:

  1. Connect to an Atlas App Services App.

  2. Authenticate the user.

  3. Create a sync configuration.

  4. Open the user's synced realm with the configuration.

// Initialize the App, authenticate a user, and open the database
auto appConfig = realm::App::configuration();
appConfig.app_id = APP_ID;
auto app = realm::App(appConfig);
auto user = app.login(realm::App::credentials::anonymous()).get();
auto syncConfig = user.flexible_sync_configuration();
auto syncedRealm = realm::db(syncConfig);

When you open a synced realm, you don't need to pass the models you want the realm to manage into the template parameter list of the open function. This is a change from the deprecated Alpha API.

The only exception to this rule is opening a synced realm to sync asymmetric_object types. When you open a synced realm to sync asymmetric_object types, you must explicitly specify the objects in the template parameter list for the open function. For more information, refer to Stream Data to Atlas - C++ SDK.

Tip

Building an Android App

When building an Android app that uses the Realm C++ SDK, you must pass the filesDir.path to the path parameter in the db_config constructor. For more information, refer to: Build an Android App.

Set Custom HTTP Headers When Using a Synced Realm

To use custom HTTP headers with Device Sync, you must set the headers on the App and on the flexible_sync_configuration().

After you initialize the configuration, use the set_custom_http_headers() member function to set the custom HTTP headers to a map of string header keys and values.

std::map<std::string, std::string> customHeaders;
customHeaders.emplace("CUSTOM_HEADER_NAME", "CUSTOM_HEADER_VALUE");
auto syncConfig = user.flexible_sync_configuration();
syncConfig.set_custom_http_headers(customHeaders);

Now the synced realm can use the headers for all Device Sync network requests.

Provide a Subset of Models to a Realm

Tip

Operating with Low Memory Constraints

Some applications have tight constraints on their memory footprints. To optimize your realm memory usage for low-memory environments, open the realm with a subset of models.

By default, the C++ SDK automatically adds all object types that have a Object Schema in your executable to your Database Schema.

However, if you want the realm to manage only a subset of models, you can specify those models by passing them into the template parameter list of the realm::open() function.

auto config = realm::db_config();
auto realm = realm::open<realm::Dog>(std::move(config));

Close a Realm

To avoid memory leaks, close the database when you're done using it. Closing the database invalidates any remaining objects. Close the database with db::close().

// Create a database configuration.
auto config = realm::db_config();
auto realm = realm::db(config);
// Use the database...
// ... later, close it.
realm.close();
// You can confirm that the database is closed if needed.
CHECK(realm.is_closed());
// Objects from the database become invalidated when you close the database.
CHECK(specificDog.is_invalidated());
← Work with Realm Files - C++ SDK
Reduce Realm File Size - C++ SDK →

On this page