Home

Awesome

UltraLiteDB - A bare-bones C# .NET Key-value Store in a single database file, intended for use in Unity

UltraLiteDB is a trimmed down version of LiteDB 4.0 (http://www.litedb.org). Anything that needs Linq or dynamic code generation has been removed to make it work in Unity's IL2CPP AoT runtime environment. Some additional features have been removed to reduce code footprint. What's left is a very small, fast key-value store that lets you save and load BSON-encoded data in any Unity environment.

Major features missing from LiteDB

So what's still there?

Use case

This is a great library to use for any project that needs to store lots of mutable data in a convenient and accessible way. For example:

It could also be useful for large amounts of read-only data as well, where you need to locate records in a data-file too large to keep in memory all the time:

Documentation

For basic CRUD operations, the LiteDB documentation largely applies to UltraLiteDB.

The biggest difference is that any query or index method using a linq expression method are missing.

Installing in a Unity project

Download the UltraLiteDB.dll from the Releases page and put it in the ./Assets/Plugins folder of your Unity project. That should be it!

How to use UltraLiteDB

A quick example for storing and searching documents:

using UltraLiteDB;

void DatabaseTest()
{
    // Open database (or create if doesn't exist)
    var db = new UltraLiteDatabase("MyData.db")

    // Get a collection
    var col = db.GetCollection("savegames");

    // Create a new character document
    var character = new BsonDocument();
    character["Name"] = "John Doe";
    character["Equipment"] = new string[] { "sword", "gnome hat" };
    character["Level"] = 1;
    character["IsActive"] = true;
	
    // Insert new customer document (Id will be auto generated)
    BsonValue id = col.Insert(character);
    // new Id has also been added to the document at character["_id"]

    // Update a document inside a collection
    character["Name"] = "Joana Doe";
    col.Update(character);

    // Insert a document with a manually chosen Id
    var character2 = new BsonDocument();
    character2["_id"] = 10;
    character2["Name"] = "Test Bob";
    character2["Level"] = 10;
    character2["IsActive"] = true;
    col.Insert(character2);

    // Load all documents
    List<BsonDocument> allCharacters = new List<BsonDocument>(characters.FindAll());

    // Delete something
    col.Delete(10);

    // Upsert (Update if present or insert if not)
    col.Upsert(character);

    // Don't forget to cleanup!
    db.Dispose();
}

To be done

The BsonDocument class generates garbage every time you load or save to the database. I'm investigating allowing custom allocators and object reuse pools to reduce garbage generation from load and save operations. I don't think this library can be made 100% garbage free, but there is currently much room for improvement.

Building

To build UltraLiteDB yourself:

  1. Make sure you have a recent .NET Core SDK installed (https://dotnet.microsoft.com/download)
  2. Download or clone this repository
  3. dotnet build -c Release
  4. Your new DLL is at ./UltraLiteDB/bin/Release/netstandard2.0/UltraLiteDB.dll

License

MIT

Copyright (c) 2017 - Maurício David

Thanks

This project is entirely built upon Maurício David's excellent LiteDB, and would not exist without it.