CSharpDB.Engine

Top-level database API, snapshot readers, and typed Collection<T> access.

class

Database

The primary entry point for embedded database usage. Manages the storage engine, SQL execution, transactions, and collection access.

Static Factory Methods

OpenAsync(string path) → ValueTask<Database>

OpenAsync(string path, DatabaseOptions options) → ValueTask<Database>

OpenInMemoryAsync() → ValueTask<Database>

OpenInMemoryAsync(DatabaseOptions options) → ValueTask<Database>

LoadIntoMemoryAsync(string path) → ValueTask<Database>

LoadIntoMemoryAsync(string path, DatabaseOptions options) → ValueTask<Database>

OpenHybridAsync(string path) → ValueTask<Database>

OpenHybridAsync(string path, DatabaseOptions options, HybridDatabaseOptions hybridOptions) → ValueTask<Database>

SQL Execution

ExecuteAsync(string sql) → ValueTask<QueryResult>

Collections

GetCollectionAsync<T>(string name) → ValueTask<Collection<T>>

Transactions

BeginTransactionAsync() → ValueTask

CommitAsync() → ValueTask

RollbackAsync() → ValueTask

Maintenance & Snapshots

CheckpointAsync() → ValueTask

SaveToFileAsync(string filePath) → ValueTask

CreateReaderSession() → ReaderSession

class

Collection<T>

Typed NoSQL document collection with JSON serialization, string keys, and path-based indexing.

CRUD

PutAsync(string key, T document) → ValueTask

GetAsync(string key) → ValueTask<T?>

DeleteAsync(string key) → ValueTask<bool>

CountAsync() → ValueTask<long>

ScanAsync() → IAsyncEnumerable<KeyValuePair<string, T>>

Querying

FindAsync(Func<T, bool> predicate) → IAsyncEnumerable<KeyValuePair<string, T>>

FindByIndexAsync<TField>(Expression<Func<T, TField>> fieldSelector, TField value) → IAsyncEnumerable<KeyValuePair<string, T>>

FindByPathAsync<TField>(string fieldPath, TField value) → IAsyncEnumerable<KeyValuePair<string, T>>

FindByPathRangeAsync<TField>(string fieldPath, TField lowerBound, TField upperBound, ...) → IAsyncEnumerable<KeyValuePair<string, T>>

Indexing

EnsureIndexAsync<TField>(Expression<Func<T, TField>> fieldSelector) → ValueTask

EnsureIndexAsync(string fieldPath) → ValueTask

class

ReaderSession

Snapshot-isolated read-only session. Only one active query can exist per reader session at a time.

ExecuteReadAsync(string sql) → ValueTask<QueryResult>

ExecuteReadAsync(Statement stmt) → ValueTask<QueryResult>

Dispose() → void

class

QueryResult

Streaming query result for SQL execution and reader sessions.

MoveNextAsync() → ValueTask<bool>

Current → DbValue[]

Schema → ColumnDefinition[]

RowsAffected → int

ToListAsync() → ValueTask<List<DbValue[]>>

GetRowsAsync() → IAsyncEnumerable<DbValue[]>

CSharpDB.Primitives

Primitive types, schemas, and exceptions.

enum

DbType

The six compact physical value carriers supported by the database. Logical SQL declarations such as BOOLEAN, INTEGER, BIGINT, temporal types, and bit strings retain separate declared-type metadata over these carriers; see the SQL data type reference.

Null — Absence of value

Integer — Shared 64-bit physical carrier; declared INTEGER is signed 32-bit

Real — 64-bit floating point

Text — UTF-8 string

Blob — Raw byte array

Decimal — Exact base-10 decimal with up to 18 digits of precision

struct

DbValue

A dynamically-typed database value wrapping one of the six physical carriers.

Static Factory Methods

FromInteger(long value) → DbValue

FromReal(double value) → DbValue

FromDecimal(decimal value) → DbValue

FromDecimalParts(long coefficient, int scale) → DbValue

FromText(string value) → DbValue

FromBlob(byte[] value) → DbValue

Properties

Type → DbType

AsInteger → long

AsReal → double

AsDecimal → decimal

DecimalCoefficient → long

DecimalScale → int

AsText → string

AsBlob → byte[]

IsNull → bool

IsTruthy → bool

Static Methods

Compare(DbValue a, DbValue b) → int

class

TableSchema

Defines the structure of a database table.

Properties (required init)

TableName → string

Columns → IReadOnlyList<ColumnDefinition>

PrimaryKeyColumnIndex → int

Methods

GetColumnIndex(string name) → int

static CreateJoinSchema(TableSchema leftSchema, TableSchema rightSchema) → TableSchema

class

IndexSchema

Defines a secondary index on table columns.

IndexName → string

TableName → string

Columns → IReadOnlyList<string>

IsUnique → bool

CSharpDB.Storage.Paging

Page I/O, transaction management, and buffer coordination.

class

Pager

Core page I/O manager. Handles single-writer transactions, WAL integration, and dirty page tracking.

Transaction Methods

BeginTransactionAsync() → ValueTask

CommitAsync() → ValueTask

RollbackAsync() → ValueTask

Page Operations

GetPageAsync(uint pageId) → ValueTask<byte[]>

AllocatePageAsync() → ValueTask<uint>

MarkDirtyAsync(uint pageId) → ValueTask

Snapshot

AcquireReaderSnapshot() → WalSnapshot

CreateSnapshotReader(WalSnapshot snapshot) → Pager

ReleaseReaderSnapshot() → void

class

SlottedPage

In-memory page abstraction. 4096-byte slotted format with cell pointer array and cell data.

CSharpDB.Storage.BTrees

Persistent B+tree keyed by long rowid.

class

BTree

InsertAsync(long key, ReadOnlyMemory<byte> payload) → ValueTask

FindAsync(long key) → ValueTask<byte[]?>

DeleteAsync(long key) → ValueTask<bool>

CreateCursor() → BTreeCursor

class

BTreeCursor

MoveNextAsync() → ValueTask<bool>

SeekAsync(long targetKey) → ValueTask<bool>

CurrentKey → long

CurrentValue → ReadOnlyMemory<byte>

CSharpDB.Storage.Catalog

Schema metadata management.

class

SchemaCatalog

Tables

CreateTableAsync(TableSchema schema) → ValueTask

GetTable(string tableName) → TableSchema?

DropTableAsync(string tableName) → ValueTask

GetTableTree(string tableName) → BTree

Indexes

CreateIndexAsync(IndexSchema schema) → ValueTask

GetIndex(string indexName) → IndexSchema?

DropIndexAsync(string indexName) → ValueTask

Views & Triggers

CreateViewAsync(string viewName, string sql) → ValueTask

CreateTriggerAsync(TriggerSchema schema) → ValueTask

CSharpDB.Storage.Indexing

Secondary index implementations with B+tree backing.

class

BTreeIndexStore

FindAsync(long key) → ValueTask<byte[]?>

FindMaxKeyAsync(IndexScanRange range) → ValueTask<long?>

InsertAsync(long key, ReadOnlyMemory<byte> payload) → ValueTask

ReplaceAsync(long key, ReadOnlyMemory<byte> payload) → ValueTask<bool>

DeleteAsync(long key) → ValueTask<bool>

CreateCursor(IndexScanRange range) → IIndexCursor

class

CachingIndexStore

Wraps an IIndexStore with an in-memory cache for frequently accessed index entries.

CSharpDB.Storage.Wal

Write-ahead log for durability and crash recovery.

class

WriteAheadLog

WriteFrameAsync(WalFrameWrite frame) → ValueTask

RecoverAsync() → ValueTask

CheckpointAsync() → ValueTask

class

CheckpointCoordinator

Manages checkpoint scheduling based on configured policies.

CheckpointIfNeededAsync() → ValueTask

ForceCheckpointAsync() → ValueTask

CSharpDB.Storage.Serialization

Record and schema encoding/decoding.

class

DefaultRecordSerializer

Encode(DbValue[] values) → byte[]

Decode(byte[] data, TableSchema schema) → DbValue[]

CSharpDB.Data

Standard ADO.NET provider for CSharpDB.

class

CSharpDbConnection

Implements DbConnection. Connection string format: Data Source=path.db

CSharpDbConnection(string connectionString)

OpenAsync() → Task

CreateCommand() → CSharpDbCommand

BeginTransactionAsync() → ValueTask<DbTransaction>

SaveToFileAsync(string filePath) → ValueTask

ClearPool(string connectionString) → void

ClearAllPools() → void

class

CSharpDbCommand

Implements DbCommand. Supports parameterized SQL execution.

CommandText → string

Parameters → CSharpDbParameterCollection

ExecuteNonQueryAsync() → Task<int>

ExecuteReaderAsync() → Task<DbDataReader>

ExecuteScalarAsync() → Task<object?>

class

CSharpDbDataReader

Implements DbDataReader. Provides column accessors for query results.

ReadAsync() → Task<bool>

GetString(int ordinal) → string

GetInt64(int ordinal) → long

GetDouble(int ordinal) → double

IsDBNull(int ordinal) → bool

FieldCount → int

GetName(int ordinal) → string

class

CSharpDbParameterCollection

Provider-specific parameter collection exposed by CSharpDbCommand.Parameters.

AddWithValue(string name, object? value) → CSharpDbParameter

Add(object value) → int

Clear() → void

CSharpDB.Client

Unified client SDK with pluggable transports.

class

CSharpDbClient

Unified client interface supporting Direct, HTTP, and gRPC transports.

Factory

Create(CSharpDbClientOptions options) → ICSharpDbClient

Representative Operations

GetInfoAsync() → Task<DatabaseInfo>

GetTableNamesAsync() → Task<IReadOnlyList<string>>

GetTableSchemaAsync(string tableName) → Task<TableSchema?>

ExecuteSqlAsync(string sql) → Task<SqlExecutionResult>

ExecuteProcedureAsync(string name, IReadOnlyDictionary<string, object?> args) → Task<ProcedureExecutionResult>

BeginTransactionAsync() → Task<TransactionSessionInfo>

ExecuteInTransactionAsync(string transactionId, string sql) → Task<SqlExecutionResult>

GetCollectionNamesAsync() → Task<IReadOnlyList<string>>

GetDocumentAsync(string collectionName, string key) → Task<JsonElement?>

PutDocumentAsync(string collectionName, string key, JsonElement document) → Task

CheckpointAsync() → Task

BackupAsync(BackupRequest request) → Task<BackupResult>

interface

ICSharpDbObservabilityClient

Optional additive runtime-diagnostics capability. Discover it separately from ICSharpDbClient so custom and older client implementations remain source and binary compatible. Results use versioned topology envelopes with explicit availability and bounded collection metadata.

GetRuntimeDiagnosticsAsync() → Task<DiagnosticsTopologySnapshot<RuntimeDiagnosticsSnapshot>>

GetStorageDiagnosticsAsync() → Task<DiagnosticsTopologySnapshot<DiagnosticsValueSnapshot<StorageRuntimeDiagnosticsSnapshot>>>

GetWalDiagnosticsAsync() → Task<DiagnosticsTopologySnapshot<DiagnosticsValueSnapshot<WalRuntimeDiagnosticsSnapshot>>>

GetActiveQueriesAsync(int maximumRecords) → Task<DiagnosticsTopologySnapshot<DiagnosticsCollectionSnapshot<ActiveQuerySnapshot>>>

GetRecentQueriesAsync(int maximumRecords) → Task<DiagnosticsTopologySnapshot<DiagnosticsCollectionSnapshot<RecentQuerySnapshot>>>

GetQueryPlanDiagnosticsAsync(OpaqueDiagnosticsId operationId) → bounded plan snapshot without query replay

GetSessionsAsync(int maximumRecords) → capped safe session snapshot

GetActiveMaintenanceOperationsAsync(int maximumRecords) → capped active maintenance snapshot

GetRecentMaintenanceOperationsAsync(int maximumRecords) → capped terminal maintenance snapshot

GetQueryDetailAsync(OpaqueDiagnosticsId operationId) → separately authorized captured detail

Ordinary summaries never contain SQL, values, credentials, connection strings, or paths. See Observability and Diagnostics for transport behavior, privacy, and availability states.

CSharpDB.Pipelines

ETL pipeline orchestration and execution.

class

PipelineOrchestrator

Executes pipeline packages from definition to completion.

ExecuteAsync(PipelineRunRequest request) → Task<PipelineRunResult>

class

PipelinePackageDefinition

JSON-serializable pipeline definition with source, transforms, and destination.

Name → string

Version → string

Description → string?

Source → PipelineSourceDefinition

Transforms → IReadOnlyList<PipelineTransformDefinition>

Destination → PipelineDestinationDefinition

Options → PipelineExecutionOptions

Incremental → PipelineIncrementalOptions?

class

PipelinePackageValidator

Validates pipeline definitions for correctness before execution.

Validate(PipelinePackageDefinition package) → PipelineValidationResult

class

PipelinePackageSerializer

Serializes pipeline definitions to and from the JSON package format.

Serialize(PipelinePackageDefinition package) → string

Deserialize(string json) → PipelinePackageDefinition

SaveToFileAsync(PipelinePackageDefinition package, string path) → Task

LoadFromFileAsync(string path) → Task<PipelinePackageDefinition>

enum

PipelineExecutionMode

Validate

DryRun

Run

Resume

CSharpDB.Storage.Diagnostics

Inspection and validation utilities.

class

DatabaseInspector

Full database inspection: file header validation, page walks, B+tree consistency, page histograms.

InspectAsync(string dbPath) → Task<DatabaseInspectReport>

class

WalInspector

Validates WAL header, frame salts, and checksums for each committed frame.

InspectAsync(string walPath) → Task<WalReport>

class

IndexInspector

Verifies index root page validity, table/column references, and B+tree reachability.

InspectAsync(string dbPath) → Task<IndexReport>