RizeDb 3.0.0

dotnet add package RizeDb --version 3.0.0
                    
NuGet\Install-Package RizeDb -Version 3.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="RizeDb" Version="3.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="RizeDb" Version="3.0.0" />
                    
Directory.Packages.props
<PackageReference Include="RizeDb" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add RizeDb --version 3.0.0
                    
#r "nuget: RizeDb, 3.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package RizeDb@3.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=RizeDb&version=3.0.0
                    
Install as a Cake Addin
#tool nuget:?package=RizeDb&version=3.0.0
                    
Install as a Cake Tool

RizeDb

An embedded object and document database for .NET 10 and .NET Standard 2.0. Store your classes as they are, in a single file inside your process, with no server to run and no schema to declare.

using RizeDb;
using RizeDb.ObjectOriented;

using var stream = new FileStream("orders.db", FileMode.OpenOrCreate, FileAccess.ReadWrite);
using var store = new ObjectStore(stream);

if (!store.TryGetObjectCollection("orders", out var orders))
{
    orders = store.CreateObjectCollection("orders");
}

var order = new Order { Number = "1001", Date = DateTime.UtcNow, Items = new() };
orders.Store(order);                                // order.Id is filled in

var match = orders.FirstOrDefault<Order>(o => o.Number == "1001");

public class Order
{
    public long Id { get; set; }                    // the only required property
    [Index(IndexSearchOptions.String)] public string Number { get; set; }
    public DateTime Date { get; set; }
    public List<OrderItem> Items { get; set; }
}

public class OrderItem
{
    public string Name { get; set; }
    public int Quantity { get; set; }
}

Why RizeDb

  • No mapping layer. Any class with a long Id can be stored, including its nested objects and lists, as one record.
  • Schema changes without migrations. Add properties, or change a property's type, without rewriting stored data. Values convert when they are read.
  • Crash-safe ACID transactions. Commits go through a write-ahead log. A process crash loses nothing that was committed, and a power cut can lose only the last few seconds of commits without corrupting the file.
  • Fast reads. Fetching a record by id took about 0.4 µs in the benchmark below.
  • Queries you can write in C#. Use lambdas over indexed properties, unindexed properties and child objects.
  • Safe to share across threads. One store serves any number of threads. Reads run concurrently and writes are serialised.
  • Sync and async. Operations have both forms: Store and StoreAsync, Retrieve and RetrieveAsync, and so on.
  • Optional AES encryption. Pass a password and every page is encrypted.
  • No third-party dependencies. Works with any seekable Stream, including a MemoryStream. The .NET 10 build has no dependencies at all, and the .NET Standard build uses only Microsoft packages.

Querying

Mark the properties you search often with [Index]. Queries on other properties still work, but they read every record.

var cutoff = DateTime.UtcNow.AddDays(-7);
var recent = orders.Retrieve<Order>().Where(o => o.Date > cutoff).ToList();

var withFlashlights = orders.Retrieve<Order>()
    .Where(o => o.Items.Any(i => i.Name == "Flashlight"))
    .ToList();

Updating and removing

orders.Store(order);                                       // an existing Id replaces the record
orders.Update<Order>(order.Id, new { Number = "1001-A" }); // changes only these properties
orders.Remove(order.Id);

Reading into a different class

Read a record into any class whose properties match the ones you need. A type can differ from the stored one as long as the value converts.

public class OrderHeader
{
    public long Id { get; set; }
    public string Number { get; set; }
}

var header = orders.Retrieve<OrderHeader>(order.Id);

Document collections

Document collections index by property path, including nested paths, and can be keyed by long or Guid.

using RizeDb.DocumentOriented;

if (!store.TryGetDocumentCollection<long>("people", out var people))
{
    store.CreateDocumentCollection("people", DocumentKeyType.Long, "Name", "Address/City");
    people = store.GetDocumentCollection<long>("people");
}

var id = people.Store(new Person { Name = "Ada", Address = new Address { City = "London" } });
var londoners = people.Where<Person>(p => p.Address.City == "London");

Transactions

A single write is its own transaction. To commit several together, use a group. If the action throws, the whole group rolls back.

store.ProcessTransactionGroup(group =>
{
    var batch = group.GetObjectCollection("orders");
    foreach (var newOrder in newOrders)
    {
        batch.Store(newOrder);
    }
});

Writes are queued and run when the action returns, so reads inside a group see only committed data. The group holds the store's only writer until it commits, so keep slow work out of the action.

Durability

You choose how soon a commit reaches the physical disk.

Stream Behaviour Closest SQLite setting
FileStream Commits survive a process crash. The log is synced in the background once commits stop for a second, and at least every five seconds. synchronous=OFF while writing, with periodic syncs
MappedFileStream with MappedFlushMode.None The operating system writes data out in its own time. synchronous=OFF
MappedFileStream with MappedFlushMode.Idle Writes don't wait for the disk, and one sync runs when writing goes quiet. About synchronous=NORMAL
MappedFileStream with MappedFlushMode.Full Every commit waits for the disk. synchronous=FULL
using var stream = new MappedFileStream(
    "orders.db",
    MappedFileStream.DefaultMinimumSize,
    MappedFileStream.DefaultGrowIncrement,
    MappedFlushMode.Idle);
using var store = new ObjectStore(stream);

On any stream, store.Flush() forces data to the device at a point you choose.

Encryption

using var store = new ObjectStore(stream, "correct horse battery staple");

Performance

Time per operation with the same record and two indexes on a file with 10,000 records, measured with BenchmarkDotNet on a Ryzen 9 7900X and .NET 10. Lower is better.

Read RizeDb SQLite Realm LiteDB
By id 0.4 µs 3.5 µs 1.8 µs 10.0 µs
By indexed string 2.8 µs 3.9 µs 116.7 µs 12.7 µs
100 records by indexed range 43.8 µs 56.7 µs 170.1 µs 3,253 µs

Writes commit one record per transaction on a real file, at matching durability settings. RizeDb and SQLite are close overall, and SQLite is ahead with syncing off.

Write RizeDb Off SQLite Off RizeDb Normal SQLite Normal RizeDb Full SQLite Full
Insert 35 µs 26 µs 36 µs 27 µs 2.00 ms 2.06 ms
Update 34 µs 19 µs 38 µs 43 µs 1.99 ms 2.06 ms
Remove 49 µs 19 µs 49 µs 41 µs 2.01 ms 2.15 ms

RizeDb allocates more per write than SQLite. Results will vary with your hardware, record shape and workload, so measure your own case if speed matters.

Good to know

  • Target frameworks: .NET 10 and .NET Standard 2.0, tested on .NET Framework 4.8. Files read the same on both. Performance figures are for .NET 10, which is the target RizeDb is tuned for.
  • Upgrading from 2.x: Version 3.0 uses file format 5, and files written by 2.5.1 and earlier don't open. Applications built against 2.x must be recompiled or given a binding redirect.
  • One process: RizeDb coordinates threads within a process, and isn't designed for several processes writing to one file.
  • One writer at a time: Write-heavy workloads can't scale across threads, because writes are serialised.
  • Dispose the store: Dispose it when you finish so the next open has no log to replay.
  • Failed writes recover once: If a write fails, it throws and is not stored, and the next call restores the store from its log with no committed data lost. WriteCommittedException means the write was stored and a later step failed, so don't retry it. A second failure, a failed recovery or a failed disk sync makes the store refuse further work until you reopen the file.
  • Type changes: Only change a property to a type every stored value converts to. A value that can't convert throws ValueConversionException, and the record and database are unaffected.

License

Apache 2.0

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on RizeDb:

Package Downloads
EnvironmentVault2.Shared

Supporting assembly for Environment Vault.

EnvironmentVault.Shared

Companion assemblies for Environment Vault

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
3.0.0 191 10/31/2026
2.5.0 483 6/5/2025
2.4.0 213 3/15/2025
2.3.0 310 3/13/2025
2.2.0 393 12/24/2024
2.0.0 329 8/28/2024
2.0.0-beta5 273 8/11/2023
2.0.0-beta4 308 1/23/2023
2.0.0-beta3 389 9/18/2022
2.0.0-beta2 382 9/18/2022
2.0.0-beta 330 9/6/2022
1.6.5 753 7/20/2021
1.6.0 583 5/16/2021
1.5.0 758 4/11/2021
1.4.0 757 4/8/2021
1.3.5 581 3/21/2021
1.3.0 907 9/16/2020
1.2.0 674 9/10/2020
1.1.0 729 8/19/2020
1.0.2 709 7/9/2020
Loading failed

3.0.0: Breaking: this version uses file format 5, and files written by 2.5.1 and earlier (format 4) do not open. This package has no converter, so convert existing files before upgrading. The assembly version is now 3.0.0.0, so applications built against 2.x must be recompiled or given a binding redirect. New: RizeDb now also targets .NET Standard 2.0, tested on .NET Framework 4.8, and files read the same on both targets. That target depends on System.Memory, System.Runtime.CompilerServices.Unsafe, System.Threading.Tasks.Extensions, System.Reflection.Emit and System.Reflection.Emit.Lightweight; .NET 10 has no dependencies. Crash safety: format 5 adds a checksummed write-ahead log and checkpoints, so a store recovers its committed data after a power cut. New ObjectStoreOptions controls background log syncing, SyncLog forces a sync, and MappedFlushMode.Full makes commits on a mapped file durable. Failed writes: a failed write no longer stops the store for good. The write throws and is not stored, and the next call restores the store from its log. A store recovers once; a second failure, a failed recovery or a failed disk sync makes it refuse further work until the file is reopened. New WriteCommittedException means a write was stored and a later step failed, so don't retry it. New ObjectStore.Recovered event reports each recovery. Fixes: a writer queued behind a failing commit could be told it succeeded while its record was lost (Release builds). A read that runs out of memory or system resources, a throwing query predicate, mixed-type range bounds, and an Update with an unknown property or wrong-typed value no longer put the store into its bad state, and the refusal now names the original cause. Query fixes include Nullable HasValue, negated Any, Any and Contains over a null sequence, and document queries on unindexable types. Also new: Verify checks a store's integrity, and document collections work in transaction groups.