CatDb 2.0.0

CatDb

<img src="https://raw.githubusercontent.com/OmidID/CatDb/master/images/nuget.png" align="left" width="128">

CatDb is a high-performance ordered key-value database for .NET, built around the Waterfall Tree (WTree): https://ieeexplore.ieee.org/document/6857846.

CatDb started from STSdb4, but this project has evolved substantially and now differs significantly in architecture, behavior, and public API.

Deployment Model

CatDb is server-first. Run it as a dedicated service via CatDb.Server (ASP.NET Core with HTTP/TCP APIs), or embed it as a library directly in your .NET process. Both use the same high-performance engine.

Installation

Package	Description	Version
CatDb	Database engine library

Why CatDb

• Server or embedded: run as a service or link directly into your process.
• Ordered key storage with efficient forward/backward/range scans.
• Write-optimized WTree internals for heavy mixed workloads.
• Secondary index support in the public API.
• Fluent query builders for key and index queries.
• Supports non-primitive keys/fields (including composite/object types with comparers).

Quick Start

using CatDb.Database;

using var engine = CatDb.Database.CatDb.FromFile("app.catdb");
var users = engine.OpenXTable<long, User>("users");

users[1] = new User("ada@example.com", "Ada", "London");
users[2] = new User("grace@example.com", "Grace", "New York");

engine.Commit();

if (users.TryGet(1, out var user))
	Console.WriteLine($"{user.Email} / {user.City}");

public sealed record User(string Email, string Name, string City);

Fluent Queries

using CatDb.Extensions;

// Primary key query
var page = users.Query().AtLeast(1).Take(100).ToList();

// Descending query
var last10 = users.Query().Backward().Take(10).ToList();

Secondary Indexes

using CatDb.Database.Indexing;
using CatDb.Extensions;

users.CreateIndex("Email", x => x.Email, IndexType.Unique);
users.CreateIndex("City", x => x.City, IndexType.NonUnique);

var byEmail = users.Query(x => x.Email).Equals("ada@example.com").FirstOrDefault();
var london = users.Query(x => x.City).Equals("London").Take(20).ToList();
var londonCount = users.Query(x => x.City).Equals("London").Count();

Build and Validation

dotnet build --no-incremental
dotnet test --no-build
dotnet run --project examples/CatDb.GettingStarted

Optional stress run:

cd examples/CatDb.StressTest
dotnet run -c Release -- --duration 120

Documentation

• Documentation site source
• Quick start
• Index and search
• Architecture
• API reference
• Troubleshooting

Waterfall Tree Reference

Background paper on Waterfall Tree concepts: https://ieeexplore.ieee.org/document/6857846/references

License

MIT License — Copyright (c) 2024-2026 CatDb. See LICENSE for full text.

Free to use in personal, commercial, and proprietary projects.