Internal link icon Looking to install the Enterprise Edition?

Getting Started with Realm Platform Developer Edition

The Realm Platform is a next-generation data layer for applications. At the core of it is, Realm Object Server, which provides realtime data synchronization of Realm databases. This guide will walk you through installing the server and syncing your first data!

Realm Platform also comes in Professional and Enterprise Editions. Learn more about the different Editions.

Installing Realm Object Server

The biggest change with Realm Platform 2.0 is that we have rebuilt Realm Object Server to take advantage of the Node.js ecosystem. The codebase is written in Typescript and is designed to be fully customizable for the specific needs of our customers. We are striving to make the server as easy to install and operate as possible!

The simplest method of installation is by using our install script, which will resolve all prerequisites for you:

curl -s https://raw.githubusercontent.com/realm/realm-object-server/master/install.sh | bash

To install manually you can follow the instructions in the documentation.

Once the server is installed, it includes a command-line interface. Let’s use this to create your first project:

ros init my-app

This creates a Typescript-based Node project for you. Later on you can explore customizing it but for now simply start the server with defaults by:

cd my-app/
npm start

That’s it! You now have a functioning Realm Object Server running locally on port 9080! The server is tied to your terminal window for now and can be stopped by pressing Ctrl-C.

Administering Realm Object Server

Realm Object Server 1.x included a web dashboard that you could login to which provided basic statistics, logs, and the ability to view the users and Realm data in the server. With Realm Platform 2.0, we have moved this functionality into a desktop application called Realm Studio. The reason for this change was that we wanted to unify the experience of working with Realm data across both open-source Realm database developers, which could use a macOS application called Realm Browser, and Realm Platform developers. Realm Studio runs on macOS, Windows, and Linux and is the starting point for all Realm developers!

To get started with Realm Studio download the latest release:

Using Realm Studio

When you first start the app, you are presented with a welcome screen:

Choose “Connect to Realm Object Server” so we can connect to the ROS running locally.

You are presented with a login screen, which includes defaults. You don’t have to type anything on this screen since the server is running locally at localhost:9080 and ROS automatically creates an admin user with username: realm-admin and password: “” (empty string). Just press “Connect” to continue!

The next screen shows the current layout of the ROS dashboard functionality. You can view the Realms in the server, the list of Users, and Logs. The two main parts are the ability to view Realm data via a browser, which is possible by clicking on a Realm, and creating/editing users via the Users tab:

Syncing My First Data With Realm Object Server

Since there is no data yet in the server, let’s use realm-js to create a sample data set.

To complete this step, you will need to sign up for our Professional Edition trial here.

A token will be emailed to you that you can use in the sample application.

On your computer, create a new directory and run:

npm init

// This will ask you for info on your Node app, 
// just press Return until it creates a `package.json` for you

Next, let’s install the dependencies for you sample app:

// Install Realm 2.0 and save to package.json
npm install realm -S

// Install Faker library used by script and save to package.json
npm install faker -S

Create a file called index.js and paste in the following code:

const faker = require('faker')
const Realm = require('realm')
const fs = require('fs')

var totalTickers = 100
var username = "realm-admin"
var password = ""
var URL = "127.0.0.1:9080"

const TickerSchema = {
  name: 'Ticker',
  primaryKey: 'tickerSymbol',
  properties: {
    tickerSymbol: { type: 'string', optional: false },
    price: { type: 'int', optional: false },
    companyName: { type: 'string', optional: false },
  }
}

var token = "<INSERT YOUR PROFESSIONAL EDITION TOKEN>";

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

function generateRandomTickerSymbol(len) {
  charSet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
  let randomString = '';
  for (let i = 0; i < len; i++) {
    let randomPoz = Math.floor(Math.random() * charSet.length);
    randomString += charSet.substring(randomPoz, randomPoz + 1);
  }
  return randomString;
}

function getStarted() {
    Realm.Sync.User.login(`http://${URL}`, username, password)
    .then(user => {
        Realm.open({
            sync: {
                url: `realm://${URL}/tickers`,
                user: user
            },
            schema: [TickerSchema],
        })
        .then(realm => {
            let tickerResults = realm.objects('Ticker')
            // Add some data to the tickers Realms
            if (tickerResults.length < totalTickers) {
                realm.write(() => {
                    for (let index = 0; index < totalTickers; index++) {
                        realm.create('Ticker', {
                            tickerSymbol: generateRandomTickerSymbol(3),
                            price: index,
                            companyName: faker.company.companyName()
                        }, true)
                    }
                })
            }

            tickerResults.addListener((objects, changes) => {
                changes.modifications.forEach((index) => {
                    var ticker = objects[index];
                    console.log(`Ticker ${ticker.companyName} - ${ticker.tickerSymbol} - ${ticker.price}`)
                });
            })
        })
    })
}

getStarted()

This sample application will login to your ROS running locally via the default admin user and then create 100 Ticker objects in a synced Realm at path: /tickers. Just run the application via:

node index.js

You will now see /tickers in Realm Studio:

Click on the /tickers row to open the browser:

The script also registers a listener to react to changes, so try editing the companyName property on one of the Ticker objects, you will see something like this print in your console:

Congrats you have successfully synced your first data with Realm Object Server 2.0!

Using Partial Synchronization

Part of Realm Platform 2.0, we are launching a preview of partial synchronization. This is a new and exciting capability where client applications can dynamically request data from Realm Object Server by registering queries. This is a major change in how application developers can use Realm in their apps. Previously, applications would need to segment their data into multiple Realms to control which data is synced at a given time. Now this can be done entirely in a single Realm!

Add this function to your code:

function partialSyncTickers(greaterThanPrice) {
    Realm.Sync.User.login(`http://${URL}`, username, password)
    .then(user => {
        Realm.open({
            sync: {
                url: `realm://${URL}/tickers`,
                user: user,
                partial: true
            },
            schema: [TickerSchema],
        })
        .then(realm => {
            console.log(`Adding query to partially sync all Tickers greater than ${greaterThanPrice}`)

            realm.subscribeToObjects('Ticker', `price > ${greaterThanPrice}`)
            .then((results, error) => {
                console.log(`Partially synced ${results.length} Tickers`)

                results.addListener((results, changes) => {
                    if (changes.insertions.length > 0) {
                        console.log(`Partially synced ${results.length} Tickers`)
                    }
                    changes.modifications.forEach((index) => {
                        var ticker = results[index];
                        console.log(`Updated Partial Synced Ticker ${ticker.companyName} - ${ticker.tickerSymbol} - ${ticker.price}`)
                    })
                })
            })
        })
    })
}

Let’s walk through what this function does, step by step:

  1. Like the getStarted() function, the first step is to login and get a User object.
  2. Next, we open up a synced Realm and we add partial: true to the sync configuration. This is how you specify a partially synced Realm!
  3. After we open the partially synced Realm, initially there is no data. The next step is to register a query. To do so, requires using a new API Realm.subscribeToObjects() We check if there are already objects in the Realm and if not, we subscribe with the query: price > ${greaterThanPrice}.
  4. Finally, we register a listener on a query of the local Realm for all Ticker objects so that we can react to the new data that the server will partially sync. When new data arrives, we print the number of Ticker objects that were synced. After that, we will print out when any changes are made.

Now comment out getStarted() and instead run the partial sync function:

// getStarted()

partialSyncTickers(10)

Given that we previously synced the entire /tickers Realm, we need to clear out our data locally by running:

// Run in the same directory as `index.js`
rm -rf realm-object-server/

Now, simply re-run the index.js file and now you will instead just sync the data that matches the partial sync query!

node index.js

In Realm Studio, you will now see there is a partially synced Realm (the number “10” will be a random ID):

Open the partially synced Realm:

You will see that there is only the number of Ticker objects in the Realm that match the query! Try editing the companyName again for one of the Ticker objects which will print to your console:
Congrats!

You have partially synced your first Realm. The same subscribeToObjects() API is provided in all Realm SDKs, so we recommend as a next step to try building a mobile application with partial sync (sample apps will be provided in the future).

What’s next?

If you’ve never used the Realm Database before, you might want to start by picking your platform and checking the docs. There, you’ll learn about what makes our database unique, like the power of live objects, auto-updating queries, and the freedom from ever having to use an ORM again. Or, you can follow a tutorial to build an iOS app similar to RealmTasks from scratch.

If you’re more familiar with the Realm Platform, then jump right into the Realm Object Server documentation documentation.