One line of code. A lot happening underneath.

You write this. It looks harmless:

db.Insert("Users", row);

Under the hood, it's anything but boring. Picture a database engine as a busy hospital ER. Your row is a new patient. It has to pass through triage, get logged in the official intake book before anyone touches anything permanent, and only then get filed into the ward roster. If the power flickers mid-admission, the intake book tells us exactly who was officially checked in.

The 5 layers, at a glance

A database isn't one thing. It's a stack of specialized layers, each solving one narrow problem. Meet the cast:

Meet the public API

This is the entire conversation you have with the database from your application code. Everything else in this course is what happens behind these lines.

using var db = new Database("mydata.mde", cacheSize: 100, useMemoryMappedFile: false);

var columns = new List<ColumnDefinition>
{
    new ColumnDefinition("Id", DataType.Int, false),
    new ColumnDefinition("Name", DataType.String),
    new ColumnDefinition("Age", DataType.Int)
};

var table = db.CreateTable("Users", columns, primaryKeyColumn: "Id");

var row = new DataRow(table.Schema);
row["Id"] = 1;
row["Name"] = "Alice";
row["Age"] = 30;

db.Insert("Users", row);

Notice there are really only four verbs you need to know at this level: open a database, define columns, make a row, insert it. Everything else this course teaches is what the database does for you behind those four verbs.

The journey of one row

Click Next Step to watch your row travel through the layers. Each stop has exactly one job.

Prefer to read it at your own pace? Here are the same seven steps as cards:

Zooming in: the real Table.Insert code

Here's the actual C# method that orchestrates steps 3 through 6. This is roughly 20 lines of C# from MiniDatabaseEngine/Table.cs. Don't be intimidated — we'll translate each line.

public void Insert(DataRow row, Transaction.Transaction? transaction = null)
{
    _lock.EnterWriteLock();
    try
    {
        var key = GetPrimaryKey(row);
        ValidateRowForWrite(row);

        var keyExists = _index.Search(key) != null;
        var keyPendingInTransaction = transaction?.HasBufferedValueForKey(_schema.TableName, key, GetPrimaryKeyDataType()) ?? false;
        if (keyExists || keyPendingInTransaction)
            throw new InvalidOperationException($"Duplicate primary key value '{key}'.");

        var serialized = SerializeRow(row);

        if (transaction != null)
        {
            transaction.LogInsert(_schema.TableName, key, serialized);
            _nextRowId++;
            return;
        }

        _index.Insert(key, serialized);
        _nextRowId++;
    }
    finally
    {
        _lock.ExitWriteLock();
    }
}

Notice how many layers this one method coordinates: lock manager, schema validator, index, serializer, transaction buffer. That orchestration is the whole reason this course exists.

Test your intuition

No memorization. Each question is a real scenario you might hit when debugging or talking to an AI about a database. Think it through, then pick.

Up next: Module 2 — Pages & Extents, the storage floor plan. We'll zoom all the way down to the bottom of the stack and see how the database physically lays out bytes on disk. Once you know the floor plan, the rest of the building makes sense.

Disks don't care about rows

Imagine a giant self-storage warehouse. Every single unit is exactly the same size. That's how a disk sees your database — not as tables and rows, but as a long row of identical storage units called pages.

The storage engine's whole job is translation: take your messy, variable-sized rows and cram them into these rigid, fixed-size units so the disk can move them around efficiently.

Anatomy of a page

A page is absurdly simple: an ID, a fixed-size array of raw bytes, and a flag. That's it. The ID is what makes the math work — it tells the engine exactly where on disk this unit lives.

public class Page
{
#if DATA_PAGE_SIZE
    public const int PageSize = #DATA_PAGE_SIZE#; 
#else
    public const int PageSize = 4096; // 4KB pages
#endif
    public int PageId { get; set; }
    public byte[] Data { get; set; }
    public bool IsDirty { get; set; }
    
    public Page(int pageId)
    {
        PageId = pageId;
        Data = new byte[PageSize];
        IsDirty = false;
    }

Because every page is the same size, finding page number N on disk is a single multiplication — no searching, no index lookup, just arithmetic.

Extents — bundling the moving truck

The warehouse moving truck is expensive to dispatch. Running 8 separate trips for 8 adjacent units is wasteful — so we send it once and have it pick up the whole block at a time. That block is called an extent.

8 pages sitting next to each other. One trip. That's the whole idea.

public class Extent
{
    public const int PagesPerExtent = 8;
    
    public int ExtentId { get; set; }
    public Page[] Pages { get; set; }
    public bool IsDirty => Pages.Any(p => p.IsDirty);
    
    public Extent(int extentId)
    {
        ExtentId = extentId;
        Pages = new Page[PagesPerExtent];
        
        for (int i = 0; i < PagesPerExtent; i++)
        {
            int pageId = extentId * PagesPerExtent + i;
            Pages[i] = new Page(pageId);
        }
    }

Try it yourself: which extent?

Remember the formula: extentId = pageId ÷ 8. Drag each page to the extent it belongs in. The math is the whole game.

The front-desk clipboard — LRU cache

Walking to the warehouse for every lookup is exhausting. So the front desk keeps a clipboard of the units opened most recently — that's the cache. When it runs out of space, it evicts whoever was touched the longest time ago. That rule has a name: LRU (Least Recently Used).

public void Put(int pageId, Page page)
{
    lock (_lockObject)
    {
        if (_cache.TryGetValue(pageId, out var node))
        {
            node.Page = page;
            MoveToHead(node);
            return;
        }

        var newNode = new CacheNode(page);
        _cache[pageId] = newNode;
        AddToHead(newNode);

        if (_cache.Count > _capacity)
        {
            var removed = RemoveTail();
            if (removed != null)
                _cache.TryRemove(removed.Page.PageId, out _);
        }
    }
}

The "top" and "bottom" of the clipboard are tracked by a doubly-linked list, which is why moving something to the top is almost free. An even fancier variant — a memory-mapped file — lets the OS handle caching for you, but that's a topic for another day.

Put it to work

Three questions to stretch the ideas. No trick questions — just situations you might hit in real conversations with an AI coding assistant.

Next up: module 3, The B+ Tree. Now that bytes have a place to live, how do we find one specific row among millions?

The phone book with index tabs

Scanning 10 million rows to find user #47,392,185 would take forever. A B+ tree turns that search into about 23 comparisons — like binary-searching a physical phone book, one flip at a time.

Picture a phone book with thick index tabs glued to the edge of the pages. The tabs don't contain phone numbers — they just say "flip here for S" or "flip here for T." The actual phone numbers live on the alphabetized pages at the end, and those pages are stapled in order — once you land on "Smith" you can just keep reading forward to "Thompson, Turner, Vance."

That's a B+ tree. The tabs are internal nodes. The pages are leaf nodes. And the staples are what make range queries fast.

Two kinds of nodes, two different jobs

Every node holds keys. But leaf nodes also hold the actual values and have Next/Previous pointers to their siblings. Internal nodes hold only keys and pointers to children — they're pure signposts.

public abstract class BPlusTreeNode
{
    public bool IsLeaf { get; protected set; }
    public BPlusTreeNode? Parent { get; set; }
    public List<object> Keys { get; protected set; }
    
    protected BPlusTreeNode(bool isLeaf)
    {
        IsLeaf = isLeaf;
        Keys = new List<object>();
    }
    
    public abstract int KeyCount { get; }
}

public class BPlusTreeInternalNode : BPlusTreeNode
{
    public List<BPlusTreeNode> Children { get; private set; }
    
    public BPlusTreeInternalNode() : base(false)
    {
        Children = new List<BPlusTreeNode>();
    }
    
    public override int KeyCount => Keys.Count;
}

public class BPlusTreeLeafNode : BPlusTreeNode
{
    public List<object?> Values { get; private set; }
    public BPlusTreeLeafNode? Next { get; set; }
    public BPlusTreeLeafNode? Previous { get; set; }
    
    public BPlusTreeLeafNode() : base(true)
    {
        Values = new List<object?>();
    }
    
    public override int KeyCount => Keys.Count;
}

Two operations that justify the whole design

A B+ tree earns its keep with two moves: jump straight to one key (Search) or collect every key in a span (Range). Same tree. Very different mechanics.

Search: climb down the tabs to the right page

public object? Search(object key)
{
    lock (_lockObject)
    {
        var leaf = FindLeafNode(key);
        int index = FindKeyIndex(leaf.Keys, key);
        
        if (index < leaf.Keys.Count && _comparer.Compare(leaf.Keys[index], key) == 0)
        {
            return ((BPlusTreeLeafNode)leaf).Values[index];
        }
        
        return null;
    }
}

Range: find the start, then walk sideways

public IEnumerable<KeyValuePair<object, object?>> Range(object? minKey, object? maxKey)
{
    lock (_lockObject)
    {
        var results = new List<KeyValuePair<object, object?>>();
        var leaf = minKey != null ? FindLeafNode(minKey) : GetFirstLeaf();
        
        while (leaf != null)
        {
            for (int i = 0; i < leaf.Keys.Count; i++)
            {
                var key = leaf.Keys[i];
                
                if (minKey != null && _comparer.Compare(key, minKey) < 0)
                    continue;
                    
                if (maxKey != null && _comparer.Compare(key, maxKey) > 0)
                    return results;
                    
                results.Add(new KeyValuePair<object, object?>(key, leaf.Values[i]));
            }
            
            leaf = leaf.Next;
        }
        
        return results;
    }
}

The three operations, at a glance

Every query the database ever runs against an index comes down to one of these three moves.

Build the tree: inserting 10, 20, 30, 40

Let's watch a tree grow from scratch, with order = 3 (so a leaf can hold 2 keys before it has to split). Four inserts, four snapshots.

Here's the insert code that orchestrates all that. It's surprisingly short — the recursion lives inside SplitLeafNode, which can bubble splits all the way up to the root.

public void Insert(object key, object? value)
{
    lock (_lockObject)
    {
        var leaf = FindLeafNode(key);
        InsertIntoLeaf(leaf, key, value);
        
        if (leaf.KeyCount > _order - 1)
        {
            SplitLeafNode(leaf);
        }
    }
}

Quick check — apply what you've seen

Four short scenarios. There's no score — the point is to stretch the ideas, not memorize them.

Coming up next: now that you know the tree exists, Module 4 shows how the LINQ query planner decides when to use it — and when it's cheaper to just read every row.

The GPS route planner inside your database

Ask your phone for directions to the airport. It doesn't try every street — it peeks at your request, notices "highway only," and picks an efficient route. Your database does the same thing with a query.

You write LINQ like .Where(r => r["Id"] == 42). Before a single row is touched, a planner inspects your request and picks a strategy. That strategy is the query plan, and it decides whether your query runs in milliseconds or minutes.

The three phases of Execute

When you call .ToList() on a LINQ query, the engine runs the Execute method. Think of it as the GPS running three steps: pick a door, filter what comes through, and sort what's left.

public TResult Execute<TResult>(Expression expression)
{
    var plan = BuildExecutionPlan(expression);
    IEnumerable<DataRow> rows = ExecuteAccessPath(plan);

    foreach (var predicate in plan.Predicates)
    {
        rows = rows.Where(predicate);
    }

    if (plan.OrderByColumn != null)
    {
        if (plan.IsOrderByDescending)
            rows = rows.OrderByDescending(r => r[plan.OrderByColumn]);
        else
            rows = rows.OrderBy(r => r[plan.OrderByColumn]);
    }

    return (TResult)(object)rows;
}

Notice the order: access path first, filters second, sort last. Sorting always happens in memory over whatever survived the filters. That's why ORDER BY never speeds up a query — it can only slow it down.

Picking the door: ExecuteAccessPath

This is the heart of the planner. A short predicate-sniffing ladder decides whether your query jumps, walks, or scans.

private IEnumerable<DataRow> ExecuteAccessPath(QueryExecutionPlan plan)
{
    if (!string.IsNullOrEmpty(_primaryKeyColumn) && plan.IndexRange != null)
    {
        if (plan.IndexRange.ExactKey != null)
        {
            var single = _table.SelectByKey(plan.IndexRange.ExactKey);
            return single != null ? new List<DataRow> { single } : new List<DataRow>();
        }

        if (plan.IndexRange.HasLowerBound || plan.IndexRange.HasUpperBound)
        {
            return _table.SelectByPrimaryKeyRange(plan.IndexRange.LowerBound, plan.IndexRange.UpperBound);
        }
    }

    return _table.SelectAll();
}

Read it top-down: exact key? one jump. range? leaf-walk. neither? full scan. That's the whole planner — three lines of real decision-making sitting on top of a B+ tree.

Where the plan meets the tree

When the plan picks "exact key," control lands on SelectByKey — the point where the LINQ layer finally calls into the B+ tree you built in Module 3.

public DataRow? SelectByKey(object key)
{
    _lock.EnterReadLock();
    try
    {
        var serialized = _index.Search(key);
        if (serialized == null)
            return null;
        
        return DeserializeRow((byte[])serialized);
    }
    finally
    {
        _lock.ExitReadLock();
    }
}

Three views of the same query

Watch how what you wrote becomes a plan object becomes a method call on Table. Click each tab:

// What you, the developer, wrote:
var user = db.Query("Users")
    .Where(r => (int)r["Id"] == 42)
    .ToList();

// What BuildExecutionPlan produced:
QueryExecutionPlan {
    Predicates: [],                    // empty — no leftover filter
    IndexRange: {
        ExactKey: 42,                 // index can do this exactly
        HasLowerBound: false,
        HasUpperBound: false
    },
    OrderByColumn: null,
    IsOrderByDescending: false
}

// What actually ran on the Table:
_table.SelectByKey(42);
  ↳ _index.Search(42);         // B+ tree descent: O(log n)
  ↳ DeserializeRow(bytes);     // bytes → DataRow
  ↳ return single row.

// No predicate loop. No sort. Done.

This three-step journey — intent → plan → operation — is exactly why SQL and LINQ feel magical. The visitor pattern turns your lambda into a data structure, and that data structure picks the physical operation.

Spot the bug: the query that won't use the index

Here's a query that looks like it should be O(log n). But the developer made one small mistake, and now it full-scans 10 million rows every time. Can you spot it?

The planner only recognizes patterns shaped like r["Id"] == constant. The moment you wrap the column in a function call — .ToString(), Math.Abs(), Substring() — the visitor's pattern-match fails and the query falls back to a full scan. This is the same footgun as writing WHERE TO_CHAR(id) = '42' in SQL. Keep the column naked on one side of the comparison.

Check your route-planning instincts

Four scenarios. No memorization — just apply what you've seen.

Next up: reads were easy — they just have to be fast. Writes are harder. They have to survive crashes, power cuts, and half-finished transactions. Module 5 opens the durability hood.

The airline check-in desk

You hand the agent two tickets and a suitcase. Before anything gets stamped on your boarding passes, the agent writes every item into a thick official logbook, in order: "party of two, bag tagged, seats assigned." Then they print the passes. If the power cuts mid-check-in, the next agent in the morning reads the logbook and finishes only the check-ins marked "complete." Anything without a complete stamp is thrown out.

That is how airlines avoid losing your luggage — and it is exactly how databases avoid losing your money. In this module we meet the logbook: the WAL, and the rules that make a transaction either fully happen or fully vanish.

Imagine a bank transfer. You debit account A, then credit account B. What if the lights go out between those two steps? Without a transaction guarantee, account A is poorer and account B is no richer. Money just evaporates. The rules below exist so that never happens.

Together these four letters spell ACID — the checklist every serious database must pass.

Log first, apply after

Here is the one rule that powers everything in this module. When a transaction wants to change data, the database does not touch the real data first. It writes the intended change into the WAL on disk, forces that log to be durable, and only then applies the change. Log first, apply after.

Flip that order and you get corruption. Apply first and hope to log later? If the crash lands between those two steps, the change is on disk but the log does not know, so recovery will never replay or undo it. The whole system is built to avoid that gap.

Watch a real transaction trickle through the engine. Four characters: User (the client), Transaction (the bookkeeper), WAL (the logbook on disk), and BPlusTree (where the rows actually live).

Inside a logbook entry

Every row in the logbook is a WALEntry. One entry per operation: "transaction 42 inserted Alice," "transaction 42 committed," and so on. The fields are chosen so recovery has everything it needs — the old value to undo, the new value to redo, and a sequence number so we know the exact order things happened.

public class WALEntry
{
    private const int MaxCheckpointActiveTransactionCount = 100_000;
    private const int MaxStringByteLength = 64 * 1024;
    private const int MaxValueLength = 1024 * 1024;

    public long TransactionId { get; set; }
    public WALOperationType OperationType { get; set; }
    public string TableName { get; set; } = string.Empty;
    public object? Key { get; set; }
    public byte[]? OldValue { get; set; }
    public byte[]? NewValue { get; set; }
    public long Timestamp { get; set; }
    public long SequenceNumber { get; set; }
    public List<long> CheckpointActiveTransactionIds { get; set; } = new();
    public long CheckpointNextTransactionId { get; set; }
}

The moment of commit

A commit is not a switch. It is a three-step dance: write the commit marker, flush the WAL to disk, then apply. The line between "might lose this" and "definitely safe" is a single call to Flush().

public void Commit()
{
    _lock.EnterWriteLock();
    try
    {
        if (_state != TransactionState.Active)
            throw new InvalidOperationException($"Cannot commit transaction in state: {_state}");

        // Log the commit
        _walManager.AppendEntry(new WALEntry
        {
            TransactionId = _transactionId,
            OperationType = WALOperationType.Commit
        });

        // Force flush to ensure durability
        _walManager.Flush();

        // Apply buffered writes only after WAL commit is durable.
        _commitApplyCallback(_entries);

        _state = TransactionState.Committed;
        _transactionManager.CompleteTransaction(_transactionId);
    }
    finally
    {
        _lock.ExitWriteLock();
    }
}

Say it once more: log first, apply after.

Morning after the crash

A crash happens. Half-written transactions, maybe a commit marker that made it to disk, maybe one that didn't. The next time the engine boots, it runs RecoverFromWAL: read the whole logbook, bucket entries by transaction, replay only the buckets with a Commit marker, throw the rest away.

Here is the recovery code, stripped of its error handling. Notice how simple the rule is: if there is a Commit entry, replay; otherwise, ignore.

public void RecoverFromWAL(Action<WALEntry> applyEntry)
{
    _lock.EnterWriteLock();
    try
    {
        var entries = _walManager.ReadEntriesForRecovery();
        var transactions = new Dictionary<long, List<WALEntry>>();
        var committedTransactions = new HashSet<long>();

        foreach (var entry in entries)
        {
            if (entry.OperationType == WALOperationType.Checkpoint) continue;

            if (entry.OperationType == WALOperationType.Commit)
                committedTransactions.Add(entry.TransactionId);
            else if (entry.OperationType == WALOperationType.Rollback)
                continue;
            else if (entry.OperationType != WALOperationType.BeginTransaction)
            {
                if (!transactions.ContainsKey(entry.TransactionId))
                    transactions[entry.TransactionId] = new List<WALEntry>();
                transactions[entry.TransactionId].Add(entry);
            }
        }

        foreach (var txnId in committedTransactions)
        {
            if (transactions.TryGetValue(txnId, out var txnEntries))
            {
                foreach (var entry in txnEntries)
                    applyEntry(entry);
            }
        }
    }
    finally { _lock.ExitWriteLock(); }
}

The mantra again: log first, apply after. Recovery only trusts what was logged.

Keeping the logbook lean

If the WAL grew forever, recovery would take forever too. So the engine periodically takes a checkpoint: flush all dirty in-memory pages to disk, write a special Checkpoint WAL entry, and truncate the oldest part of the log. The logbook starts fresh from a known-good moment.

Checkpoints, deferred writes, and the commit dance all rest on the same foundation: log first, apply after.

Think it through

Four scenarios. Pick the answer a seasoned database engineer would give. The explanations are where the real learning happens — read them even when you are right.

Next module: Concurrency. Multiple transactions at once — how does the engine keep them from stepping on each other?

The Subway Revolving Door

Picture a revolving door at a subway station. Many people can walk through at the same time, as long as they are all going the same direction. But if one person stops in the middle to tie their shoelaces, everyone else must wait until they are done.

That is exactly how a database handles concurrency. Many readers can flow through together. A single writer gets the door to themselves. The trick is making sure no one ever crashes into anyone else.

The door has three states

A reader-writer lock keeps track of which state the door is in right now.

Readers and a writer can never coexist. Only the IDLE state connects them.

Five Doors, Stacked

A real database does not have one door. It has five, nested like Russian dolls. Each door guards a different part of the system, from the whole database down to a tiny cache page.

When an operation needs to pass through more than one door, it must always pick them up in the same order. That single rule prevents an entire class of bugs called deadlock.

The rule is simple to say and life-saving to follow: always acquire locks in order from level 1 down to level 5. Never the other way. That contract is written directly into the source code as a comment.

/// <summary>
/// Thread Safety:
/// This class uses ReaderWriterLockSlim to ensure thread-safe operations.
/// Multiple threads can read concurrently, but write operations are exclusive.
/// 
/// Lock Ordering (to prevent deadlocks when nested locking occurs):
/// When multiple locks need to be acquired, always acquire them in this order:
/// 1. Database._lock (schema-level operations)
/// 2. Table._lock (table-level operations)
/// 3. BPlusTree._lockObject (index operations)
/// 4. StorageEngine._lock (this class - storage operations)
/// 5. PageCache/ExtentCache locks (cache operations)
/// </summary>
public class StorageEngine : IDisposable
{
    private readonly ReaderWriterLockSlim _lock;

Reading vs Writing: One Word Changes Everything

In the code, the only difference between a read operation and a write operation is a single word. But that word completely changes how the door behaves.

Notice how both examples wrap their work in try/finally. The lock must be released even if the work explodes halfway through. Forgetting that single line is how a database freezes forever.

public void Insert(DataRow row, Transaction.Transaction? transaction = null)
{
    _lock.EnterWriteLock();
    try
    {
        var key = GetPrimaryKey(row);
        ValidateRowForWrite(row);

        var keyExists = _index.Search(key) != null;
        var keyPendingInTransaction = transaction?.HasBufferedValueForKey(_schema.TableName, key, GetPrimaryKeyDataType()) ?? false;
        if (keyExists || keyPendingInTransaction)
            throw new InvalidOperationException($"Duplicate primary key value '{key}'.");

        var serialized = SerializeRow(row);

        if (transaction != null)
        {
            transaction.LogInsert(_schema.TableName, key, serialized);
            _nextRowId++;
            return;
        }

        _index.Insert(key, serialized);
        _nextRowId++;
    }
    finally
    {
        _lock.ExitWriteLock();
    }
}

public DataRow? SelectByKey(object key)
{
    _lock.EnterReadLock();
    try
    {
        var serialized = _index.Search(key);
        if (serialized == null)
            return null;
        
        return DeserializeRow((byte[])serialized);
    }
    finally
    {
        _lock.ExitReadLock();
    }
}

EnterWriteLock means "I need the door all to myself." EnterReadLock means "I will share." Picking the wrong one is either a correctness bug or a performance disaster.

When the Door Jams: A Deadlock Almost Happens

Here is what happens when two threads forget the ordering rule. Thread A picks up Lock A, Thread B picks up Lock B, then each wants the other. Now nobody can move. This is the race condition that every concurrent system has to defend against.

Spot the Bug

Here is a method that grabs two of the five locks from our stack. It looks innocent. It even has a try/finally. But somewhere in here, the ordering rule is broken. If another thread is doing the usual 1 → 5 walk, the two can wedge against each other.

Click the line you think is wrong.

This exact shape of bug is how real production systems hang at 3 a.m. Knowing the lock order of your system is like knowing the emergency exits — rare to need, priceless when you do.

Check Your Understanding

Four scenarios. No memorization — just use what you now know about doors, readers, writers, and lock ordering.

Next up — Module 7: Observability. Now that you know how it works, how do you see it working at runtime?

Flying blind is not a strategy

Your database has been running for three days. Was everything fine? Did commits happen? How many? How many rolled back? If you cannot answer those questions in under five seconds, your system is not observable.

A pilot cannot open the hood of a 747 at 35,000 feet. They rely on the cockpit instrument panel — gauges, warning lights, and the voice recorder. A running database is the same. You cannot freeze it mid-transaction to peek inside. You need instruments that report outward while it flies.

One sentence. Two realities.

Here is the same event — a row being inserted — logged two different ways. Both “work.” Only one of them is usable after the fact.

Console.WriteLine("insert done");

{"timestamp":"2026-04-22T10:12:03Z",
 "level":"Information",
 "event":"row.inserted",
 "table":"Users",
 "txn":42}

The black box recorder

Every log line in the engine is a DatabaseLogEntry — a small, strongly-typed object that knows how to turn itself into JSON. Think of it as one page torn from the flight recorder.

public sealed class DatabaseLogEntry
{
    public DateTimeOffset Timestamp { get; init; } = DateTimeOffset.UtcNow;
    public DatabaseLogLevel Level { get; init; }
    public string EventName { get; init; } = string.Empty;
    public string Message { get; init; } = string.Empty;
    public IReadOnlyDictionary<string, object?> Properties { get; init; } = new Dictionary<string, object?>();

    public string ToJson()
    {
        var payload = new Dictionary<string, object?>(StringComparer.Ordinal)
        {
            ["timestamp"] = Timestamp.ToString("O"),
            ["level"] = Level.ToString(),
            ["event"] = EventName,
            ["message"] = Message
        };

        foreach (var pair in Properties)
        {
            payload[pair.Key] = pair.Value;
        }

        return JsonSerializer.Serialize(payload);
    }
}

The dashboard gauges

Logs tell the story. Metrics count the story. Every major event the engine performs bumps a counter by one. Here is the whole metrics gauge cluster in 30 lines.

internal sealed class DatabaseMetrics
{
    private long _tablesCreated;
    private long _transactionsStarted;
    private long _inserts;
    private long _updates;
    private long _deletes;
    private long _flushes;
    private long _checkpoints;
    private long _backupsCreated;
    private long _integrityChecks;

    public void IncrementTablesCreated() => Interlocked.Increment(ref _tablesCreated);
    public void IncrementTransactionsStarted() => Interlocked.Increment(ref _transactionsStarted);
    public void IncrementInserts() => Interlocked.Increment(ref _inserts);
    public void IncrementUpdates() => Interlocked.Increment(ref _updates);
    public void IncrementDeletes() => Interlocked.Increment(ref _deletes);
    public void IncrementFlushes() => Interlocked.Increment(ref _flushes);
    public void IncrementCheckpoints() => Interlocked.Increment(ref _checkpoints);
    public void IncrementBackupsCreated() => Interlocked.Increment(ref _backupsCreated);
    public void IncrementIntegrityChecks() => Interlocked.Increment(ref _integrityChecks);

    public DatabaseMetricsSnapshot Snapshot()
    {
        return new DatabaseMetricsSnapshot
        {
            TablesCreated = Interlocked.Read(ref _tablesCreated),
            TransactionsStarted = Interlocked.Read(ref _transactionsStarted),
            Inserts = Interlocked.Read(ref _inserts),
            Updates = Interlocked.Read(ref _updates),
            Deletes = Interlocked.Read(ref _deletes),
            Flushes = Interlocked.Read(ref _flushes),
            Checkpoints = Interlocked.Read(ref _checkpoints),
            BackupsCreated = Interlocked.Read(ref _backupsCreated),
            IntegrityChecks = Interlocked.Read(ref _integrityChecks)
        };
    }
}

The gauge cluster

Nine counters. Each one answers a different question about what the engine has been doing.

The event vocabulary

Alongside the counters, the engine emits named events — the stable keys you filter on in a log aggregator. These seven cover the whole life of a database.

Three lines and you can see inside

Here is the consumer side. Nothing fancy — register a logger, flip a flag, read a snapshot.

using var db = new Database(
    "mydata.mde",
    options: new DatabaseOptions
    {
        Logger = new JsonConsoleDatabaseLogger(),
        EnableMetrics = true
    });

var metrics = db.GetMetricsSnapshot();
Console.WriteLine($"Inserts: {metrics.Inserts}, Checkpoints: {metrics.Checkpoints}");

One insert, traced through the instrument panel

Follow a single insert from user code out through the two telemetry pipelines — counter and log — and back out as a readable snapshot.

Does it click?

Four scenarios. Answer from the cockpit, not from memory.