Redb 0.0.4

Redb.NET

redb (An embedded key-value database) bindings for .NET and Unity.

English | 日本語

Overview

Redb.NET is a high-performance C# binding for redb, an embedded database implemented in Rust.

While SQLite is well-known as an embedded database, and LMDB or RocksDB as key-value databases, redb stands out as an excellent choice for its simplicity, stability, high performance, and support for concurrency.

Redb.NET provides a high-level binding for redb, offering an easy-to-use API for C#. The binding layer is carefully tuned for performance, ensuring no overhead.

Installation

NuGet packages

Redb.NET requires .NET Standard 2.1 or higher. Packages are available on NuGet.

Package	Description	Latest Version
Redb	The main package for Redb.NET.
Redb.SystemTextJson	Extension package supporting serialization with System.Text.Json.
Redb.MessagePack	Extension package supporting serialization with MessagePack for C#.

Unity

For Unity, all packages, including extension packages, can be installed via the Package Manager.

1. Open the Package Manager from Window > Package Manager.
2. Click the "+" button > Add package from git URL.
3. Enter the URL for the corresponding package.

To use the extension packages, you need to separately add System.Text.Json or MessagePack using tools like NugetForUnity.

Platforms

Redb.NET supports the following platforms:

Quick Start

using Redb;

using var db = RedbDatabase.Create("test.redb", RedbDatabaseOptions.Default);

using (var tx = db.BeginWrite())
{
    using (var table = tx.OpenTable<string, int>("my_table"))
    {
        table.Insert("foo", 12);
        table.Insert("bar", 30);
    }

    tx.Commit();
}

using (var tx = db.BeginRead())
{
    using (var table = tx.OpenTable<string, int>("my_table"))
    {
        var foo = table.Get("foo");
        Console.WriteLine($"foo: {foo}");

        if (table.TryGet("bar", out var bar))
        {
            Console.WriteLine($"bar: {bar}");
        }
    }
}

Table API

You can open Table/ReadOnlyTable using OpenTable(). Both generic and non-generic types are available.

// generic table
using var table1 = tx.OpenTable<string, int>("my_table");

// non-generic table
using var table2 = tx.OpenTable("my_table");

In Table<TKey, TValue>/ReadOnlyTable<TKey, TValue>, the keys and values are strongly typed when reading and writing values.

table1.Insert("foo", 1);
int value = readOnlyTable1.Get("foo");

This is automatically serialized by the IRedbEncoding set in RedbDatabase. By default, primitive types and some other types are supported, but you can support any type by connecting a serializer. See the C# Serialization section for details.

In Table/ReadOnlyTable, you can directly read and write untyped binary data.

table2.Insert("foo"u8, "bar"u8);
RedbBlob blob = readOnlyTable2.Get("foo"u8);

RedbBlob is a struct that wraps a pointer on the Rust side. You can read values without overhead through this, but you must dispose of it with Dispose().

var span = blob.AsSpan();
span.CopyTo(buffer);
blob.Dispose();

Compaction

You can perform compaction by calling Compact().

db.Compact();

The default size of a redb database file is over 1MB, but compaction can reduce it to a few dozen KB.

C# Serialization

By default, binary (ReadOnlySpan<byte>), primitive types, Guid, DateTime, and TimeSpan can be used as keys or values. By connecting a serializer to the database, you can use any object as a key or value.

Currently, System.Text.Json and MessagePack for C# are supported.

using Redb;
using Redb.SystemTextJson;
// using Redb.MessagePack;

using var db = RedbDatabase.Create("test.redb", RedbDatabaseOptions.Default)
    .WithJsonSerializer(); // or .WithMessagePackSerializer();

using (var tx = db.BeginWrite())
{
    using (var table = tx.OpenTable<string, Person>("persons"))
    {
        table.Insert("alice", new Person("Alice", 18));
        table.Insert("bob", new Person("Bob", 30));
    }

    tx.Commit();
}

using (var tx = db.BeginRead())
{
    using (var table = tx.OpenTable<string, Person>("persons"))
    {
        var alice = table.Get("alice");
        var bob = table.Get("bob");
        Console.WriteLine(alice);
        Console.WriteLine(bob);
    }
}

record Person(string Name, int Age);

Supported Features

Redb.NET is currently in preview, and some features like MultimapTable are not yet implemented in the C# API. These are planned to be supported in the stable release.

License

This library is provided under the MIT License.