Setting Up Your Realms

Last updated 4 months ago

What is a Realm?

A Realm is an instance of a Realm Database. Realms can be local, in-memory, or synchronized. In practice, your application works with any kind of Realm the same way. Local Realms are the standard use-case, where the Realm simply persists data locally on the device. In-memory Realms have no persistence mechanism, and are meant for temporary storage. With Realm Platform, you will be working with a synchronized Realm.

A synchronized Realm uses the Realm Platform to transparently synchronize its contents with other devices. While your application continues working with a synchronized Realm as if it's a local Realm, the data in that Realm might be updated by any device with write access to that Realm--so the Realm could represent a channel in a chat application, for instance, being updated by any user talking in that channel. Or, it could be a shopping cart, accessible only to devices owned by you.

If you're used to working with other kinds of databases, here are some things that a Realm is not:

  • A Realm is not a table. Tables typically only store one kind of information: user records, email messages, and so on. But a Realm can contain multiple kinds of objects.

  • A Realm is not a schemaless document store. Because object properties are analogous to key/value pairs, it's easy to think of a Realm as a document store, but objects in a Realm have defined schemas that support giving values defaults or marking them as required or optional.

  • A Realm is not a traditional relational database. A Realm is an object database in which links between objects are a first-class type. The links do not require the use of key lookups and are instead analogous to pointers.

The Default Synced Realm

The easiest way to get started with Realm Platform is to use the default synchronized Realm. With Realm Platform - Cloud each cloud instance will have a single default Realm. For Self-Hosted each server installation will include a single default Realm.

For most apps, you can include all of your application data within the default synchronized Realm. Realm Platform supports query-based sync, so that you can control what data from the default synced Realm is synchronized to the client application.

In addition, to you application data, the server will also include other internal classes used in its management and the master list of authenticated users, represented by the __User class. The internal data is managed by permissions restricting its access--you can learn more about how the permission system works later, for now just know this internal data exists.

The purpose of the default synchronized Realm is to simplify getting started and allow your application data to link into the master list of authenticated users.

You do not need to create the default synced Realm, it is automatically created for you.

Interacting with the default synced Realm has built-in APIs in the Realm SDKs:

Swift
Objective-C
Java
Javascript
.Net

The default synced Realm is provided via an automatic SyncConfiguration that can be accessed from the logged in SyncUser.

For example, to log in, then asynchronously open the default synced Realm:

SyncUser.logIn(with: credentials, server: serverURL) { user, error in
if let user = user {
Realm.Configuration.defaultConfiguration = user.configuration()
Realm.asyncOpen() { realm in
// ...
}
}
}

Your Server URL will follow a format like:

Cloud: https://my-cloud-url.us1.cloud.realm.io

Self-hosting: http://127.0.0.1:9080

The default synced Realm is provided via an automatic RLMSyncConfiguration that can be accessed from the logged in RLMSyncUser.

For example, to log in, then asynchronously open the default synced Realm:

[RLMSyncUser logInWithCredentials:credentials
authServerURL:serverURL
onCompletion:^(RLMSyncUser *user, NSError *error) {
if (user) {
RLMRealmConfiguration *config = [user configuration];
[RLMRealm asyncOpenWithConfiguration:config
callbackQueue:dispatch_get_main_queue()
callback:^(RLMRealm *realm, NSError *error) {
if (realm) {
// ...
}
}];
}
}];

Your Server URL will follow a format like:

Cloud: https://my-cloud-url.us1.cloud.realm.io

Self-hosting: http://127.0.0.1:9080

The default synced Realm is provided via an automatic SyncConfiguration that can be accessed from the logged in SyncUser.

For example, to log in and open the default synced Realm:

SyncCredentials credentials = getCredentials();
String url = getUrl();
SyncUser.login(credentials, url, new SyncUser.Callback<SyncUser>() {
@Override
public void onSuccess(SyncUser user) {
SyncConfiguration config = user.getDefaultConfiguration();
Realm realm = Realm.getInstance(config);
// Use Realm
}
@Override
public void onError(ObjectServerError error) {
// Handle error
}
});

Your Server URL will follow a format like:

Cloud: https://my-cloud-url.us1.cloud.realm.io

Self-hosting: http://127.0.0.1:9080

The default synced Realm is provided via the default configuration which can be accessed from the logged in Realm.Sync.User.

When using query-based sync with Javascript, you are required to pass in a schema for your Realm.

For example, to log in and open the default synced Realm:

Realm.Sync.User.login(server, username, password)
.then((user) => {
let config = user.createConfiguration();
config.schema = [Schema];
Realm.open(config).then((realm) => {
// ...
});
})

Your Server URL will follow a format like:

Cloud: https://my-cloud-url.us1.cloud.realm.io

Self-hosting: http://127.0.0.1:9080

The default synced Realm is provided via an automatic QueryBasedSyncConfiguration, which will use the current logged in user from User.Current and the server URL used to authenticate.

For example, to log in, then asynchronously open the default synced Realm with the current user:

var user = await User.LoginAsync(credentials, serverUrl);
RealmConfiguration.DefaultConfiguration = new QueryBasedSyncConfiguration();
var realm = await Realm.GetInstanceAsync();

If you are working with multiple users, you can pass in the specific user as well:

var user = await User.LoginAsync(credentials, serverUrl);
RealmConfiguration.DefaultConfiguration = new QueryBasedSyncConfiguration(user: user);
var realm = await Realm.GetInstanceAsync();

Your Server URL will follow a format like:

Cloud: https://my-cloud-url.us1.cloud.realm.io

Self-hosting: http://127.0.0.1:9080

Other Synced Realms

With Realm Platform, you are not restricted to only using the default synced Realm. Instead, you can create as many Realms as needed for your application. Prior to Realm Platform 3.0 and the introduction of query-based sync, using multiple Realms was the recommended pattern.

A common use-case for multiple Realms is to isolate data that is user-specific. A hypothetical chat application might use one synchronized Realm for public chats, another synchronized Realm storing user data, yet another synchronized Realm for a "master channel list" that's read-only to non-administrative users, and a local Realm for persisted settings on that device. Realms are lightweight, and your application can be using several at one time. (On mobile platforms, there are some resource constraints, but up to a dozen open at once should be no issue.)

The downside of multiple Realms is that objects in one Realm cannot link to objects in another, nor are cross-Realm queries supported. This means that when designing an application with multiple Realms, you must consider how your data is structured across the Realms and use keys to refer to objects in other Realms.

Creating Models

Whether you use the default synced Realm or other Realms, the first step when using a Realm is to define the object models, or schema, for the objects it will include. With Realm Platform, you can choose to create your models for the Realm in one of two ways:

In Your Application

The simplest way to get started with a synced Realm is to create your models in your client application directly. Realm provides language-specific SDKs that allow you to define a model as a regular class with regular properties.

Swift
Objective-C
Java
Javascript
.Net
import RealmSwift
// Dog model
class Dog: Object {
@objc dynamic var name = ""
@objc dynamic var owner: Person? // Properties can be optional
}
// Person model
class Person: Object {
@objc dynamic var name = ""
@objc dynamic var birthdate = Date(timeIntervalSince1970: 1)
let dogs = List<Dog>()
}

See Models in the Swift documentation for more information on supported data types and other related concepts.

#import <Realm/Realm.h>
@class Person;
// Dog model
@interface Dog : RLMObject
@property NSString *name;
@property Person *owner;
@end
RLM_ARRAY_TYPE(Dog) // define RLMArray<Dog>
// Person model
@interface Person : RLMObject
@property NSString *name;
@property NSDate *birthdate;
@property RLMArray<Dog *><Dog> *dogs;
@end
RLM_ARRAY_TYPE(Person) // define RLMArray<Person>
// Implementations
@implementation Dog
@end // none needed
@implementation Person
@end // none needed
public class Dog extends RealmObject {
private String name;
private int age;
// ... Generated getters and setters ...
}
public class Person extends RealmObject {
@PrimaryKey
private long id;
private String name;
private RealmList<Dog> dogs; // Declare one-to-many relationships
// ... Generated getters and setters ...
}

See Models in the Java documentation for more information on supported data types and other related concepts.

const Realm = require('realm');
// Define your models and their properties
const CarSchema = {
name: 'Car',
properties: {
make: 'string',
model: 'string',
miles: {type: 'int', default: 0},
}
};
const PersonSchema = {
name: 'Person',
properties: {
name: 'string',
birthday: 'date',
cars: 'Car[]', // list of cars
picture: 'data?' // optional property
}
};

See Models in the Javascript documentation for more information on supported data types and other related concepts.

// Define your models like regular C# classes
public class Dog : RealmObject
{
public string Name { get; set; }
public int Age { get; set; }
public Person Owner { get; set; }
}
public class Person : RealmObject
{
public string Name { get; set; }
public IList<Dog> Dogs { get; }
}

See Models in the .Net documentation for more information on supported data types and other related concepts.

In JavaScript, the schema for your model must be passed into the constructor as part of the configuration object. For Swift, Java, and .Net the classes defined in your application code will automatically be added to the Realm when you open it, or you can choose to define a subset of classes for the Realm within its configuration.

In Realm Studio

When working with a larger team or when building a cross-platform application, it can be easier to create your models in a centralized place. Realm Platform offers a desktop application, Realm Studio, where you can connect to your cloud instance or self-hosted server and create a new synchronized Realm. You can then create new classes and add properties to the Realm.

Once you are finished creating the Realm in Studio, you can export the model definitions to any supported platform language so you can include the code in your application.

Not what you were looking for? Leave Feedback