CSharpDB.Service
Thread-safe service layer for hosting CSharpDB in ASP.NET Core, Blazor, or MCP server applications.
Ask AI about CSharpDB.Service
Powered by Claude Β· Grounded in docs
I know everything about CSharpDB.Service. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
CSharpDB
A lightweight, embedded SQL database engine written from scratch in C#. Single-file storage, WAL-based crash recovery, concurrent readers, async-first API, zero external dependencies.
Why CSharpDB?
CSharpDB is a fully self-contained database engine that runs inside your .NET application β no server process, no external dependencies, just a single .db file on disk. It provides two data-access paths: a full SQL engine with JOINs, aggregates, views, triggers, and indexes, and a NoSQL Collection API that bypasses SQL entirely for sub-microsecond key-value reads.
Use cases:
- Embedded databases for desktop, CLI, or IoT applications
- Prototyping and local development without setting up a database server
- Educational reference for understanding database internals (storage engines, B+trees, WAL, query planning)
- Cross-language interoperability via the native C library, REST API, or Node.js package
Features
| Category | Details |
|---|---|
| Storage | Single .db file, 4 KB page-oriented, B+tree-backed tables and indexes |
| Durability | Write-Ahead Log (WAL) with fsync-on-commit, automatic crash recovery |
| Concurrency | Single writer + concurrent snapshot-isolated readers via WAL-based MVCC |
| SQL | DDL, DML, JOINs, aggregates, GROUP BY, HAVING, CTEs, views, triggers, indexes, and sys.* catalog queries |
| NoSQL | Typed Collection<T> with Put/Get/Delete/Scan/Find β 1.44M reads/sec |
| ADO.NET | Standard DbConnection/DbCommand/DbDataReader provider |
| Client SDK | CSharpDB.Client β unified API with pluggable transports (Direct, HTTP, gRPC, TCP, Named Pipes) |
| Native FFI | NativeAOT-compiled C library (.dll/.so/.dylib) β use CSharpDB from Python, Node.js, Go, Rust, Swift, Kotlin, Dart, and more |
| Node.js Client | TypeScript/JavaScript package (csharpdb) wrapping the native library via koffi |
| REST API | ASP.NET Core Minimal API with 33 endpoints, OpenAPI/Scalar UI |
| MCP Server | Model Context Protocol server β let AI assistants query and modify your database |
| Admin UI | Blazor Server dashboard for browsing tables, views, indexes, triggers |
| Procedures | Table-backed stored procedure catalog (__procedures) with typed params and transactional execution |
| CLI | Interactive REPL with meta-commands, file execution, snapshot mode, remote connectivity |
| Dependencies | Zero β pure .NET 10, nothing else |
Admin UI Preview
See the product first, then dive into the API and internals:
| Querying Metadata | Table Data View | Table Schema View |
|---|---|---|
![]() | ![]() | ![]() |
Quick Start
Install the recommended entry package:
dotnet add package CSharpDB
Engine API
using CSharpDB.Engine;
await using var db = await Database.OpenAsync("mydata.db");
await db.ExecuteAsync("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)");
await db.ExecuteAsync("INSERT INTO users VALUES (1, 'Alice', 30)");
await db.ExecuteAsync("INSERT INTO users VALUES (2, 'Bob', 25)");
await using var result = await db.ExecuteAsync(
"SELECT * FROM users WHERE age > 26 ORDER BY name ASC");
await foreach (var row in result.GetRowsAsync())
Console.WriteLine($"{row[0].AsInteger}: {row[1].AsText}, age {row[2].AsInteger}");
// 1: Alice, age 30
Collection API (NoSQL)
var users = await db.GetCollectionAsync<User>("users");
await users.PutAsync("user:1", new User("Alice", 30, "alice@example.com"));
var alice = await users.GetAsync("user:1");
await foreach (var kvp in users.FindAsync(u => u.Age > 25))
Console.WriteLine(kvp.Value.Name);
record User(string Name, int Age, string Email);
ADO.NET Provider
using CSharpDB.Data;
await using var conn = new CSharpDbConnection("Data Source=myapp.db");
await conn.OpenAsync();
using var cmd = conn.CreateCommand();
cmd.CommandText = "SELECT * FROM users WHERE age > @age";
cmd.Parameters.AddWithValue("@age", 25);
await using var reader = await cmd.ExecuteReaderAsync();
while (await reader.ReadAsync())
Console.WriteLine($"{reader.GetInt64(0)}: {reader.GetString(1)}");
REST API
# Start the API server
dotnet run --project src/CSharpDB.Api
# Create a table
curl -X POST http://localhost:61818/api/sql/execute \
-H "Content-Type: application/json" \
-d '{"sql": "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"}'
# Insert a row
curl -X POST http://localhost:61818/api/tables/users/rows \
-H "Content-Type: application/json" \
-d '{"values": {"id": 1, "name": "Alice"}}'
# Browse rows
curl http://localhost:61818/api/tables/users/rows
CLI
# Local database
dotnet run --project src/CSharpDB.Cli -- mydata.db
# Connect to a remote CSharpDB server
dotnet run --project src/CSharpDB.Cli -- --endpoint http://localhost:61818
csdb> CREATE TABLE demo (id INTEGER PRIMARY KEY, name TEXT);
csdb> INSERT INTO demo VALUES (1, 'Hello');
csdb> SELECT * FROM demo;
csdb> .tables
csdb> .quit
MCP Server (AI Integration)
Connect AI assistants like Claude Desktop, Cursor, OpenAI Codex, LM Studio, or VS Code Copilot to your database:
dotnet run --project src/CSharpDB.Mcp -- --database mydata.db
Add to claude_desktop_config.json (or .mcp.json for Claude Code / Cursor):
{
"mcpServers": {
"csharpdb": {
"command": "dotnet",
"args": ["run", "--project", "path/to/src/CSharpDB.Mcp", "--", "--database", "mydata.db"]
}
}
}
Or for OpenAI Codex CLI (~/.codex/config.toml):
[mcp_servers.csharpdb]
command = "dotnet"
args = ["run", "--project", "path/to/src/CSharpDB.Mcp", "--", "--database", "mydata.db"]
The MCP server exposes 15 tools for schema inspection, data browsing, row mutations, and SQL execution. See the MCP Server Reference for the full tool list and configuration options for all supported clients.
Client SDK
The unified CSharpDB.Client SDK provides a single ICSharpDbClient interface with pluggable transports:
using CSharpDB.Client;
// Direct (in-process) β default
var client = CSharpDbClient.Create(new CSharpDbClientOptions
{
DataSource = "mydata.db"
});
// All database operations go through the client
var tables = await client.GetTableNamesAsync();
var result = await client.ExecuteSqlAsync("SELECT * FROM users WHERE age > 25");
await client.InsertRowAsync("users", new Dictionary<string, object?>
{
["id"] = 3, ["name"] = "Charlie", ["age"] = 28
});
// DI registration
services.AddCSharpDbClient(new CSharpDbClientOptions { DataSource = "mydata.db" });
The transport layer supports Direct (in-process), HTTP, gRPC, TCP, and Named Pipes. Direct is fully implemented; network transports are part of the public API contract and planned for the service daemon milestone.
Cross-Language Interop (Native FFI)
CSharpDB compiles to a standalone native library via NativeAOT β no .NET runtime required at the call site. Any language with C FFI support can use it.
Node.js (via csharpdb package):
import { Database } from 'csharpdb';
const db = new Database('mydata.db');
db.execute('CREATE TABLE demo (id INTEGER PRIMARY KEY, name TEXT)');
db.execute("INSERT INTO demo VALUES (1, 'Alice')");
for (const row of db.query('SELECT * FROM demo'))
console.log(row);
db.close();
Python (via ctypes β zero dependencies):
from csharpdb import Database
with Database("mydata.db") as db:
db.execute("CREATE TABLE demo (id INTEGER PRIMARY KEY, name TEXT)")
db.execute("INSERT INTO demo VALUES (1, 'Alice')")
for row in db.query("SELECT * FROM demo"):
print(row)
The native library exports 20 C functions covering database lifecycle, SQL execution, result iteration, transactions, and error handling. See the Native Library Reference for the full API, build instructions, and examples for C, Go, Rust, Swift, Kotlin, and Dart.
Architecture
SQL string Collection<T> API
β β
[Tokenizer] ββ Sql [JSON serialize] ββ Engine
β β
[Parser β AST] (bypassed)
β β
[Query Planner] ββ Execution (bypassed)
β β
[Operator Tree] β
β β
[B+Tree] βββββββββββββββ [B+Tree] ββ Storage
β
[Pager + WAL] (page cache, dirty tracking, write-ahead log)
β
[File I/O] (4 KB pages, slotted page layout)
β
mydata.db + mydata.db.wal
The SQL path goes through tokenizer β parser β planner β operators β B+tree. The Collection API goes directly to the B+tree, bypassing SQL entirely for maximum throughput.
Project Structure
CSharpDB.slnx
βββ src/
β βββ CSharpDB.Core/ Primitives (DbValue, Schema, ErrorCodes)
β βββ CSharpDB/ All-in-one NuGet package metadata
β βββ CSharpDB.Storage/ Pager, B+tree, WAL, file I/O
β βββ CSharpDB.Sql/ Tokenizer, parser, AST, script splitter
β βββ CSharpDB.Execution/ Query planner, operators, expression evaluator
β βββ CSharpDB.Engine/ Top-level Database API + Collection<T> (NoSQL)
β βββ CSharpDB.Client/ Unified client SDK with transport abstraction
β βββ CSharpDB.Data/ ADO.NET provider (DbConnection, DbCommand, DbDataReader)
β βββ CSharpDB.Native/ NativeAOT C FFI library for cross-language interop
β βββ CSharpDB.Storage.Diagnostics/ Storage diagnostics and integrity checking
β βββ CSharpDB.Cli/ Interactive REPL with remote connectivity
β βββ CSharpDB.Service/ Compatibility facade over CSharpDB.Client
β βββ CSharpDB.Admin/ Blazor Server admin dashboard
β βββ CSharpDB.Api/ REST API (ASP.NET Core Minimal API)
β βββ CSharpDB.Mcp/ MCP server for AI assistant integration
βββ clients/
β βββ node/ Node.js/TypeScript client package (csharpdb)
βββ tests/
β βββ CSharpDB.Tests/ Engine unit + integration tests
β βββ CSharpDB.Data.Tests/ ADO.NET provider tests
β βββ CSharpDB.Cli.Tests/ CLI smoke + integration tests
β βββ CSharpDB.Benchmarks/ Performance benchmarks (BenchmarkDotNet + custom)
βββ samples/ Sample SQL datasets
βββ docs/ Documentation + FFI tutorials
Supported SQL
| Category | Syntax |
|---|---|
| DDL | CREATE TABLE, DROP TABLE, ALTER TABLE (ADD/DROP/RENAME COLUMN, RENAME TO) |
| DML | INSERT INTO ... VALUES, SELECT, UPDATE ... SET, DELETE FROM |
| Indexes | CREATE [UNIQUE] INDEX, DROP INDEX |
| Views | CREATE VIEW ... AS, DROP VIEW |
| Triggers | CREATE TRIGGER ... BEFORE/AFTER INSERT/UPDATE/DELETE ... BEGIN ... END |
| CTEs | WITH name AS (select) SELECT ... |
| JOINs | INNER JOIN, LEFT JOIN, RIGHT JOIN, CROSS JOIN |
| Aggregates | COUNT(*), COUNT(col), COUNT(DISTINCT col), SUM, AVG, MIN, MAX |
| Clauses | WHERE, GROUP BY, HAVING, ORDER BY, LIMIT, OFFSET |
| Expressions | =, <>, <, >, <=, >=, AND, OR, NOT, LIKE, IN, BETWEEN, IS NULL |
| Types | INTEGER (i64), REAL (f64), TEXT (UTF-8), BLOB (byte[]) |
System Catalog Queries
Use SQL to inspect schema metadata:
SELECT * FROM sys.tables ORDER BY table_name;
SELECT * FROM sys.columns WHERE table_name = 'users' ORDER BY ordinal_position;
SELECT * FROM sys.indexes WHERE table_name = 'users';
SELECT * FROM sys.views;
SELECT * FROM sys.triggers;
SELECT * FROM sys.objects ORDER BY object_type, object_name;
Underscored aliases are also supported: sys_tables, sys_columns, sys_indexes, sys_views, sys_triggers, sys_objects.
Building and Testing
Requires .NET 10 SDK.
dotnet build
dotnet run --project tests/CSharpDB.Tests/CSharpDB.Tests.csproj --
dotnet run --project tests/CSharpDB.Data.Tests/CSharpDB.Data.Tests.csproj --
dotnet run --project tests/CSharpDB.Cli.Tests/CSharpDB.Cli.Tests.csproj --
Performance Highlights
Benchmarks run on Intel i9-11900K, .NET 10, Windows 11. Full results in tests/CSharpDB.Benchmarks/README.md.
| Metric | Result |
|---|---|
| Single INSERT (auto-commit, durable) | 27,842 ops/sec |
| Batched INSERT (100 rows/tx) | ~370K rows/sec |
| Point lookup by PK (1K rows) | 786,596 ops/sec |
Collection GetAsync (10K docs) | 1,371,530 ops/sec |
| Concurrent readers (8 sessions) | 256,088 ops/sec |
ADO.NET ExecuteScalar | 323 ns / 696 bytes |
| Crash recovery | 100% reliable (50/50 cycles), P50 = 11.5 ms |
Samples
The samples/ directory contains ready-to-run SQL scripts for three realistic scenarios:
- ecommerce-store.sql β Northwind Electronics (customers, products, orders, reviews)
- medical-clinic.sql β Riverside Health Center (patients, doctors, appointments, billing)
- school-district.sql β Maplewood School District (students, courses, enrollments, attendance)
Each script creates 7 tables with sample data, indexes, views, and triggers. See the samples README for execution instructions.
Roadmap
See docs/roadmap.md for the full roadmap and status.
Recently completed
- Unified Client SDK (
CSharpDB.Client) with transport abstraction - NativeAOT C FFI library (
CSharpDB.Native) for cross-language interop - Node.js/TypeScript client package (
csharpdb) - CLI remote connectivity (
--endpoint,--transport) - SQL script splitter and statement classifier (
CSharpDB.Sql) - Service layer refactor to facade over
CSharpDB.Client - CI pipeline for cross-platform native library builds
SELECT DISTINCT, composite indexes, prepared statement caching
In progress
- Broader index range-scan planning (
<,>,<=,>=,BETWEEN) - Service daemon for persistent background hosting (HTTP/gRPC/TCP/Named Pipes)
- Network transport implementations for
CSharpDB.Client
Still planned
- B+tree delete rebalancing
- Python and Go client packages
Mid-term
- Subqueries and
EXISTS UNION/INTERSECT/EXCEPT- Window functions (
ROW_NUMBER,RANK)
Long-term
- Memory-mapped I/O (mmap) read path
- Full-text search
- JSON path querying for Collection API
- Secondary indexes for Collection API
Documentation
| Document | Description |
|---|---|
| Getting Started Tutorial | Step-by-step walkthrough from opening a database to transactions |
| Architecture Guide | Layer-by-layer deep dive into the engine design |
| Internals & Contributing | How to extend the engine, testing strategy, project layout |
| Client SDK | Unified client API, transport model, and DI integration |
| Native Library Reference | C FFI API, build instructions, and cross-language examples |
| Node.js Client | TypeScript/JavaScript package documentation |
| REST API Reference | All 33 API endpoints with request/response examples |
| MCP Server Reference | AI assistant integration via Model Context Protocol |
| CLI Reference | Interactive REPL commands and meta-commands |
| Storage Inspector | Read-only DB/WAL integrity diagnostics and page-level inspection |
| Service Daemon Design | Background service architecture and roadmap |
| FFI Tutorials | Step-by-step JavaScript and Python interop guides |
| FAQ | Common setup, SQL, Admin UI, and troubleshooting questions |
| Roadmap | Near-term, mid-term, and long-term project goals |
| Benchmark Suite | Full benchmark results and comparison with 11 other databases |
| Sample Datasets | Ready-to-run SQL scripts for testing |



