Connection Strings Reference

This document provides a complete reference for WitDatabase connection string parameters. Connection strings are used with ADO.NET provider and Entity Framework Core.

Basic Format

Data Source=path/to/database.witdb;Property1=Value1;Property2=Value2

Rules:

• Property names are case-insensitive (Data Source = data source = DATA SOURCE)
• Values with spaces or semicolons must be quoted: Password="my;secret"
• Boolean values: true/false, yes/no, 1/0
• Use forward slashes / or escaped backslashes \\ in paths

Quick Examples

// Minimal
"Data Source=app.witdb"

// In-memory (testing)
"Data Source=:memory:"

// With encryption
"Data Source=secure.witdb;Encryption=aes-gcm;Password=MySecret123!"

// High-performance writes (LSM-Tree)
"Data Source=/data/logs;Store=lsm;Sync Writes=false"

// Read-only access
"Data Source=archive.witdb;Mode=ReadOnly;Cache Size=10000"

// Production with pooling
"Data Source=/var/app/data.witdb;Encryption=aes-gcm;Password=***;Pooling=true;Max Pool Size=50"

Core Properties

Data Source

// File-based database
"Data Source=myapp.witdb"
"Data Source=C:\\Data\\myapp.witdb"
"Data Source=/var/lib/myapp/data.witdb"

// In-memory (non-persistent)
"Data Source=:memory:"

// Relative path
"Data Source=./data/app.witdb"

Mode

"Data Source=app.witdb;Mode=ReadOnly"
"Data Source=app.witdb;Read Only=true"  // Equivalent
"Data Source=temp;Mode=Memory"          // In-memory

Storage Engine

Engine Comparison

// B+Tree (default) — general purpose
"Data Source=app.witdb;Store=btree"

// LSM-Tree — write-optimized
"Data Source=logs.witdb;Store=lsm"

// In-memory — testing
"Data Source=:memory:;Store=inmemory"

Tip: Start with btree. Switch to lsm only if you have write-heavy workloads (>80% writes) or time-series data.

Encryption

Encryption Algorithms

Examples

// Simple password encryption
"Data Source=secure.witdb;Encryption=aes-gcm;Password=MySecretPassword123!"

// Multi-tenant (different keys per user)
"Data Source=multi.witdb;Encryption=aes-gcm;User=tenant1;Password=TenantPass123"

// ChaCha20 for Blazor WASM or ARM without AES-NI
"Data Source=app.witdb;Encryption=chacha20-poly1305;Password=MyPassword"

// Fast encryption for Blazor WASM (fewer PBKDF2 iterations)
"Data Source=wasm.witdb;Encryption=aes-gcm;Password=WasmPass;Fast Encryption=true"

Security Warning: Never hardcode passwords in source code. Use environment variables, configuration files, or secrets management (Azure Key Vault, AWS Secrets Manager).

// Good: from environment
var password = Environment.GetEnvironmentVariable("DB_PASSWORD");

        
        

            
            Loading...
        
quot;Data Source=app.witdb;Encryption=aes-gcm;Password={password}"

// Good: from configuration
var password = Configuration["Database:Password"];

Caching

Cache Algorithms

Tuning Guidelines

// Default caching
"Data Source=app.witdb"

// Large cache for read-heavy workload
"Data Source=app.witdb;Cache Size=10000"

// Large page size for BLOB storage
"Data Source=files.witdb;Page Size=16384;Cache Size=2000"

// Memory-constrained (Blazor WASM)
"Data Source=app.witdb;Cache Size=300;Page Size=4096"

Memory formula: Cache Size × Page Size ≈ cache memory usage.
Example: 5000 pages × 4096 bytes = ~20 MB

Transactions

Isolation Levels

Recommendation: Use Snapshot for read-heavy workloads with MVCC. It provides strong consistency without blocking readers.

Journal Modes

// Default (transactions enabled, ReadCommitted)
"Data Source=app.witdb"

// Snapshot isolation (recommended for read-heavy)
"Data Source=app.witdb;Isolation Level=Snapshot"

// Disable transactions (maximum performance, no ACID guarantees)
"Data Source=cache.witdb;Transactions=false"

// Disable MVCC (single-writer scenarios)
"Data Source=app.witdb;MVCC=false"

// Rollback journal instead of WAL
"Data Source=app.witdb;Journal=rollback"

Concurrency

Parallel Mode

// Default (single writer, file locking)
"Data Source=app.witdb"

// Disable file locking (single-process only!)
"Data Source=app.witdb;File Locking=false"

// Custom lock timeout (60 seconds)
"Data Source=app.witdb;Lock Timeout=60"

// Parallel writes for high-throughput
"Data Source=app.witdb;Parallel Mode=Auto;Max Writers=8"

Warning: Only disable file locking if you guarantee single-process access. Multiple processes without locking will corrupt the database.

Common Scenarios

Development / Testing

// Simple file database
"Data Source=dev.witdb"

// In-memory for unit tests
"Data Source=:memory:"

Web Application (ASP.NET Core)

// With encryption and connection pooling
"Data Source=/var/app/data.witdb;Encryption=aes-gcm;Password=***;Pooling=true;Max Pool Size=50;Isolation Level=Snapshot"

Desktop Application

// User-specific encrypted database
var appData = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);

        
        

            
            Loading...
        
quot;Data Source={appData}/MyApp/data.witdb;Encryption=aes-gcm;Password={userPassword}"

Read-Only Analytics

// Large cache, LRU for sequential scans
"Data Source=analytics.witdb;Mode=ReadOnly;Cache Size=20000;Cache=lru"

Blazor WebAssembly

// Optimized for browser: small cache, fast encryption
"Data Source=app.witdb;Encryption=aes-gcm;Password=***;Fast Encryption=true;Cache Size=300"

LSM-Tree Configuration

These parameters only apply when Store=lsm. LSM-Tree is optimized for write-heavy workloads.

LSM Architecture Overview

[[Svg Src="./witdatabase-lsm-write-flow.svg" Alt="witdatabase-lsm-write-flow"]]

Tuning Guidelines

Examples

// High-throughput logging (async writes, large buffers)
"Data Source=/data/logs;Store=lsm;Sync Writes=false;MemTable Size=16777216;Block Cache Size=134217728"

// Memory-constrained environment
"Data Source=/data/app;Store=lsm;MemTable Size=2097152;Block Cache Size=16777216"

// Maximum durability (sync every write)
"Data Source=/data/financial;Store=lsm;Sync Writes=true;LSM WAL=true"

// Disable compaction (manual control)
"Data Source=/data/bulk;Store=lsm;Background Compaction=false"

Durability Warning: Sync Writes=false significantly improves write performance but risks losing the most recent writes (up to MemTable size) on system crash.

Connection Pooling

Connection pooling reuses database connections to reduce overhead in applications with frequent connect/disconnect patterns.

When to Use Pooling

Examples

// Basic pooling for web applications
"Data Source=app.witdb;Pooling=true"

// Production web API with tuned pool
"Data Source=app.witdb;Pooling=true;Min Pool Size=5;Max Pool Size=50"

// High-load API server
"Data Source=app.witdb;Pooling=true;Min Pool Size=10;Max Pool Size=200;Connection Lifetime=3600"

// With encryption
"Data Source=secure.witdb;Encryption=aes-gcm;Password=***;Pooling=true;Max Pool Size=50"

Pool Management in Code

// Clear specific pool
WitDbConnection.ClearPool(connectionString);

// Clear all pools
WitDbConnection.ClearAllPools();

Best Practice: In ASP.NET Core, let the DI container manage connection lifetime. Use AddDbContext or AddDbContextPool for EF Core.

Secondary Indexes

By default, secondary indexes are stored alongside the main database file. Use Index Directory to store them separately (useful for different storage tiers).

// Indexes on fast SSD, data on HDD
"Data Source=/hdd/data.witdb;Index Directory=/ssd/indexes"

Connection String Builder

For programmatic construction, use WitDbConnectionStringBuilder:

using OutWit.Database.AdoNet;

var builder = new WitDbConnectionStringBuilder
{
    DataSource = "/var/app/data.witdb",
    Store = "btree",
    Encryption = "aes-gcm",
    Password = Configuration["Database:Password"],
    CacheSize = 5000,
    IsolationLevel = WitDbIsolationLevel.Snapshot,
    Pooling = true,
    MaxPoolSize = 50
};

var connectionString = builder.ConnectionString;
// Result: "Data Source=/var/app/data.witdb;Store=btree;Encryption=aes-gcm;Password=***;..."

Parsing Existing Connection String

var builder = new WitDbConnectionStringBuilder(existingConnectionString);

// Read properties
Console.WriteLine(builder.DataSource);      // "/var/app/data.witdb"
Console.WriteLine(builder.Encryption);      // "aes-gcm"
Console.WriteLine(builder.CacheSize);       // 5000

// Modify
builder.CacheSize = 10000;
var newConnectionString = builder.ConnectionString;

Validation

var builder = new WitDbConnectionStringBuilder
{
    DataSource = "app.witdb",
    Encryption = "aes-gcm"
    // Missing Password!
};

// Check for errors
var errors = builder.Validate();
foreach (var error in errors)
{
    Console.WriteLine(error);  // "Password is required when encryption is enabled."
}

// Or throw exception
builder.ThrowIfInvalid();  // Throws ArgumentException

Builder Properties Reference

Enums

WitDbConnectionMode:

public enum WitDbConnectionMode
{
    ReadWriteCreate,  // Default
    ReadWrite,
    ReadOnly,
    Memory
}

WitDbIsolationLevel:

public enum WitDbIsolationLevel
{
    ReadUncommitted,
    ReadCommitted,    // Default
    RepeatableRead,
    Serializable,
    Snapshot
}

WitDbParallelMode:

public enum WitDbParallelMode
{
    None,       // Default - single writer
    Auto,       // Recommended - automatic selection
    Buffered,   // Buffer writes, batch commit
    Latched,    // Page-level latching
    Optimistic  // Optimistic concurrency
}

Complete Properties Reference

All connection string properties in one table:

Core

Storage Engine

Encryption

Cache

Transactions

Concurrency

Connection Pooling

LSM-Tree (only when Store=lsm)

Index