EvaluatedApplications.HoloDb.Client 1.5.0

HoloDb.Client

The .NET client for a remote HoloDb server. It mirrors the in-process HoloDbService surface, so moving from embedded to networked changes only how you get the handle — the query API and the returned QueryResult are identical. Columnar results stay columnar over the wire (typed column arrays, not JSON).

Usage

using HoloDb.Client;

await using var db = await HoloDbClient.ConnectAsync("your-host", 5432, new HoloDbClientOptions
{
    AuthToken        = "s3cret",           // the server's --token
    PinnedThumbprint = "ABCD...",          // pin the server's TLS cert (printed by the server on start)
});

await db.ExecuteAsync("CREATE TABLE users (id INT PRIMARY KEY, age INT, name TEXT)");
await db.ExecuteAsync("INSERT INTO users VALUES (1, 30, 'Ada')");

var r = await db.ExecuteAsync("SELECT name FROM users WHERE age >= 18");
for (var i = 0; i < r.RowCount; i++) Console.WriteLine(r.GetText(i, 0));   // typed, no boxing

// column-native bulk load (no SQL parsing on either side)
await db.BulkLoadAsync("users", new[] { "id", "age", "name" },
    new Array[] { new long[] { 2, 3 }, new long[] { 25, 41 }, new[] { "Ben", "Cara" } }, count: 2);

One connection is one session: transactions (BEGIN / COMMIT / ROLLBACK sent as SQL) are scoped to it and requests are serialised, so use one client per concurrent worker. GetStatsAsync() returns server counters (uptime, connections, queries, commits, transaction aborts, WAL size).

Need a bounded connect timeout, a fixed set of workers, or reconnect-on-drop? These are opt-in, additive:

// bounded connect/handshake (throws TimeoutException, not OperationCanceledException, on timeout)
await using var db = await HoloDbClient.ConnectAsync("your-host", 5432, TimeSpan.FromSeconds(5));

// one connected client per worker, rented out exclusively
await using var pool = await HoloDbClientPool.ConnectAsync("your-host", 5432, size: 8, options);
using (var lease = await pool.RentAsync())
    await lease.Client.ExecuteAsync("SELECT 1");

// reconnect-and-retry on transient transport failures (not on app-level SQL/auth errors)
await using var resilient = await ResilientHoloDbClient.ConnectAsync("your-host", 5432, options);
await resilient.ExecuteAsync("SELECT 1");

// bound the WHOLE call (every attempt/reconnect/backoff sleep, and any circuit-breaker wait) - opt-in,
// throws TimeoutException if the budget runs out before the call finishes
await resilient.ExecuteAsync("SELECT 1", operationTimeout: TimeSpan.FromSeconds(10));

The server is EvaluatedApplications.HoloDb.Server (run it directly or via the Docker image). For a dev server that mints a self-signed certificate, either pin the thumbprint it prints on startup or set AllowUntrustedCertificate = true (dev only).

Key notes — sizing the pool

HoloDbClientPool connects N clients up front and rents them out exclusively — one client per concurrent worker, with no multiplexing or concurrency inside a single connection. This is fundamentally different from connection pools (HikariCP, Redis, pgBouncer) that share a small pool across many logical requests.

Do not use the HikariCP formula (pool size = cores × 2 + effective spindles). That formula works when many callers compete for a shared resource (a database thread/connection). Here, each client is a single-session, request-serialized connection — no multiplexing, no contention. Instead:

• Size to expected concurrent workers: if you have 8 worker threads/tasks making queries in parallel, size the pool to 8.
• Check the server's connection limit (HoloDb defaults to 100 open connections): size your pool well below that ceiling.
• Start small and measure: 4–16 is typical for most applications. If your workers stall waiting for a lease, increase; if you have idle pool slots, decrease.

One undersized pool means workers queue for leases and latency climbs; one oversized pool wastes memory and connection file descriptors with no throughput gain (because a query still serializes through each client's internal mutex).

License

Proprietary — this package ships the compiled library only. Every capability is free to use. See LICENSE. Copyright (c) 2026 Dongyang Stephen Chen, trading as Evaluated Applications. All rights reserved.