Overview

WitDatabase is a feature-rich embedded database engine that provides enterprise-level capabilities in a lightweight, zero-dependency package. This section provides an overview of all major features and links to detailed documentation for each.

Architecture at a Glance

WitDatabase is built as a layered system where each layer can be configured or replaced:

[[Svg Src="./witdatabase-architecture-layers.svg" Alt=" Application Layer"]]

Feature Categories

Storage Engines

WitDatabase offers three storage engines optimized for different workloads:

// B+Tree (default, recommended for most applications)
.WithBTree()

// LSM-Tree (for write-heavy workloads)
.WithLsmTree()

// In-Memory (for testing)
.WithMemoryStorage()

→ Detailed documentation: Storage Engines

Transactions & ACID

Full ACID compliance with enterprise-grade transaction support:

Transaction Features:

• BEGIN / COMMIT / ROLLBACK
• Savepoints for partial rollback
• Nested transactions pattern
• Auto-commit mode

using var transaction = connection.BeginTransaction();
try
{
    // Multiple operations...
    transaction.Commit();
}
catch
{
    transaction.Rollback();
    throw;
}

→ Detailed documentation: Transactions & Concurrency

Isolation Levels

Five isolation levels to balance consistency and performance:

// Via connection string
"Data Source=app.witdb;Isolation Level=Snapshot"

// Via ADO.NET
using var tx = connection.BeginTransaction(IsolationLevel.Serializable);

// Via builder
.WithDefaultIsolationLevel(IsolationLevel.Snapshot)

→ Detailed documentation: Transactions & Concurrency

MVCC (Multi-Version Concurrency Control)

MVCC allows readers and writers to operate concurrently without blocking:

// Enable MVCC (enabled by default)
.WithMvcc()

// Snapshot isolation gives each transaction a consistent view
.WithDefaultIsolationLevel(IsolationLevel.Snapshot)

→ Detailed documentation: Transactions & Concurrency

Row-Level Locking

Fine-grained locking for pessimistic concurrency control:

-- Exclusive lock (prevent other writes and locks)
SELECT * FROM Orders WHERE Id = 1 FOR UPDATE;

-- Shared lock (allow other reads, prevent writes)
SELECT * FROM Orders WHERE Status = 'pending' FOR SHARE;

-- Non-blocking variants
SELECT * FROM Orders WHERE Id = 1 FOR UPDATE NOWAIT;
SELECT * FROM Orders WHERE Id = 1 FOR UPDATE SKIP LOCKED;

→ Detailed documentation: Transactions & Concurrency

Encryption

Protect data at rest with industry-standard encryption:

// Via connection string
"Data Source=secure.witdb;Encryption=aes-gcm;Password=MySecretPassword"

// Via builder
.WithEncryption("MySecretPassword")           // AES-GCM (default)
.WithChaCha20Encryption("MySecretPassword")   // ChaCha20-Poly1305

Security Features:

• PBKDF2 key derivation with configurable iterations
• User-based salt for multi-tenant scenarios
• Page-level encryption (entire database encrypted)
• No plaintext data on disk

→ Detailed documentation: Encryption

Indexing

Automatic and manual indexes for query optimization:

-- Unique index
CREATE UNIQUE INDEX IX_Users_Email ON Users(Email);

-- Composite index
CREATE INDEX IX_Orders_Customer_Date ON Orders(CustomerId, OrderDate DESC);

-- Covering index
CREATE INDEX IX_Products_Category ON Products(CategoryId) INCLUDE (Name, Price);

→ Detailed documentation: Indexing

Caching

Configurable page cache for optimal memory usage:

// Via connection string
"Data Source=app.witdb;Cache=lru;Cache Size=5000"

// Via builder
.WithCacheSize(5000)        // 5000 pages
.WithCacheAlgorithm("lru")  // LRU instead of default Clock

Guidelines:

• Default: 1000 pages (~4 MB with 4KB pages)
• Read-heavy: Increase cache size
• Memory-constrained: Reduce cache size

→ Detailed documentation: Caching

Write-Ahead Logging (WAL)

Durability and crash recovery:

// Via connection string
"Data Source=app.witdb;Journal=wal"

// Via builder
.WithWalJournal()       // WAL mode (default)
.WithRollbackJournal()  // Rollback journal

Recovery Process:

1. On crash, incomplete transactions are in the journal
2. On next open, journal is automatically replayed
3. Database is restored to last consistent state
4. No data loss for committed transactions

→ Detailed documentation: Write-Ahead Logging

Platform Support

WitDatabase runs everywhere .NET runs:

// Desktop / Server
var db = new WitDatabaseBuilder()
    .WithFilePath("app.witdb")
    .WithBTree()
    .Build();

// Blazor WebAssembly
var db = new WitDatabaseBuilder()
    .WithIndexedDbStorage("MyApp", JSRuntime)
    .WithBTree()
    .WithEncryption("password")
    .Build();

→ Detailed documentation: Platform Support

Extensibility

Replace any component with custom implementations:

// Register custom provider
ProviderRegistry.Instance.Register<ICryptoProvider>("my-hsm", 
    p => new HsmCryptoProvider(p.GetRequired<string>("keyId")));

// Use custom provider
var db = new WitDatabaseBuilder()
    .WithFilePath("secure.witdb")
    .WithEncryption("my-hsm", new ProviderParameters()
        .Set("keyId", "production-key"))
    .Build();

→ Detailed documentation: Extensibility

Feature Availability by API

Not all features are available through all APIs. Use this matrix to understand what's available where:

Recommendations:

• Core API — Maximum performance, simple key-value access
• SQL Engine — Direct SQL without ADO.NET overhead
• ADO.NET — Standard .NET data access, compatibility
• EF Core — Full ORM, LINQ, migrations, productivity

Quick Configuration Reference

Connection String (ADO.NET / EF Core)

// Minimal
"Data Source=app.witdb"

// With encryption
"Data Source=app.witdb;Encryption=aes-gcm;Password=secret"

// Full configuration
"Data Source=app.witdb;Store=btree;Encryption=aes-gcm;Password=secret;MVCC=true;Isolation Level=Snapshot;Cache Size=5000;Journal=wal"

Builder Pattern (Core API / SQL Engine)

var db = new WitDatabaseBuilder()
    // Storage
    .WithFilePath("app.witdb")      // File path
    .WithBTree()                     // Storage engine
    
    // Security
    .WithEncryption("password")      // AES-GCM encryption
    
    // Transactions
    .WithTransactions()              // Enable transactions
    .WithMvcc()                      // Enable MVCC
    .WithDefaultIsolationLevel(IsolationLevel.Snapshot)
    
    // Performance
    .WithCacheSize(5000)             // Page cache size
    .WithWalJournal()                // WAL journaling
    
    .Build();