Quick start

CatDb is a .NET library. The current documented release is v2.0.3.

Add the package with the same version:

dotnet add package CatDb --version 2.0.3

CatDb is server-first: point client code at a running CatDb.Server/TCP server and open tables the same way you would locally. Linking the engine directly into your process (no server) is the other supported mode, for single-process apps, tests, and demos.

Once you have an engine — remote or in-process — open a table, write records, and call Commit() when those writes must survive process exit.

using CatDb.Database;

using var engine = CatDb.Database.CatDb.FromConnectionString(
    "Provider=Network;Host=localhost;Port=7182;Database=default;User Id=admin;Password=admin");

var users = engine.OpenXTable<long, User>("users");
users[1] = new User("Ada", "Lovelace");
users[2] = new User("Grace", "Hopper");

engine.Commit();

if (users.TryGet(1, out var user))
{
    Console.WriteLine($"{user.FirstName} {user.LastName}");
}

public sealed record User(string FirstName, string LastName);

Open an engine

Connect to a server (see Setup server to run one):

using var remoteEngine = CatDb.Database.CatDb.FromNetwork(
    host: "localhost", port: 7182, databaseName: "default", userName: "admin", password: "admin");

Or use one connection string for any backend — FromConnectionString picks File/Memory/Network from the string itself (see Database engine for the full key reference):

using var networked = CatDb.Database.CatDb.FromConnectionString(
    "Provider=Network;Host=localhost;Port=7182;Database=default;User Id=admin;Password=admin");

For local use (no server process), open a file, an in-memory store, or any stream directly:

using var fileEngine = CatDb.Database.CatDb.FromFile("app.catdb");
using var memoryEngine = CatDb.Database.CatDb.FromMemory();
using var streamEngine = CatDb.Database.CatDb.FromStream(stream);

// same file, via connection string
using var fileViaConnString = CatDb.Database.CatDb.FromConnectionString(
    "Provider=File;Path=app.catdb;CommitMode=TransactionLog");

FromFile uses CommitMode.WriteAheadLog by default. It creates a main database file and a .wal file next to it.

Open a table

var table = engine.OpenXTable<long, string>("events");

table[100] = "created";
table.Replace(101, "updated");
table.InsertOrIgnore(101, "ignored because key exists");
table.Delete(100);

engine.Commit();

Tables are ordered by key, so scans return stable key order:

foreach (var row in table.Forward())
{
    Console.WriteLine($"{row.Key}: {row.Value}");
}

foreach (var row in table.Backward())
{
    Console.WriteLine($"{row.Key}: {row.Value}");
}

Use range queries

using CatDb.Extensions;

var rows = table.Query().Between(100, 200).ToList();

var firstPage = table.Query().AtLeast(100).Take(50).ToList();
var nextPage = table.Query().AtLeast(100)
    .After(firstPage.Last().Key)
    .Take(50)
    .ToList();

For string keys, prefix search is index-backed:

var names = engine.OpenXTable<string, long>("name-to-id");
var matches = names.Query().StartsWith("ada");

Build and run examples from source

cd src
dotnet build --no-incremental
dotnet test --no-build
dotnet run --project CatDb.GettingStarted

The Getting Started project contains runnable demos for basic insert/read, KeyQuery, range-count performance, and keyset paging.