Realm Browser Tutorial

Despite popular opinion, Realm isn’t a wrapper for SQLite and doesn’t touch SQLite files on disk. Realm is a completely proprietary standard, written in C++ that is then exposed to developers via a number of different public API libraries.

On disk, Realm saves its data as .realm files, which are otherwise completely opaque binary blobs. You CAN open them up in a hex editor, but there won’t be much that’s recognizable in there. Without writing an app that’s using Realm’s C++ package, it’s not possible to view the contents of a .realm file.

Enter the Realm Browser!

The What?

The Realm Browser is a small application to make viewing the data inside any given Realm file quick and easy. When a ‘.realm’ file is opened, the Realm Browser displays a window with two columns. The column on the left shows all of the model classes of the objects stored by the Realm file, and the column on the right shows a spreadsheet of all of the objects in the Realm file. Double clicking on any of the properties of an object will let you edit those properties, with the new changes immediately being saved to the Realm file.

The Realm Browser also implements Realm’s cross-process notification system. What this means in practice is that if you open a Realm file in the Browser that’s in an app presently running in the iOS Simulator/Android Emulator, any code in the app that causes the data in that Realm file to change, will instantly be updated in the Browser as well.

The Browser also features a few other niceties, such as being able to export compacted copies of Realm files (Great for shipping pre-built Realm files with apps) as well as dynamically generating the class definitions of the types of objects inside it.

How Does it Work?

Normally, it’s necessary for developers to implement model classes into their apps, and these are used at runtime to generate the Realm schema and to subsequently query for data. Because the Realm Browser only has access to the Realm file on disk and none of these model objects, it goes about opening Realm files a little differently.

While it’s not publicly documented nor supported, the Cocoa and Java versions of Realm feature a set of APIs that make up what is called the ‘Dynamic API’. The Dynamic API allows Realm to view and manipulate the contents of Realm file without requiring the normal additional runtime information (Such as the model classes). When instantiating a Realm instance from code with the Dynamic API enabled, it’s possible to query the schema from that instance, and to then query for objects which will be returned as the base Realm Object class. These objects are still KVC-compliant, so it’s possible to read and write data from them, just as if they were dictionary objects.

The Realm Browser makes heavy use of the Dynamic API in order to display the contents of Realm files. When a file is opened, the Browser will instantiate a new Realm object, and use that to generate a schema graph. This graph is used to determine the names of each model object type stored by this Realm, and the names of every property in order to set up the columns in the spreadsheet view. Once the user clicks on a model type in the column on the left, a standard Realm ‘get all objects’ query is run, and the results of the query are passed to the spreadsheet.

The Realm Mobile Platform

When working with the Realm Mobile Platform, synchronized Realms are handled a little differently. It’s not possible to simply open them up like traditional Realm files since they rely on having a network connection to the Realm Object Server.

Luckily, the Realm Browser also provides support for synchronized Realms. When choosing to open a Realm file in the Browser, there is an option to connect to an active instance of the Realm Object Server. After entering in the URL and the credentials for an admin account, the Browser will present a list of all of the synchronized Realm files belonging to that account that you can open.

When you open a synchronized Realm with the Realm Browser, a local copy of that Realm will be created specifically for the Browser. In this way, you’re not piggy-backing off another device’s credentials, the Browser itself becomes another connection to the shared Realms.

Realm Browser on Mobile

Officially, Realm only provides the macOS Realm Browser as the official client at the time of writing. That being said, several third parties have developed drop-in libraries that allow debug builds of apps to expose the contents of their Realm files.

Realm Browser by Jonas Rottmann (Android)

Realm Browser by Max Baumbach (iOS)

(And here’s a sneak peek of another Browser for iOS!)

The Future of the Desktop Browser

The Realm Browser for macOS was originally released when there were no other versions of Realm except for Objective-C. As times have definitely changed since then, there’s been a lot of internal discussion about the future of the Browser in its current form. Now that various versions of Realm are in a position that they can be run on Windows and Linux in addition to macOS, the need for Browsers on other platforms has become much more important.

Ideally, to minimize the amount of engineering resources and maintenance overhead, a single cross-platform codebase that could be deployed to any platform would be the best. Now that Realm supports Node.js, there’s discussion about creating a new version of the Browser using Electron to produce crossplatform apps similar to desktop clients the likes of Atom and Slack.

While there’s nothing formal to announce yet, there’ll definitely be some exciting changes to the Browser coming soon!