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 five fundamental data types supported by the database.

Null — Absence of value
Integer — 64-bit signed integer
Real — 64-bit floating point
Text — UTF-8 string
Blob — Raw byte array
struct

DbValue

A dynamically-typed database value wrapping one of the five core types.

Static Factory Methods

FromInteger(long value) → DbValue
FromReal(double value) → DbValue
FromText(string value) → DbValue
FromBlob(byte[] value) → DbValue

Properties

Type → DbType
AsInteger → long
AsReal → double
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.

Constructor

TableSchema(string name, ColumnDefinition[] columns)

Properties

Name → string
Columns → IReadOnlyList<ColumnDefinition>
PrimaryKeyColumnIndex → int

Methods

GetColumnIndex(string name) → int
CreateJoinSchema(TableSchema other) → TableSchema
class

IndexSchema

Defines a secondary index on table columns.

Name → string
TableName → string
Columns → 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.BTree

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>

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>