配置并打开 Realm — C++ SDK
在此页面上
域是 Realm 中用于组织数据的核心数据结构。Realm 是应用程序中使用的对象(称为 Realm 对象)以及描述对象的其他元数据的集合。
打开域时,必须指定 db_config 。 db_config
可能包含以下信息:
Realm 在设备上存储的可选路径
Realm 应管理的模型的可选列表
如果需要自定义事件循环,则使用可选的调度程序
如果要将 域 与 Device Sync 一起使用,请输入
sync_config
如果您不需要指定 Realm 文件路径、Device Sync 配置或其他配置详细信息,则可以使用默认的db_config
构造函数。
Realm 文件
Realm将域中每个对象和类型的二进制编码版本存储在单个.realm
文件中。 该文件位于打开域时可以定义的特定路径。 您可以使用 打开、查看和编辑这些文件的内容。
辅助文件
SDK 会为每个 Realm 创建附加文件:
realm 文件,后缀为 "realm",例如
default.realm
:包含对象数据。锁定文件,后缀为 "lock",例如
default.realm.lock
:跟踪 Realm 中哪些数据版本正在使用中。 这可以防止 Realm 回收客户端应用程序仍在使用的存储空间。note 文件,后缀为 "note",例如
default.realm.note
:启用线程间和进程间通知。管理文件,后缀为“管理”,例如
default.realm.management
:内部状态管理。
同步 Realm
您可以将 Realm 配置为在许多设备之间自动同步数据,而每个设备都有自己的本地数据副本。 同步 Realm 需要sync_config
,并且需要 Atlas App Services 后端来处理同步过程。
应用程序始终可以在本地创建、修改和删除同步的 Realm 对象,即使在离线状态下也是如此。 只要网络连接可用,Realm SDK 就会建立与应用程序服务器的连接,并与其他客户端进行双向更改同步。 Atlas Device Sync 协议和服务器端操作转换可确保 Realm 的所有完全同步实例看到完全相同的数据,即使某些更改发生在离线状态和/或接收时无序。
已同步 Realms 与非同步 Realms
同步域与非同步本地域有几个不同之处:
同步 Realm 尝试将更改与后端 App Services App 同步,而非同步 Realm 则不会。
同步 Realm 只能由经过身份验证的用户访问,而非同步 Realm 没有用户或身份验证的概念。
通过同步 Realm,您可以在打开 Realm 之前下载更新。 但是,要求在打开 Realm 之前下载更改需要用户处于在线状态。 非同步 Realm 始终可离线使用。
您可以手动将数据从非同步 Realm 复制到同步 Realm,反之亦然,但无法同步非同步 Realm。
打开非同步 Realm
您可以使用默认构造函数在当前目录中打开 Realm。 或者,您可以构造具有特定文件路径的db_config
,以在特定位置打开 Realm。
打开默认 Realm
在不指定可选路径的情况下打开 Realm 会在当前目录中打开默认 Realm。
打开 Realm 时,C++ SDK 可以自动推断项目中哪些模型可用。 除非您要打开一个 域 以与非对称 对象 单向同步数据,否则无需手动指定可用模型。有关更多信息,请参阅本页上的“打开同步 Realm”。
auto config = realm::db_config(); auto realm = realm::db(std::move(config));
提示
构建 Android 应用
构建使用 Realm C++ SDK 的 Android 应用程序时,您必须将filesDir.path
传递给db_config构造函数中的path
参数。 有关更多信息,请参阅:构建 Android 应用。
在文件路径中打开 Realm
您可以使用set_path()
指定db_config
在打开 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));
提示
构建 Android 应用
在构建使用 Realm C++ SDK 的 Android 应用程序时,您必须将filesDir.path
作为path
参数传递到db_config构造函数中。 有关更多信息,请参阅:构建 Android 应用。
打开同步 Realm
您必须拥有 为 Flexible Sync 配置 的 Atlas App Services App ,才能在设备之间同步数据。
要打开同步 Realm,请执行以下操作:
连接到 Atlas App Services App。
对用户进行身份验证。
创建同步配置。
使用配置打开用户的同步 Realm。
// 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);
当您打开同步 Realm 时,无需将希望该 Realm 管理的模型传递到打开函数的模板参数列表中。 这是对已弃用的 Alpha API 的更改。
此规则的唯一例外是打开同步 Realm 来同步asymmetric_object
类型。 当您打开同步 Realm 以同步asymmetric_object
类型时,您必须在打开函数的模板参数列表中显式指定对象。 有关更多信息,请参阅将数据流式传输到 Atlas - C++ SDK。
提示
构建 Android 应用
构建使用 Realm C++ SDK 的 Android 应用程序时,您必须将filesDir.path
传递给db_config构造函数中的path
参数。 有关更多信息,请参阅:构建 Android 应用。
使用 Realm 时设置自定义 HTTP headers
要在 Device Sync 中使用自定义 HTTP headers,您必须在应用程序 和 上 设置 headersflexible_sync_configuration()
。
初始化配置后,使用set_custom_http_headers()
成员函数将自定义 HTTP 标头设置为字符串标头键和值的映射。
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);
现在,同步 Realm 可以将标头用于所有 Device Sync 网络请求。
为 Realm 提供模型子集
提示
在低内存限制下运行
某些应用程序对其内存占用有严格的限制。 要针对低内存环境优化 Realm 内存使用量,请使用模型子集打开 Realm。
默认情况下,C++ SDK 会自动将可执行文件中具有对象模式的所有对象类型添加到数据库模式中。
但是,如果您希望 Realm 仅管理模型的子集,则可以通过将这些模型传递到realm::open()
函数的模板参数列表来指定这些模型。
auto config = realm::db_config(); auto realm = realm::open<realm::Dog>(std::move(config));
关闭 Realm
为避免内存泄漏,请在使用完数据库后将其关闭。 关闭数据库会使所有剩余对象失效。 使用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());