Embedded Database in Unity

3 min readMay 22, 2023

In every application, it is often necessary to store data in a database or something similar. It can be for caching external information or processing data that is only accessible to the application’s user.

In Unity, there are at least 4 options to achieve that:

Today, I am going to talk about Realm which is the option I chose in one of my projects.

Realm was acquired by MongoDB in 2019, is open source and free to use. It can be used to store data and/or use it as a cache between the client application and the MongoDB database.

Package installation

To install Realm in your Unity project, you need to add a Scoped Registry. From the editor’s menu, go to Edit > Project Settings… then navigate to the Package Manager setting:

Add a new scoped registry by pressing the + button, enter the following details and press Apply:

Name:     Realm NPM (free to type anything)
URL:      https://registry.npmjs.org
Scope(s): io.realm.unity

Once added, you can navigate to the menu Window > Package Manager then select My Registries as shown below:

You can choose the version you want to install in your project.

Note that version 11.0.0 did not work properly when I tried with Unity 2023.1.25f1, so I chose 10.21.1 instead. But this may have changed when reading this article!

Edit: After upgrading to Unity 2022.3.0, version 11.0.0 worked without a glitch.

Using Realm

Describe Models

Using Realm is fairly simple. First, you define what you want to store in the database by creating Object Models:

A simple Realm Object Model

You only need to inherit from RealmObject.

Note that not all data types are supported. For instance, DateTime is not supported but DateTimeOffset is. Check here for a list of supported types.

Initialize the Database

To initialize the database, you call Realm.GetInstanceAsync with a RealmConfiguration as parameter.

Initializing the Realm Database and writing some data

Once initialized, you can start reading/writing to the DB. To write new data in the DB, use Realm.Add and wrap it with a Realm.Write call as shown above.

To read data, use the Find method:

Reading data from Realm Database

Weaving Assemblies

Realm does not magically know about your Object Models. Instead, it transforms your classes in a way that it understands about your Object Models.

Once you have created a new Object Model, you should see some logs related to RealmWeaver:

[Assembly-CSharp] Weaving completed in 3599 ms.
1 class was woven:
FileEntity
      FilePath: String [PrimaryKey]
      LocalPath: String
      RequestedDate: DateTimeOffset

If that does not happen, try to force it by going to Tools > Realm > Weave Assemblies:

Issue with Android

When using Realm, you can specify where to store the database file by passing its path as a parameter to the RealmConfiguration constructor:

Custom Realm DB Path may not work

On some Android devices (such as the Oculus Quest 2), the Application.persistentDataPath location does not support named pipe files. To sort this, you need to create those files in a separate location.

You can use the Android Context.FilesDir() method to get a location where you can create named pipe files. Once done, customize your RealmConfiguration FallbackPipePath with this folder as shown below:

Custom path for named pipe files in Realm Configuration

There is a lot more you can do with Realm. Do not hesitate to check on https://realm.io or on the MongoDB website.