https://github.com/maxakbar/csharpdb

FAQ
https://github.com/maxakbar/csharpdb
faq
Last synced: about 1 month ago
JSON representation
FAQ
Host: GitHub
URL: https://github.com/maxakbar/csharpdb
Owner: MaxAkbar
License: mit
Created: 2026-03-01T03:07:48.000Z (3 months ago)
Default Branch: main
Last Pushed: 2026-04-23T02:24:47.000Z (about 2 months ago)
Last Synced: 2026-04-23T03:32:53.747Z (about 2 months ago)
Topics: faq
Language: C#
Homepage: https://github.com/MaxAkbar/CSharpDB/blob/main/docs/faq.md
Size: 8.25 MB
Stars: 20
Watchers: 0
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Roadmap: docs/roadmap.md
Awesome Lists containing this project

README

          


  



CSharpDB




  The embedded database engine built for .NET


  Zero dependencies. Full SQL. ACID storage. Single file. One NuGet package.





  

  

  

  

  

  

  

  





  Getting Started ·

  Docs ·

  Benchmarks ·

  Roadmap ·

  Website



---

## Performance at a Glance

| 1.99M gets/sec | 9.68M COUNTs/sec | 799.29K rows/sec | 890 commits/sec |

|:-:|:-:|:-:|:-:|

| Collection point reads | Concurrent reader burst (8x reused) | Durable `InsertBatch` B10000 | Concurrent durable writes |

_{Intel i9-11900K, 16 logical cores, Windows 10.0.26300, .NET SDK 10.0.203, .NET runtime 10.0.7. Snapshot promoted from the May 6, 2026 release-core suite; latest release guardrail compare passed May 6, 2026 with PASS=187, WARN=0, SKIP=0, FAIL=0. Full results live in the benchmark suite.}

---

## Durable API Top Lines

Default CSharpDB file-backed benchmarks are fully durable: WAL fsync-on-commit unless a row explicitly says otherwise. In-memory rows show the same API paths without disk durability.

| Surface | Single write | Batch x100 | Point read | Concurrent read |

|---|---:|---:|---:|---:|

| SQL file-backed | 267.1 ops/sec | 25.56K rows/sec | 1.48M ops/sec | 9.68M COUNTs/sec |

| SQL hybrid incremental-durable | 276.1 ops/sec | 26.55K rows/sec | 1.47M ops/sec | 10.04M COUNTs/sec |

| SQL in-memory | 259.48K ops/sec | 934.22K rows/sec | 1.49M ops/sec | 10.26M COUNTs/sec |

| Collection file-backed | 265.7 ops/sec | 24.53K docs/sec | 1.99M ops/sec | - |

| Collection hybrid incremental-durable | 276.9 ops/sec | 25.75K docs/sec | 2.02M ops/sec | - |

| Collection in-memory | 262.14K ops/sec | 969.55K docs/sec | 2.02M ops/sec | - |

_{Source: `master-table-20260506-024609-median-of-3.csv` from the May 6, 2026 release-core snapshot. Full methodology and storage-mode detail live in the benchmark suite README.}

---

## Concurrent Durable Writes

The current release-core concurrent write rows measure the intended shared-insert shape: one shared `Database`, disjoint explicit key ranges, auto-commit SQL inserts, and `ConcurrentWriteTransactions` enabled. The numbers below are total durable commits/sec across all writers combined.

| Workload | Writers | Commit window | Durable Commits/sec | Commits/flush | Notes |

|----------|--------:|--------------:|--------------------:|--------------:|-------|

| Shared auto-commit `INSERT` | 4 | `0` | 247.0 | 1.00 | One durable flush per commit |

| Shared auto-commit `INSERT` | 4 | `250us` | 463.4 | 1.99 | Group commit roughly doubles throughput |

| Shared auto-commit `INSERT` | 8 | `0` | 239.2 | 1.00 | Still flush-bound with no commit window |

| Shared auto-commit `INSERT` | 8 | `250us` | 890.1 | 3.94 | Current release-core headline row |

Focused hot insert fan-in diagnostics cover the newer right-edge and auto-ID shapes that are not part of the release-core scorecard yet:

| Insert shape | Writers/window | Durable Commits/sec | Commits/flush |

|---|---:|---:|---:|

| Serialized explicit hot right-edge | `W8 + 250us` | 278.4 | 1.00 |

| Concurrent explicit hot right-edge | `W8 + 250us` | 910.3 | 3.33 |

| Concurrent auto-ID hot right-edge | `W8 + 250us` | 913.1 | 3.34 |

| Concurrent explicit disjoint ranges | `W8 + 250us` | 1,049.6 | 3.96 |

_{Sources: release-core `concurrent-write-diagnostics-20260506-032735-median-of-3.csv`; focused insert fan-in diagnostic `insert-fan-in-diagnostics-20260505-233424.csv`. Focused rows remain diagnostic until the release-core suite includes those shapes directly. Full methodology and tuning notes live in the benchmark suite README.}

---

## Local SQLite Reference

Same-runner SQLite rows use Microsoft.Data.Sqlite 10.0.7 with WAL + `synchronous=FULL`. They are comparison points, not universal claims.

| Workload | CSharpDB | SQLite WAL+FULL |

|---|---:|---:|

| Durable prepared bulk insert B1000 | 211.99K rows/sec | 155.66K rows/sec |

| SQL point lookup | 1.48M ops/sec | 93.91K ops/sec |

_{Source: `sqlite-compare-20260506-035128-median-of-3.csv` from the May 6, 2026 release-core snapshot.}

---

## Generated Collection Fast Path

The source-generated collection path is opt-in through `GetGeneratedCollectionAsync(...)`. It mainly improves collection payload CPU, direct field extraction, and index-reader paths; one-row durable writes can still be WAL-flush-bound.

| Path | Source-gen JSON | Generated binary | Gain | Allocation |

|---|---:|---:|---:|---|

| Encode payload | 600.1 ns | 306.2 ns | 1.96x | 552 B to 136 B |

| Decode payload | 2,277.9 ns | 371.9 ns | 6.12x | 1,240 B to 480 B |

| Indexed int field read | 187.23 ns | 29.74 ns | 6.30x | 0 B to 0 B |

| Text field UTF-8 read | 185.82 ns | 27.26 ns | 6.82x | 56 B to 0 B |

| Key match | 21.48 ns | 19.91 ns | 1.08x | 0 B to 0 B |

_{Source: `BenchmarkDotNet.Artifacts/results/CSharpDB.Benchmarks.Micro.GeneratedCollection*Benchmarks-report.csv`. These rows are diagnostic microbenchmarks, not release-core scorecard rows.}

---

## Quick Start

```bash

dotnet add package CSharpDB

```

```csharp

using CSharpDB.Engine;

// If the file exists, delete it to start fresh

if (File.Exists("mydata.db"))

    File.Delete("mydata.db");

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 using var result = await db.ExecuteAsync("SELECT * FROM users WHERE age > 26");

await foreach (var row in result.GetRowsAsync())

    Console.WriteLine($"{row[0].AsInteger}: {row[1].AsText}, age {row[2].AsInteger}");

```

---

## Why CSharpDB?

- **No moving parts** — single `.db` file, no server process, no native binaries, no external dependencies

- **SQL + NoSQL in one engine** — full SQL with JOINs, CTEs, subqueries, views, and triggers *plus* a typed `Collection` API that bypasses SQL entirely for sub-microsecond reads

- **ACID by default** — WAL-based crash recovery with fsync-on-commit and concurrent snapshot-isolated readers

- **Ships with tooling** — Admin UI, VS Code extension, CLI REPL, REST API, gRPC daemon, pipeline tooling, integrated forms and reports designers, and MCP server for AI agents

- **Use from any language** — NativeAOT compiles to a standalone C library; call from Python, Node.js, Go, Rust, Swift, Kotlin, Dart, Android, and iOS

---

## Admin UI

| Querying | Table Data | Schema |

|:-:|:-:|:-:|

| ![Query tab](docs/images/QuerySytemTable.png) | ![Data browser](docs/images/TableDetails.png) | ![Schema view](docs/images/TableSchema.png) |

Blazor Server dashboard with query execution, visual [Query Designer](https://csharpdb.com/docs/admin-ui.html#query-editor), data browser CRUD, schema editing, stored procedures, visual pipeline design, integrated forms and reports designers, backup and maintenance flows, and storage diagnostics.

---

## Ecosystem

CSharpDB is more than an embedded SQL engine. The same database can be used through in-process APIs, remote service hosts, AI tooling, visual designers, and cross-language bindings.

| Surface | Primary use | Highlights |

|---|---|---|

| **Engine API** | Embedded in-process access | Direct async SQL, transactions, views, triggers, procedures, and query stats |

| **Collection API** | Typed document and key-value access | `Collection`, nested path indexes, point reads, scans, and path/range queries |

| **ADO.NET Provider** | Standard .NET data access | `DbConnection`, `DbCommand`, `DbDataReader`, and `DbTransaction` support |

| **Client SDK** | One C# API across transports | Direct, HTTP, and gRPC transports plus maintenance and diagnostics |

| **REST API** | HTTP integration and automation | 30+ endpoints with OpenAPI and Scalar for SQL, schema, data, collections, and maintenance |

| **gRPC Daemon** | Long-running remote host | Strongly typed RPC surface for SQL, schema, procedures, collections, and maintenance |

| **CLI REPL** | Terminal-first workflows | Interactive SQL shell, schema inspection, backup/restore, and migration commands |

| **MCP Server** | AI assistant integration | Tool-based schema inspection, query execution, and row operations for MCP-compatible clients |

| **Admin UI** | Browser-based database studio | Query editor, visual query designer, CRUD, schema editing, procedures, and storage diagnostics |

| **Forms + Reports** | Internal app workflows and printable output | Database-backed forms designer/runtime plus banded reports with grouping, expressions, preview, and print |

| **Pipelines** | ETL and automation | Package-based runtime, visual pipeline designer, transforms, dry-run, checkpoints, and run history |

| **VS Code Extension** | IDE integration | Schema explorer, `.csql` support, query results, CRUD, and storage diagnostics |

| **Native FFI** | Polyglot embedding | NativeAOT C library for Python, Go, Rust, Swift, Kotlin, Dart, Android, and iOS |

| **Node.js Package** | JavaScript and TypeScript access | Local embedded wrapper over the native library for Node.js apps and tooling |

---

## Use from Any Language

**Node.js:**

```javascript

import { Database } from 'csharpdb';

const db = new Database('mydata.db');

db.execute("INSERT INTO demo VALUES (1, 'Alice')");

for (const row of db.query('SELECT * FROM demo')) console.log(row);

db.close();

```

**Python:**

```python

from csharpdb import Database

with Database("mydata.db") as db:

    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. See the [Native Library Reference](https://csharpdb.com/docs/tutorials/native-ffi.html) for Go, Rust, Swift, Kotlin, Dart, Android, and iOS examples.

---

## How CSharpDB Compares

| Feature | CSharpDB | SQLite | LiteDB | RocksDB |

|---------|:--------:|:------:|:------:|:-------:|

| Pure .NET / no native binaries | ✅ | ❌ | ✅ | ❌ |

| Full SQL (JOINs, CTEs, subqueries) | ✅ | ✅ | ❌ | ❌ |

| NoSQL Collection API | ✅ | ❌ | ✅ | ❌ |

| ACID transactions | ✅ | ✅ | ✅ | ✅ |

| REST API / gRPC | ✅ | ❌ | ❌ | ❌ |

| Admin UI | ✅ | ❌ | ❌ | ❌ |

| MCP server (AI agents) | ✅ | ❌ | ❌ | ❌ |

| VS Code extension | ✅ | ❌ | ❌ | ❌ |

| Multi-language SDKs | ✅ | ✅ | ❌ | ✅ |

| Mature ecosystem / battle-tested | ❌ | ✅ | ✅ | ✅ |

---

## Architecture

```

  SQL string              Collection API

      |                        |

  [Tokenizer]            [JSON serialize]

      |                        |

  [Parser -> AST]         (bypassed)

      |                        |

  [Query Planner]              |

      |                        |

  [Operator Tree]              |

      |                        |

  [B+Tree]  ---------------  [B+Tree]

      |

  [Pager + WAL]              (page cache, write-ahead log)

      |

  [File I/O]                 (4 KB pages, slotted layout)

      |

  mydata.db + mydata.db.wal

```

---

## Documentation

| | |

|---|---|

| [Getting Started](https://csharpdb.com/docs/getting-started.html) | Step-by-step walkthrough |

| [Architecture Guide](https://csharpdb.com/architecture.html) | Engine design deep dive |

| [Tools & Ecosystem](https://csharpdb.com/docs/ecosystem.html) | APIs, hosts, designers, and integrations |

| [EF Core Provider](https://csharpdb.com/docs/entity-framework-core.html) | Embedded EF Core 10 provider guide |

| [Trusted C# Callbacks](docs/trusted-csharp-functions/README.md) | Register in-process C# functions, commands, and validation rules for SQL, forms, reports, and pipelines |

| [Trusted C# Host Sample](samples/trusted-csharp-host/README.md) | VS Code-ready C# host project for trusted functions, commands, validation rules, and form actions |

| [Admin UI Guide](https://csharpdb.com/docs/admin-ui.html) | Querying, schema, pipelines, forms, reports, and storage |

| [CSharpDB.Client](src/CSharpDB.Client/README.md) | Unified client API and transports |

| [Pipelines](https://csharpdb.com/docs/pipelines.html) | ETL package model and visual designer |

| [Reports](https://csharpdb.com/docs/reports.html) | Visual banded report designer and preview |

| [Native FFI](https://csharpdb.com/docs/tutorials/native-ffi.html) | C library API and cross-language examples |

| [REST API Reference](https://csharpdb.com/docs/rest-api.html) | HTTP API, schema/data CRUD, and maintenance |

| [MCP Server](https://csharpdb.com/docs/mcp-server.html) | AI assistant integration |

| [CLI Reference](https://csharpdb.com/docs/cli.html) | REPL commands |

| [VS Code Extension](vscode-extension/README.md) | Local NativeAOT-backed extension |

| [Benchmark Suite](tests/CSharpDB.Benchmarks/README.md) | Full results and comparisons |

| [CSharpDB and SharpCoreDB](docs/comparisons/sharpcoredb.md) | Evidence-based comparison and fit guidance |

| [SQL Reference](https://csharpdb.com/docs/sql.html) | Supported SQL syntax |

| [Internals & Contributing](https://csharpdb.com/docs/internals.html) | Project structure and concurrency model |

| [FAQ](https://csharpdb.com/docs/faq.html) | Common questions |

| [Roadmap](https://csharpdb.com/roadmap.html) | Project goals |

---

## License

[MIT](LICENSE)
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/maxakbar/csharpdb

Awesome Lists containing this project

README

CSharpDB
