CosmoNova 1.0.8

CosmoNova

A T-SQL-compatible database engine for .NET 10, packaged as a single embeddable assembly. Born from merging two existing libraries into one tightly-coupled unit:

• The LSM-tree storage engine previously published as CosmoKv (MVCC snapshot-isolation transactions, WAL durability, value-log indirection, background compaction). C# port of Dgraph's Badger v4.
• The T-SQL query engine previously housed inside CosmoSQLClient.CosmoKv (lexer, parser, planner, executor, schema catalog) — a substantial subset of T-SQL 2025 syntax compatible with what SQL Server accepts.

Putting them in one assembly is intentional: the executor has free access to storage internals (cursor reuse, index-aware planning, in-place row materialization), which is the source of the 32–60× perf advantage over SQL Server 2025 measured in the cross-engine benchmarks below.

Two API surfaces, one assembly

Most application code reaches CosmoNova through the CosmoKvConnection facade in CosmoSQLClient.CosmoKv v6.0+, which implements the standard ISqlDatabase interface used across the CosmoSQLClient driver family. Direct use of CosmoNova.Sql.* types is intended for daemons and tooling that host the engine themselves.

Quick start — storage API

using CosmoKv;

await using var db = await Db.OpenAsync(DbOptions.Default("/tmp/mydb"));

await db.SetAsync("hello"u8.ToArray(), "world"u8.ToArray());
byte[]? v = await db.GetAsync("hello"u8.ToArray());

await using (var txn = db.BeginTransaction(update: true))
{
    txn.Set("a"u8.ToArray(), "1"u8.ToArray());
    txn.Set("b"u8.ToArray(), "2"u8.ToArray());
    await txn.CommitAsync();
}

await foreach (var item in db.IterateAsync(IteratorOptions.WithPrefix("user:"u8.ToArray())))
{
    byte[] value = await item.ReadValueAsync();
}

Quick start — SQL API (via the CosmoSQLClient.CosmoKv facade)

using CosmoSQLClient.CosmoKv;
using CosmoSQLClient.Core;

await using var conn = await CosmoKvConnection.OpenAsync(
    new CosmoKvConfiguration { DataSource = "/tmp/mydb" });

await conn.ExecuteAsync(@"
    CREATE TABLE users (
        id   BIGINT IDENTITY PRIMARY KEY,
        name VARCHAR(64) NOT NULL,
        born DATETIME
    );");

await conn.ExecuteAsync(
    "INSERT INTO users (name, born) VALUES (@n, @b);",
    new List<SqlParameter> {
        SqlParameter.Named("@n", SqlValue.From("Ada")),
        SqlParameter.Named("@b", SqlValue.From(new DateTime(1815, 12, 10))),
    });

var rows = await conn.QueryAsync(
    "SELECT id, name FROM users WHERE born < @cutoff ORDER BY born;",
    new List<SqlParameter> { SqlParameter.Named("@cutoff", SqlValue.From(new DateTime(1900, 1, 1))) });

foreach (var row in rows)
    Console.WriteLine($"{row[0]} {row[1]}");

Direct engine use (no facade) is also possible via the CosmoNova.Sql.EngineMetrics, Parsing.TSqlParser, and Execution.Executor types — but those APIs require careful lifecycle management; the facade exists so you don't have to.

Performance

Storage layer (vs Badger v4 / RocksDB-style baselines)

Numbers from bench/CosmoKv.Benchmarks/ on Apple M1, APFS, SyncWrites=false, 1 warmup + 3 measurement iterations.

SQL layer (vs SQL Server 2025 — same T-SQL on both)

Numbers from Benchmarks/CosmoSQLBenchmarks/CosmoKvVsMsSqlBenchmarks.cs on Apple M1, .NET 10, against SQL Server 2025. CosmoNova runs embedded; SQL Server runs over TDS via Microsoft.Data.SqlClient.

Cross-platform validation: 293 storage + 11 CLI tests pass on macOS Apple Silicon (APFS) and Windows 11 ARM64 (Parallels guest, native NTFS); 1,415 SQL-engine tests pass in CosmoSQLClient.CosmoKv.Tests.

Multi-process deployment

CosmoNova's library is single-process / single-writer — opening the same data directory from two processes is not supported (file-locks + in-memory MVCC state can't span processes). For deployments where multiple processes share one database, use the CosmoKvD daemon, which owns the embedded CosmoNova instance and exposes it over Unix pipes + HTTP.

Process A ─┐
Process B ─┤
Process C ─┼── pipes/HTTP ──► CosmoKvD ──► CosmoNova ──► disk
Process D ─┘                  (1 proc)    (engine+storage)

This is the same pattern SQL Server (sqlservr.exe), Postgres (postmaster), and MySQL (mysqld) use. The daemon is what handles connection multiplexing, authentication, and lifecycle.

In production, the CosmoMail mailserver uses CosmoKvD to back its IMAP/SMTP/Webmail services across four containers sharing one daemon.

Project layout

src/CosmoKv/                          ← all production source ships from one .csproj
  Db.cs, DbOptions.cs, Txn.cs, …       ← storage API (CosmoKv.*)
  Backup/, Crypto/, Diagnostics/,
  Internal/, Iterators/, Levels/,
  Memory/, Mvcc/, Streaming/,
  Subscriptions/, Tables/, ValueLog/,
  Wal/                                  ← storage subsystems
  Sql/                                  ← T-SQL engine (CosmoNova.Sql.*)
    Ast/                                  parse-tree types
    Lexer/                                T-SQL tokenizer
    Parsing/  TSqlParser.cs               recursive-descent T-SQL parser
    Execution/                            executor + optimizer + EngineMetrics
    Schema/                               catalog + DDL handling
    Storage/                              engine↔KV bridge

tests/                                 ← 293 storage tests + CLI tests
bench/CosmoKv.Benchmarks/              ← storage micro-benchmarks
bench/CosmoKvDLoad/                    ← multi-process daemon load harness
                                         (talks to CosmoKvD over pipes)
tools/cosmokv/                         ← CLI tool (ships separately as CosmoKv.Cli)
docs/                                  ← getting-started, api-reference,
                                         internals, benchmarks, examples

Storage features

(carried over from CosmoKv 3.2.3; no behavior change)

• MVCC snapshot-isolation transactions. Every commit gets a monotonic timestamp; readers see a stable snapshot at their BeginTransaction call. Read-write conflicts are detected at commit time and raise ConflictException.
• WAL-backed durability. Every write goes through a write-ahead log before the in-memory memtable; SyncWrites=true fsyncs on every entry. Crash recovery is exercised by an in-process kill-fuzz test and a subprocess crash harness.
• Value log indirection. Values larger than ValueThreshold (default 1 KiB) live in .vlog files; LSM rows hold a 12-byte pointer. Reclaim space via Db.RunValueLogGcAsync.
• Background compaction. A worker scores levels and runs L0→L1→…→L_n compactions; tombstones are discarded at the bottom level. L0 backpressure stalls writers cleanly when the compactor can't keep up.
• Sharded LRU block cache (default 256 MiB, 16 shards) keyed by (fileId, blockOffset). Cached point Gets are 3× faster than uncached.
• Pluggable block compression — None, LZ4, Snappy, Zstd. Codec id is stored per block so a single database can mix compression types across its history.
• TTL enforcement. Set expiresAt on a write and the entry stops being visible after that wall-clock time. A background sweeper writes tombstones for expired user-keys.
• Lock-free memtable. Writes use CAS-link inserts on a concurrent skiplist.
• IAsyncEnumerable<Item> iteration with forward/reverse, prefix filter, and AllVersions mode.
• Change-feed subscriptions. db.Subscribe(prefix) returns an IAsyncEnumerable<ChangeEvent> of every subsequent commit whose user-key matches the prefix.
• Bulk streaming. KvStream (export) + KvStreamWriter (bulk-load) ship IAsyncEnumerable<KvList> pipelines. The writer builds L0 SSTables directly, bypassing the WAL.
• Backup / Restore. Portable, CRC64-protected COSMOBAK stream format.
• Encryption at rest. AES-256-GCM AEAD on every SST block, WAL frame, and vlog frame; master key wraps a per-DB DEK.
• OpenTelemetry instrumentation. Meter("CosmoKv") + ActivitySource("CosmoKv"). Zero overhead when no listener is attached.

SQL features

(carried over from CosmoSQLClient.CosmoKv 5.32.1; no behavior change)

• T-SQL subset compatible with SQL Server 2025. SELECT/INSERT/UPDATE/DELETE, JOIN (INNER/LEFT/RIGHT/FULL/CROSS), GROUP BY + GROUPING SETS, PIVOT/UNPIVOT, CTEs (WITH), windowed functions, IDENTITY columns, UNIQUE/PRIMARY KEY constraints, OUTPUT clauses, MERGE, scalar UDFs, stored procedures, triggers (subset), OPTION (RECOMPILE|FORCE ORDER|MAXDOP n) hints.
• Cost-based join reordering (JoinReorderPlanner) for all-INNER multi-table SELECTs without FORCE ORDER.
• Hash join for INNER / LEFT with at least one equi-conjunct in ON; nested-loop fallback otherwise.
• MAXDOP-parallelised joins for work products above the parallelism threshold.
• Parse cache (EngineMetrics.ParseCached) bounded at 256 entries; bypassed by OPTION (RECOMPILE).
• Snapshot-isolation transactions layered on the storage MVCC; BEGIN TRAN/COMMIT/ROLLBACK, savepoints, nested transactions.
• Constraint exceptions — UniqueConstraintViolationException (with IsPrimaryKey distinguishing 2627 vs 2601) and SqlTransactionConflictException for retry-safe txn aborts.
• Engine telemetry — public counters on EngineMetrics: ParseCacheHits/Misses/Size, JoinReorderInvocations/Applied, ParallelJoinSteps, HashJoinSteps.

Roadmap

CosmoNova is single-node today. The shape of the eventual horizontal-scaling story is shared-nothing sharding with per-shard Raft replication (the Vitess / CockroachDB / TiDB model), with cluster intelligence living in the daemon layer rather than the engine. None of that is implemented yet; the production path for now is one CosmoKvD per database, vertically scaled.

See docs/internals.md for engine internals and docs/benchmarks.md for the full benchmark methodology.

Production usage

• CosmoMailServer — IMAP/SMTP/Webmail backend; embedded CosmoNova via the CosmoSQLClient.CosmoKv facade, accessed by 4 service containers through one CosmoKvD daemon.
• CosmoS3 — S3-compatible object store; CosmoNova as one of several pluggable backends.

License

Apache 2.0. See LICENSE.