Note: This documentation section only describes features specific to the Enterprise and Professional Editions. For other topics, including configuration, general usage, and troubleshooting, read the main Object Server documentation.

Installing/Upgrading

Note: The Professional and Enterprise editions of the Realm Object Server are currently available for Linux only.

Upgrading to Professional Edition

If you are upgrading to the Professional Edition of the Realm Object Server, you must first uninstall the Developer Edition. Then, using the access token you’ve received from us via email, follow these steps according to your distribution:

• RHEL/CentOS 6
• RHEL/CentOS 7
• Ubuntu 16.04

# Set the token variable:
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Setup Realm's package repository
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-professional/script.rpm.sh | sudo bash

# Install the Realm Object Server
sudo yum -y install realm-object-server-professional

# Enable and start the service
sudo chkconfig realm-object-server on
sudo service realm-object-server start

# Set the token variable:
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Setup Realm's package repository
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-professional/script.rpm.sh | sudo bash

# Install the Realm Object Server
sudo yum -y install realm-object-server-professional

# Enable and start the service
sudo systemctl enable realm-object-server
sudo systemctl start realm-object-server

# Set the token variable:
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Setup Realm's package repository
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-professional/script.deb.sh | sudo bash

# Update repositories
sudo apt-get update

# Install the Realm Object Server
sudo apt-get install realm-object-server-professional

# Enable and start the service
sudo systemctl enable realm-object-server
sudo systemctl start realm-object-server

Upgrading to Enterprise Edition

If you are upgrading to the Enterprise Edition of the Realm Object Server, you must first uninstall the Developer/Professional Edition. Then, using the access token you’ve received from us via email, follow these steps according to your distribution:

• RHEL/CentOS 6
• RHEL/CentOS 7
• Ubuntu 16.04

# Set the token variable:
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Setup Realm's package repository
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.rpm.sh | sudo bash

# Install the Realm Object Server
sudo yum -y install realm-object-server-enterprise

# Enable and start the service
sudo chkconfig realm-object-server on
sudo service realm-object-server start

# Set the token variable:
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Setup Realm's package repository
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.rpm.sh | sudo bash

# Install the Realm Object Server
sudo yum -y install realm-object-server-enterprise

# Enable and start the service
sudo systemctl enable realm-object-server
sudo systemctl start realm-object-server

# Set the token variable:
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Setup Realm's package repository
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.deb.sh | sudo bash

# Update repositories
sudo apt-get update

# Install the Realm Object Server
sudo apt-get install realm-object-server-enterprise

# Enable and start the service
sudo systemctl enable realm-object-server
sudo systemctl start realm-object-server

Load Balancing

The Realm Object Server has extremely high performance; even a single instance can handle tens of thousands of concurrent connections. However, for applications that expect millions of concurrent connections, multiple Object Servers are required. The Enterprise Edition of Realm Mobile Platform offers integrated load balancing, which allows you to horizontally scale to any number of Object Server instances.

Installation

Each node in a load balancing cluster runs a standalone instance of the Realm Sync Worker. This synchronization worker normally runs as part of Realm Object Server, synchronizing Realms between the server and Realm Mobile Database Clients; in its standalone form, it performs load balancing for an Object Server. Each load balancer runs its own instance of Sync Worker, all communicating with the Object Server instance.

The realm-sync-worker package must be installed from the Realm enterprise repository.

• RHEL/CentOS 6
• RHEL/CentOS 7
• Ubuntu 16.04

# Set the token variable:
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Setup Realm's Enterprise package repository. No need to do it if you already installed the ROS Enterprise
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.rpm.sh | sudo bash

# Install the Realm Object Server standalone sync worker:
sudo yum -y install realm-sync-worker

# Replace /etc/realm/token-signature.pub with the one from the Realm Object
# Server.

# Enable and start the service
sudo chkconfig realm-sync-worker on
sudo service realm-sync-worker start

# Set the token variable:
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Setup Realm's Enterprise package repository. No need to do it if you already installed the ROS Enterprise
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.rpm.sh | sudo bash

# Install the Realm Object Server standalone sync worker:
sudo yum -y install realm-sync-worker

# Replace /etc/realm/token-signature.pub with the one from the Realm Object
# Server.

# Enable and start the service
sudo systemctl enable realm-sync-worker
sudo systemctl start realm-sync-worker

# Set the token variable:
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Setup Realm's Enterprise package repository. No need to do it if you already installed the ROS Enterprise.
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.deb.sh | sudo bash

# Update repositories
sudo apt-get update

# Install the Realm Object Server
sudo apt-get install realm-sync-worker

# Replace /etc/realm/token-signature.pub with the one from the Realm Object
# Server.

# Enable and start the service
sudo systemctl enable realm-sync-worker
sudo systemctl start realm-sync-worker

Configuration

Both the Realm Object Server and each individual sync worker must be configured for load balancing operation.

In the Realm Object Server’s configuration.yml file, the sync.servers section describes the cluster of load balancers. Each balancing node must be identified with a unique ID, which can be any string as long as it is a valid filesystem path component.

Example:

sync:
  servers:
  - id: 'alpha'
    address: '::'
    port: 7800
  - id: 'beta'
    address: 'beta.local'
    port: 7800
  - id: 'delta'
    address: 'delta.local'
    port: 7800

If the address field designates an IP address representing all interfaces, i.e. “0.0.0.0” (or “::” if using IPv6), this indicates to the Realm Object Server that a local synchronization worker should be started listening on the IP address of localhost (“127.0.0.1” or “::1” respectively).

The sync workers use a separate configuration file, sync-worker-configuration.yml, which is a subset of the Object Server’s file. The file is created by default on worker startup. Check the network section in the sync-worker-configuration.yml and ensure that the listen_address line is uncommented and correct:

network:
  sync:
    listen_address: '0.0.0.0'

An address of 0.0.0.0 will listen on all interfaces; you may alternatively specify a specific interface by IP address. The server must be listed in the sync.servers section of the Object Server’s configuration file.

The example configuration files provided as part of the Realm Object Server installation provide additional details.

Failover

Realm Object Server supports manual failover, but not automatic failover. You must have Load Balancing configured with sync workers to use failover, and set up redundant sync workers and/or Object Servers as described below in “prerequisites.”

Switching to a backup Sync Worker

Prerequisites

Following the directions in the Continuous Backup backup client section, configure a backup client to point to a machine running sync-worker. The network.server_address setting in the configuration file (object-server-backup-client.yml) should be set to the sync worker’s IP address or domain name.

Install sync-worker on the same machine as this backup client, but do not start the sync-worker.

Set up the sync worker following the configuration instructions under “Load Balancing,” with the following change: Set storage.root_path to point to the same folder the backup client is writing to.

Make sure that the token-signature.pub file is the same for both the backup client and the running sync worker it’s backing up from.

Triggering failover

If a sync-worker machine fails and you want to bring the failover machine online, take the following steps. (“Failover machine” refers to the machine set up in the prerequisite section that will take over for the failed sync worker.)

• Stop the backup client process on the failover machine. (On Ubuntu servers: systemctl stop realm-object-server-backup-client)
• Start the sync worker on the failover machine. (systemctl start realm-sync-worker)
• Open the configuration.yml file of the Realm Object Server and change the IP address (or host name) of the sync-worker that failed to the IP address (or host name) of the failover machine.
• Restart the Realm Object Server. (systemctl restart realm-object-server)

Note: Some monitoring services can automatically update DNS records with the IP address of a failover machine when the primary machine is unreachable, thus eliminating the need for the third step; alternatively, you could update the DNS records manually in place of the third step. In either case, the DNS of the sync worker would need to be given an extremely short TTL (time-to-live) value. Changing the DNS record, whether automatically or manually, rather than editing configuration.yml may make your Object Server unreachable for a period of time (up to the TTL value, and potentially longer if a customer’s name server does not respect that setting).

Switching to a backup Realm Object Server

This requires load balancing with at least one sync-worker configured and running.

Prerequisites

Install the Realm Object Server on a secondary machine (this will be the “failover machine”), but do not start the server. Only one Object Server can be running in a cluster at a time.

Ensure the following files are identical between the running Realm Object Server and the backup server:

• configuration.yml
• token-signature.pub
• token-signature.key
• Any custom authorization providers

Triggering failover

When the primary Realm Object Server goes down, simply start the Object Server on the failover machine. On Ubuntu servers: systemctl start realm-object-server

Upon startup, the failover machine will load synced data from the sync-workers. Client Realm Mobile Databases should be pointing to the load balancer, thus needing no changes to their configurations. On Amazon Web Services, this could be accomplished by setting up an ELB with a health check running on the primary Object Server.

High Availability

One of the unique aspects of Realm Mobile Platform is that it is designed to be offline-first. Architecturally, clients retain a local copy of data from the server and read or write directly to their copy. The client SDK then sends the changes asynchronously when network connectivity is available and Realm Object Server automatically integrates these changes in a deterministic manner. Such a system is inherently highly available from the perspective of the client. Reads and writes can always occur locally irrelevant of the network conditions or server operations.

Realm is currently working on a clustering solution that supports automatic failover. This functionality will be available in the Enterprise Edition. To learn more and get early access, please contact us.

Continuous Backup

The Enterprise Edition of Realm Object Server includes a backup server running alongside the main process. This server monitors the state of a running Object Server, sending changes asynchronously to one or more backup clients. All clients maintain a slightly delayed copy of the server state.

You may continue to use the Manual Backup system described in the main Object Server documentation with the Enterprise Edition. (Manual backup is the only backup system provided for the Professional and Developer Editions.)

Backup Server

The backup server is installed as part of the realm-object-server and the realm-sync-worker. To enable it, run:

• RHEL/CentOS 6
• RHEL/CentOS 7
• Ubuntu 16.04

sudo chkconfig realm-object-server-backup-server on
sudo service realm-object-server-backup-server start

# Starts automaticaly when starting the realm-object-server
sudo systemctl enable realm-object-server
sudo systemctl start realm-object-server
sudo systemctl status realm-object-server-backup-server

sudo systemctl enable realm-object-server
sudo systemctl start realm-object-server
sudo systemctl status realm-object-server-backup-server

The configuration is done in the Realm Object Server YAML file (/etc/realm/configuration.yml) under the backup section. The keys used by the backup server are:

If backing up a node in a cluster of sync workers, the backup server will read the sync worker configuration file instead, located at /etc/realm/sync-worker-configuration.yml.

Backup Client

The Realm Object Server Backup Client is started on every machine where a backup is needed. The backup client is configured in a separate YAML file.

To install the backup client, you need to setup the enterprise repository as described above.

• RHEL/CentOS 6
• RHEL/CentOS 7
• Ubuntu 16.04

# Set the token variable:
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Setup Realm's Enterprise package repository. No need to do it if you already installed the ROS Enterprise
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.rpm.sh | sudo bash

# Install the Realm Object Server Backup Client
sudo yum -y install realm-object-server-backup-client

# Edit the configuration to point to an ROS with backup enabled. The default configuration assumes ROS and the Backup Server live on the same machine.
vim /etc/realm/object-server-backup-client.yml

# Enable and start the service
sudo chkconfig realm-object-server-backup-client on
sudo service realm-object-server-backup-client start

# Set the token variable:
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Setup Realm's Enterprise package repository. No need to do it if you already installed the ROS Enterprise
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.rpm.sh | sudo bash

# Install the Realm Object Server
sudo yum -y install realm-object-server-backup-client

# Edit the configuration to point to an ROS with backup enabled. The default configuration assumes ROS and the Backup Server live on the same machine.
vim /etc/realm/object-server-backup-client.yml

# Enable and start the service
sudo systemctl enable realm-object-server-backup-client
sudo systemctl start realm-object-server-backup-client

# Set the token variable:
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Setup Realm's Enterprise package repository. No need to do it if you already installed the ROS Enterprise.
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.deb.sh | sudo bash

# Update repositories
sudo apt-get update

# Install the Realm Object Server
sudo apt-get install realm-object-server-backup-client

# Edit the configuration to point to an ROS with backup enabled. The default configuration assumes ROS and the Backup Server live on the same machine.
vim /etc/realm/object-server-backup-client.yml

# Enable and start the service
sudo systemctl enable realm-object-server-backup-client
sudo systemctl start realm-object-server-backup-client

The configuration file is in /etc/realm/object-server-backup-client.yml.

The keys of the backup client configuration are

Synchronous Backup

The Enterprise Edition of Realm Object Server can maintain synchronous backups using the sync-worker system described in Load Balancing. Two sync workers act as a primary and a replica, communicating over the network. The replica receives incremental updates of all Realms after the primary has updated its own copies. If the primary sync worker fails, the Realm Object Server can continue by restarting the replica as the new primary and redirecting the proxy. With synchronous backups, client changesets uploaded to the primary are sent by the primary to the replica. After the replica saves its copy, it sends an acknowledgment back to the primary, which only then acknowledges the changeset’s successful save to the client.

Note: Instead of (or in addition to) synchronous backup, you may continue to use the Manual Backup system described in the main Object Server documentation with the Enterprise Edition. (Manual backup is the only backup system provided for the Professional and Developer Editions.)

One significant advantage of the synchronous backup system is that client resets should never happen, as long as the primary and replica don’t experience simultaneous data loss. A client reset happens when the local copy of a client’s Realm has a newer version than the copy on the Object Server the client is synchronized with. This can happen if the server crashed and was restored, but the local client made unsynced changes after the crash and before the restore. Under this circumstance, the local Realm is entirely replaced with the copy on the server.

The client Realm Mobile Database won’t erase any of its changeset data until after it receives acknowledgment of the successful upload. So, when you’re using the synchronous backup system, data won’t be lost unless both primary and replica fail at the same time: the client won’t get the acknowledgment until both the primary and replica have copies of the data.

In addition to preventing data loss, the synchronous backup system guarantees consistency of internal IDs and version numbers, so a primary can be replaced with a replica without affecting any clients.

Operating Modes

The backup system is built into the Sync Worker instead of being a separate system. A Realm Sync Worker can be started in one of four different modes:

• Primary with no replica: the standard sync worker that does not perform backup.
• Primary with asynchronous replica: A standard sync worker, with the addition that the server delivers its data to a connected replica. A primary with an asynchronous replica will never wait on its replica, and clients are always served immediately with minimal latency—however, there’s no longer a data loss guarantee, as the client receives a data write acknowledgment before the data is replicated.
• Primary with synchronous replica: A sync worker that ensures its data is copied successfully to a replica before it downloads and acknowledges data to a client. This system has slightly higher latency than a primary with an asynchronous replica, but protects against data loss.
• Replica: A sync worker acting as a replica for a primary sync worker. Replicas will not accept connections from clients.

Primaries use the same port for listening for Object Server connections and replica connections. At most one replica is allowed to be connected to a primary sync worker; if a new replica connects while an older replica is connected, the new replica will be given preference, and the older connection will be closed.

Replicas will keep trying to connect to their primaries until they succeed. If the connection is lost, the replica will continue to try to connect indefinitely.

It makes no difference whether a primary or a replica starts first.

Protocol

The Sync Workers have a backup protocol that allows exchange of data in two distinct ways: whole Realm transfer, or a history of incremental changes. Whole Realm transfer is most efficient when the replica starts from an empty slate. Rather than replaying a potentially very long history, the replica receives the whole Realm at once. The Realm backup system uses whole Realm transfer when the replica starts from scratch. Once the replica and primary are synchronized, the workers will switch to using incremental updates.

When a Realm is changed on the primary, the primary sends incremental updates to the replica. If the updates are lost due to a crash or network disconnect, they will never be regenerated. Instead, when the connection is re-established, the primary and replica will check the version numbers of their respective copies of the Realms, and if the primary is ahead of the replica, the whole Realm will be transferred again. (This should be a rare occurrence unless the environment has an excessive amount of network failures.) A sync worker can be reconfigured to be a primary with a replica at any point without migration.

Each Realm is backed up independently of all other Realms, so a downloading Sync client using one Realm will never be blocked by backup activity in other Realms.

Merging and Performance

There are two possible ways to deal with changeset merging on the replica: the replica repeats the merge computation performed by the primary, or the replica receives the result of the merge computation from the primary. The first method uses less network bandwidth, while the second uses less CPU time on the replica.

The Realm backup system lets the replica perform the merge except in cases where the merge computation is very slow. The primary measures the time to perform the merge computation, and in case of a long computation, the whole Realm is transferred to avoid a repeat of the slow merge computation.

Latency is (slightly) higher for a primary with synchronous backup than for the other types of primary. However, due to pipelining, a synchronous primary performs fewer write transactions than the other types of primaries in certain use cases. This could lead to situations where a primary with synchronous backup has higher performance than the two other types. (Of course, the two other types could be rewritten to use pipelining.)

Security

The Sync Workers communicate over unencrypted TCP by default; they can be configured to use TLS over TCP. TLS allows the backup connection to go through unprotected network intermediaries with minimal risk of eavesdropping and tampering.

A replica must present a shared secret to the primary in order to prove that it is allowed to receive backup data. The shared secret is a string and is configured in the configuration files for the primary and replica. A system administrator must generate shared secrets and enter them in the configuration files for the primary and replica.

Failover

When either the primary or replica fails with data loss, the system must be restarted in a new configuration.

The simplest case is when the replica fails. In that case, a new replica must be started and pointed towards the primary. In the case of primary failure, the replica must either be restarted as a primary or its root directory must be transferred to the location of a new primary. A new replica must also be started somewhere.

The proxies must always be configured to point to the primary.

Configuration

As with load balancing, sync workers are configured in a configuration.yml file. To switch configuration, a sync worker must be restarted with a new configuration file.

The new configuration options for backup: are:

• master_slave_shared_secret: the secret shared between the primary and its replica
• master_address and master_port: the connection information a replica uses to connect to its primary
• operating_mode: One of the four operating modes described above. Valid values are:
  • master_with_no_slave
  • master_with_asynchronous_slave
  • master_with_synchronous_slave
  • slave

If operating_mode isn’t specified, the default is master_with_no_slave, creating a normal sync worker with no replication.

If the sync worker is configured ad a replica, the configuration must specify the address/port of its primary (master). The primary address/port specified in the replica’s configuration file is the same as the listening address/port in the primary’s configuration.

The shared secret is sent by the replica to the primary during initial connection. The primary only proceeds with the backup exchange if the shared secrets match.

Here are sample configuration.yml files for a primary and replica, as well as a recovered primary and replica (that is, when a replica is manually promoted to take over as primary).

Primary

storage:
  root_path: root-dir-original-primary

network:
  sync:
    listen_address: '1.2.3.4'
    listen_port: '9001'

backup:
  operating_mode: 'master_with_synchronous_slave'

  master_slave_shared_secret: 'A secret'

Replica

storage:
  root_path: root-dir-original-replica

network:
  sync:
    listen_address: '5.6.7.8'
    listen_port: '9002'

backup:
  operating_mode: 'slave'

  master_address: '1.2.3.4'
  master_port: '9001'

  master_slave_shared_secret: 'A secret'

Recovered Primary (a replica promoted to a primary)

storage:
  root_path: root-dir-original-replica

network:
  sync:
    listen_address: '9.10.11.12'
    listen_port: '9003'

backup:
  operating_mode: 'master_with_synchronous_slave'

  master_slave_shared_secret: 'Possibly another secret'

Replica for Recovered Primary

storage:
  root_path: root-dir-new-replica

network:
  sync:
    listen_address: '13.14.15.16'
    listen_port: '9004'

backup:
  operating_mode: 'slave'

  master_address: '9.10.11.12'
  master_port: '9003'

  master_slave_shared_secret: 'Possibly another secret'

Notes:

• backup.master_address and backup.master_port of the replica must be the same as network.listen_address and network.listen_port of the primary.
• The root_path of the replica becomes the root_path of the next primary. It is also possible to copy the whole directory to another location while the sync worker is stopped.
• A replica still listens for incoming connections, even though it doesn’t accept sync connections. The endpoint /info is active for all sync workers including replicas.
• Proxies will have to be redirected if necessary.
• A communicating primary and replica must have the same secret, but the secret can be changed at any time.

Monitoring

Realm Object Server workers support sending metrics to statsd, which is assumed to be listening at localhost:8125. You can then forward these metrics to graphite or similar systems for monitoring.

All metrics keys start with a prefix of realm.<hostname>:

realm.example.com.connection.online
realm.example.com.connection.failed
realm.example.com.realms.open
realm.example.com.protocol.violated
realm.example.com.protocol.bytes.received
realm.example.com.authentication.failed

Metrics

Enabling Professional and Enterprise APIs

To use the Event Handling, Data Access and Data Connector features in Node.js applications, you must enable the APIs by including your access token in the application. (This token is sent to you via email when you sign up for a trial or purchase the Professional or Enterprise editions.) Near the start of your Node.js application, include your token and make a setAccessToken call to the Object Server:

var token = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...";

// Unlock Professional Edition APIs
Realm.Sync.setAccessToken(token);

The access token could also be loaded from a file rather than stored in your code:

RealmSync.setAccessToken(fs.readFileSync('./access-token', 'utf-8'));

Event Handling

An exclusive feature of the Enterprise and Professional Editions of Realm Object Server is event handling capabilities. This functionality is provided in the server-side Node.js SDK via a global event listener API which hooks into the Realm Object Server, allowing you to observe changes across Realms. This could mean listening to every Realm for changes, or Realms that match a specific pattern. For example, if your app architecture separated user settings data into a Realm unique for each user where the virtual path was /~/settings, then a listener could be setup to react to changes to any user’s settings Realm.

Whenever a change is synchronized to the server, it triggers a notification which allows you to run custom server-side logic in response to the change. The notification will inform you about the virtual path of the updated Realm and provide the Realm object and fine-grained information on which objects changed. The change set provides the object indexes broken down by class name for any inserted, deleted, or modified object in the last synchronized transaction.

Creating an Event Handler

To use Realm Event Handling, you’ll need to create a small Node.js application.

Create a directory to place the server files, then create a file named package.json. This JSON file is used by Node.js and npm, its package manager, to describe an application and specify external dependencies.

You can create this file interactively by using npm init. You can also fill in a simple skeleton file yourself using your text editor:

{
    "name": "MyApp",
    "version": "0.0.1",
    "main": "index.js",
    "author": "Your Name",
    "description": "My Cool Realm App",
    "dependencies": {
        "realm": "^1.8.0"
    }
}

We specify the Realm Mobile Platform as version 1.8 or higher. If you have other dependencies for your application, go ahead and specify them in the dependencies section of this file.

After the package.json file is configured properly, type:

npm install

to download, unpack and configure all the modules and their dependencies.

Your event handler will need to access the Object Server with administrative privileges, so you’ll need to get the Object Server’s admin token. Under Linux, view the token with:

cat /etc/realm/admin_token.base64

On macOS, the token is stored in the realm-object-server folder, inside the Realm Mobile Platform folder. Navigate to that folder and view the token:

cd path-to/realm-mobile-platform
cat realm-object-server/admin_token.base64

A sample index.js file might look something like this. This example listens for changes to a user-specific private Realm at the virtual path /~/private. It will look for updated Coupon objects in these Realms, verify their coupon code if it wasn’t verified yet, and write the result of the verification into the isValid property of the Coupon object.

var Realm = require('realm');

var ACCESS_TOKEN = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...";

// Unlock Professional Edition APIs
Realm.Sync.setAccessToken(ACCESS_TOKEN); 

// Insert the Realm admin token here
//   Linux:  cat /etc/realm/admin_token.base64
//   macOS:  cat realm-object-server/admin_token.base64
var ADMIN_TOKEN = 'ADMIN_TOKEN';

// the URL to the Realm Object Server
var SERVER_URL = 'realm://127.0.0.1:9080';

// The regular expression you provide restricts the observed Realm files to only the subset you
// are actually interested in. This is done in a separate step to avoid the cost
// of computing the fine-grained change set if it's not necessary.
var NOTIFIER_PATH = '^/.*/private$';

// The handleChange callback is called for every observed Realm file whenever it
// has changes. It is called with a change event which contains the path, the Realm,
// a version of the Realm from before the change, and indexes indication all objects
// which were added, deleted, or modified in this change
function handleChange(changeEvent) {
  // Extract the user ID from the virtual path, assuming that we're using
  // a filter which only subscribes us to updates of user-scoped Realms.
  var matches = changeEvent.path.match(/^\/([0-9a-f]+)\/private$/);
  var userId = matches[1];

  var realm = changeEvent.realm;
  var coupons = realm.objects('Coupon');
  var couponIndexes = changeEvent.changes.Coupon.insertions;

  for (var couponIndex of couponIndexes) {
    var coupon = coupons[couponIndex];
    if (coupon.isValid !== undefined) {
      var isValid = verifyCouponForUser(coupon, userId);
      // Attention: Writes here will trigger a subsequent notification.
      // Take care that this doesn't cause infinite changes!
      realm.write(function() {
        coupon.isValid = isValid;
      });
    }
  }
}

// create the admin user
var adminUser = Realm.Sync.User.adminUser(adminToken);

// register the event handler callback
Realm.Sync.addListener(SERVER_URL, adminUser, NOTIFIER_PATH, 'change', handleChange);

console.log('Listening for Realm changes');

The heart of the event handler is the handleChange() function, which is passed a changeEvent object. This object has four keys:

• path: The path of the changed Realm (used above with match to extract the user ID)
• realm: the changed Realm itself
• oldRealm: the changed Realm in its old state, before the changes were applied
• changes: an object containing a hash map of the Realm’s changed objects

The changes object itself has a more complicated structure: it’s a series of key/value pairs, the keys of which are the names of objects (i.e., Coupon in the above code), and the values of which are another object with key/value pairs listing insertions, deletions, and modifications to those objects. The values of those keys are index values into the Realm. Here’s the overall structure of the changeEvent object:

{
  path: "realms://server/user/realm",
  realm: <realm object>,
  oldRealm: <realm object>,
  changes: {
    objectType1: {
      insertions: [ a, b, c, ...],
      deletions: [ a, b, c, ...],
      modifications: [ a, b, c, ...]
    },
    objectType2: {
      insertions: [ a, b, c, ...],
      deletions: [ a, b, c, ...],
      modifications: [ a, b, c, ...]
    }
  }
}

In the example above, we get the Coupons and the indexes of the newly inserted coupons with this:

var realm = changeEvent.realm;
var coupons = realm.objects('Coupon');
var couponIndexes = changeEvent.changes.Coupon.insertions;

Then, we use for (var couponIndex of couponIndexes) to loop through the indexes and to get each changed coupon.

Integrating With Another Service

For a complete example of integrating the Event Handling framework with another service (in this case, IBM Watson’s Bluemix), read the tutorial for the Scanner App.

Data Access

The Professional and Enterprise Editions of the Realm Object Server allow you to access and change any shared Realm server-side using the administration token generated when you start the server. This allows access to all data in that Realm.

To retrieve the admin token on Linux:

cat /etc/realm/admin_token.base64

On macOS the token is stored in the realm-object-server folder within the zip:

cat realm-object-server/admin_token.base64

This can be used to synchronously construct a Realm.Sync.User object which can be passed into the Realm constructor to open a connection to any Realm on the server side.

// Open a Realm using the admin user
var adminToken = '3x4mpl3T0k3n…';
var adminUser = Realm.Sync.User.adminUser(adminToken);
var realm = new Realm({
  sync: {
    user: admin_user,
    url: 'realm://object-server-url:9080/my-realm',
  },
  schema: [{...}
  }]
});

Note that when used with an admin user, the Realm URL does not include the ~ character that resolves into the user ID for non-admin authentication; the admin user does not have a user ID. For non-admin authentication, read the Authentication section in the Object Server Access Control documentation.

Data Connector

The Enterprise Edition of the Realm Object Server offers a Node.js-based adapter API that allows you to access all low-level Object Server operations and data. This can be used to let a synced Realm interact with an existing legacy database such as PostgreSQL: the Realm will also be kept in sync with the external database in real time. Client applications can use the Realm Mobile Database API and get the benefits of working with real-time, native objects.

The Adapter API is set up in a very similar fashion to the Event Handler API described above. Create a small Node.js application by creating a directory to place the server files, then create a package.json for npm dependencies or use npm init to create it interactively.

{
    "name": "MyApp",
    "version": "0.0.1",
    "main": "index.js",
    "author": "Your Name",
    "description": "My Cool Realm App",
    "dependencies": {
        "realm": "^1.8.0"
    }
}

After your other dependencies are specified, use npm install to download, unpack and configure the modules.

As with the event handler API, you’ll need to access the Object Server with administrative privileges, and will need to get the Object Server’s admin token. Under Linux, view the token with:

cat /etc/realm/admin_token.base64

On macOS, the token is stored in the realm-object-server folder, inside the Realm Mobile Platform folder. Navigate to that folder and view the token:

cd path-to/realm-mobile-platform
cat realm-object-server/admin_token.base64

To use the Adapter API, the Node.js application you’re creating will act as a translator, receiving instructions from the Object Server and calling your external database’s API to read and write to it. A sample application might look like this:

var Realm = require('realm');

var ACCESS_TOKEN = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...";

// Unlock Enterprise Edition APIs
Realm.Sync.setAccessToken(ACCESS_TOKEN); 

var adapterConfig = {
  // Insert the Realm admin token here
  //   Linux:  cat /etc/realm/admin_token.base64
  //   macOS:  cat realm-object-server/admin_token.base64
  admin_token: 'ADMIN_TOKEN',

  // the URL to the Realm Object Server
  server_url: 'realms://127.0.0.1:9080',

  // local path for the Adapter API file
  local_path: './adapter',

  // regular expression to limit which Realms will be observed
  realm_path_regex: '/^\/([0-9a-f]+)\/private$/'
};

class CustomAdapter {
  constructor(config) {
    this.adapter = new Realm.Sync.Adapter(
      config.local_path,
      config.server_url,
      Realm.Sync.User.adminUser(config.admin_token),
      config.realm_path_regex,

      // This callback is called any time a new transaction is available for
      // processing for the given path. The argument is the path to the Realm
      // for which changes are available. This will be called for all Realms
      // which match realm_path_regex.
      (realm_path) => {
        var current_instructions = this.adapter.current(realm_path);
        while (current_instructions) {
          // if defined, process the current array of instructions
          this.process_instructions(current_instructions);

          // call advance to progress to the next transaction
          this.adapter.advance(realm_path);
          current_instructions = this.adapter.current(realm_path);
        }
      }
    )
  }

  // This method is passed the list of instructions returned from
  // Adapter.current(path)
  process_instructions(instructions) {
    instructions.forEach((instruction) => {
        // perform an operation for each type of instruction
        switch (instruction.type) {
          case 'INSERT':
            insert_object(instruction.object_type, instruction.identity, instruction.values);
            break;
          case 'DELETE':
            delete_object(instruction.object_type, instruction.identity);
            break;
          // ... add handlers for all other relevant instruction types
          default:
            break;
        }
      })
  }
}

Each instruction object returned by Adapter.current has a type property which is one of the following strings. Two or more other properties containing data for the instruction processing will also be set.

• INSERT: insert a new object
  • object_type: type of the object being inserted
  • identity: primary key value or row index for the object
  • values: map of property names and property values for the object to insert
• SET: set property values for an existing object
  • object_type: type of the object
  • identity: primary key value or row index for the object
  • values: map of property names and property values to update for the object
• DELETE: delete an existing object
  • object_type: type of the object
  • identity: primary key value or row index for the object
• CLEAR: delete all objects of a given type
  • object_type: type of the object
• LIST_SET: set the object at a given list index to an object
  • object_type: type of the object
  • identity: primary key for the object
  • property: property name for the list property to mutate
  • list_index: list index to set
  • object_identity: primary key or row number of the object being set
• LIST_INSERT: insert an object in the list at the given index
  • object_type: type of the object
  • identity: primary key for the object
  • property: property name for the list property to mutate
  • list_index: list index at which to insert
  • object_identity: primary key or row number of the object to insert
• LIST_ERASE: erase an object in the list at the given index: this removes the object
• from the list but the object will still exist in the Realm
  • object_type: type of the object
  • identity: primary key for the object
  • property: property name for the list property to mutate
  • list_index: list index which should be erased
• LIST_CLEAR: clear a list removing all objects: objects are not deleted from the Realm
  • object_type: type of the object
  • identity: primary key for the object
  • property: property name for the list property to clear
• ADD_TYPE: add a new type
  • object_type: name of the type
  • primary_key: name of primary key property for this type
  • properties: Property map as described in Realm.ObjectSchema
• ADD_PROPERTIES: add properties to an existing type
  • object_type: name of the type
  • properties: Property map as described in Realm.ObjectSchema
• CHANGE_IDENTITY: change the row index for an existing object: not called for objects with primary keys
  • object_type: type of the object
  • identity: old row value for the object
  • new_identity: new row value for the object

For full details, including all the instruction types and the data passed to them, consult the API reference for the Realm.Sync.Adapter class.

A PostgreSQL data connector is already implemented, and more are on the way, including MongoDB and Microsoft SQL Server. Any data connector can be customized to your application’s specific needs. If you’re a Realm Enterprise customer, contact your representative for more information.