{"id":46681944,"url":"https://github.com/maxakbar/csharpdb","last_synced_at":"2026-05-10T04:27:35.344Z","repository":{"id":341308212,"uuid":"1169674356","full_name":"MaxAkbar/CSharpDB","owner":"MaxAkbar","description":"FAQ","archived":false,"fork":false,"pushed_at":"2026-04-23T02:24:47.000Z","size":8646,"stargazers_count":20,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-23T03:32:53.747Z","etag":null,"topics":["faq"],"latest_commit_sha":null,"homepage":"https://github.com/MaxAkbar/CSharpDB/blob/main/docs/faq.md","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MaxAkbar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-01T03:07:48.000Z","updated_at":"2026-04-23T02:24:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MaxAkbar/CSharpDB","commit_stats":null,"previous_names":["maxakbar/csharpdb"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/MaxAkbar/CSharpDB","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxAkbar%2FCSharpDB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxAkbar%2FCSharpDB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxAkbar%2FCSharpDB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxAkbar%2FCSharpDB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MaxAkbar","download_url":"https://codeload.github.com/MaxAkbar/CSharpDB/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MaxAkbar%2FCSharpDB/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32169657,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T02:19:40.750Z","status":"ssl_error","status_checked_at":"2026-04-23T02:17:55.737Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["faq"],"created_at":"2026-03-09T00:13:11.301Z","updated_at":"2026-05-10T04:27:35.338Z","avatar_url":"https://github.com/MaxAkbar.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/icon3.png\" alt=\"CSharpDB\" width=\"120\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eCSharpDB\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eThe embedded database engine built for .NET\u003c/strong\u003e\u003cbr\u003e\n  Zero dependencies. Full SQL. ACID storage. Single file. One NuGet package.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.nuget.org/packages/CSharpDB\"\u003e\u003cimg src=\"https://img.shields.io/nuget/v/CSharpDB\" alt=\"NuGet\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.nuget.org/packages/CSharpDB\"\u003e\u003cimg src=\"https://img.shields.io/nuget/dt/CSharpDB?label=Downloads\" alt=\"NuGet downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/MaxAkbar/CSharpDB/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/MaxAkbar/CSharpDB/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/MaxAkbar/CSharpDB/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/MaxAkbar/CSharpDB?label=Stars\" alt=\"GitHub stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://dotnet.microsoft.com/download/dotnet/10.0\"\u003e\u003cimg src=\"https://img.shields.io/badge/.NET-10-512bd4\" alt=\".NET 10\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/MaxAkbar/CSharpDB\"\u003e\u003cimg src=\"https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-0f766e\" alt=\"Platform: Windows, Linux, macOS\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/MaxAkbar/CSharpDB/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/MaxAkbar/CSharpDB?display_name=tag\u0026label=Release\" alt=\"Release\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://csharpdb.com/getting-started.html\"\u003eGetting Started\u003c/a\u003e \u0026middot;\n  \u003ca href=\"https://csharpdb.com/docs/index.html\"\u003eDocs\u003c/a\u003e \u0026middot;\n  \u003ca href=\"https://csharpdb.com/benchmarks.html\"\u003eBenchmarks\u003c/a\u003e \u0026middot;\n  \u003ca href=\"https://csharpdb.com/roadmap.html\"\u003eRoadmap\u003c/a\u003e \u0026middot;\n  \u003ca href=\"https://csharpdb.com\"\u003eWebsite\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Performance at a Glance\n\n| 1.99M gets/sec | 9.68M COUNTs/sec | 799.29K rows/sec | 890 commits/sec |\n|:-:|:-:|:-:|:-:|\n| Collection point reads | Concurrent reader burst (8x reused) | Durable `InsertBatch` B10000 | Concurrent durable writes |\n\n\u003csub\u003eIntel 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 \u003ca href=\"tests/CSharpDB.Benchmarks/README.md\"\u003ebenchmark suite\u003c/a\u003e.\u003c/sub\u003e\n\n---\n\n## Durable API Top Lines\n\nDefault 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.\n\n| Surface | Single write | Batch x100 | Point read | Concurrent read |\n|---|---:|---:|---:|---:|\n| SQL file-backed | 267.1 ops/sec | 25.56K rows/sec | 1.48M ops/sec | 9.68M COUNTs/sec |\n| SQL hybrid incremental-durable | 276.1 ops/sec | 26.55K rows/sec | 1.47M ops/sec | 10.04M COUNTs/sec |\n| SQL in-memory | 259.48K ops/sec | 934.22K rows/sec | 1.49M ops/sec | 10.26M COUNTs/sec |\n| Collection file-backed | 265.7 ops/sec | 24.53K docs/sec | 1.99M ops/sec | - |\n| Collection hybrid incremental-durable | 276.9 ops/sec | 25.75K docs/sec | 2.02M ops/sec | - |\n| Collection in-memory | 262.14K ops/sec | 969.55K docs/sec | 2.02M ops/sec | - |\n\n\u003csub\u003eSource: `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 \u003ca href=\"tests/CSharpDB.Benchmarks/README.md\"\u003ebenchmark suite README\u003c/a\u003e.\u003c/sub\u003e\n\n---\n\n## Concurrent Durable Writes\n\nThe 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.\n\n| Workload | Writers | Commit window | Durable Commits/sec | Commits/flush | Notes |\n|----------|--------:|--------------:|--------------------:|--------------:|-------|\n| Shared auto-commit `INSERT` | 4 | `0` | 247.0 | 1.00 | One durable flush per commit |\n| Shared auto-commit `INSERT` | 4 | `250us` | 463.4 | 1.99 | Group commit roughly doubles throughput |\n| Shared auto-commit `INSERT` | 8 | `0` | 239.2 | 1.00 | Still flush-bound with no commit window |\n| Shared auto-commit `INSERT` | 8 | `250us` | 890.1 | 3.94 | Current release-core headline row |\n\nFocused hot insert fan-in diagnostics cover the newer right-edge and auto-ID shapes that are not part of the release-core scorecard yet:\n\n| Insert shape | Writers/window | Durable Commits/sec | Commits/flush |\n|---|---:|---:|---:|\n| Serialized explicit hot right-edge | `W8 + 250us` | 278.4 | 1.00 |\n| Concurrent explicit hot right-edge | `W8 + 250us` | 910.3 | 3.33 |\n| Concurrent auto-ID hot right-edge | `W8 + 250us` | 913.1 | 3.34 |\n| Concurrent explicit disjoint ranges | `W8 + 250us` | 1,049.6 | 3.96 |\n\n\u003csub\u003eSources: 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 \u003ca href=\"tests/CSharpDB.Benchmarks/README.md\"\u003ebenchmark suite README\u003c/a\u003e.\u003c/sub\u003e\n\n---\n\n## Local SQLite Reference\n\nSame-runner SQLite rows use Microsoft.Data.Sqlite 10.0.7 with WAL + `synchronous=FULL`. They are comparison points, not universal claims.\n\n| Workload | CSharpDB | SQLite WAL+FULL |\n|---|---:|---:|\n| Durable prepared bulk insert B1000 | 211.99K rows/sec | 155.66K rows/sec |\n| SQL point lookup | 1.48M ops/sec | 93.91K ops/sec |\n\n\u003csub\u003eSource: `sqlite-compare-20260506-035128-median-of-3.csv` from the May 6, 2026 release-core snapshot.\u003c/sub\u003e\n\n---\n\n## Generated Collection Fast Path\n\nThe source-generated collection path is opt-in through `GetGeneratedCollectionAsync\u003cT\u003e(...)`. It mainly improves collection payload CPU, direct field extraction, and index-reader paths; one-row durable writes can still be WAL-flush-bound.\n\n| Path | Source-gen JSON | Generated binary | Gain | Allocation |\n|---|---:|---:|---:|---|\n| Encode payload | 600.1 ns | 306.2 ns | 1.96x | 552 B to 136 B |\n| Decode payload | 2,277.9 ns | 371.9 ns | 6.12x | 1,240 B to 480 B |\n| Indexed int field read | 187.23 ns | 29.74 ns | 6.30x | 0 B to 0 B |\n| Text field UTF-8 read | 185.82 ns | 27.26 ns | 6.82x | 56 B to 0 B |\n| Key match | 21.48 ns | 19.91 ns | 1.08x | 0 B to 0 B |\n\n\u003csub\u003eSource: `BenchmarkDotNet.Artifacts/results/CSharpDB.Benchmarks.Micro.GeneratedCollection*Benchmarks-report.csv`. These rows are diagnostic microbenchmarks, not release-core scorecard rows.\u003c/sub\u003e\n\n---\n\n## Quick Start\n\n```bash\ndotnet add package CSharpDB\n```\n\n```csharp\nusing CSharpDB.Engine;\n\n// If the file exists, delete it to start fresh\nif (File.Exists(\"mydata.db\"))\n    File.Delete(\"mydata.db\");\n\nawait using var db = await Database.OpenAsync(\"mydata.db\");\n\nawait db.ExecuteAsync(\"CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)\");\nawait db.ExecuteAsync(\"INSERT INTO users VALUES (1, 'Alice', 30)\");\n\nawait using var result = await db.ExecuteAsync(\"SELECT * FROM users WHERE age \u003e 26\");\nawait foreach (var row in result.GetRowsAsync())\n    Console.WriteLine($\"{row[0].AsInteger}: {row[1].AsText}, age {row[2].AsInteger}\");\n```\n\n---\n\n## Why CSharpDB?\n\n- **No moving parts** — single `.db` file, no server process, no native binaries, no external dependencies\n- **SQL + NoSQL in one engine** — full SQL with JOINs, CTEs, subqueries, views, and triggers *plus* a typed `Collection\u003cT\u003e` API that bypasses SQL entirely for sub-microsecond reads\n- **ACID by default** — WAL-based crash recovery with fsync-on-commit and concurrent snapshot-isolated readers\n- **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\n- **Use from any language** — NativeAOT compiles to a standalone C library; call from Python, Node.js, Go, Rust, Swift, Kotlin, Dart, Android, and iOS\n\n---\n\n## Admin UI\n\n| Querying | Table Data | Schema |\n|:-:|:-:|:-:|\n| ![Query tab](docs/images/QuerySytemTable.png) | ![Data browser](docs/images/TableDetails.png) | ![Schema view](docs/images/TableSchema.png) |\n\nBlazor 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.\n\n---\n\n## Ecosystem\n\nCSharpDB 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.\n\n| Surface | Primary use | Highlights |\n|---|---|---|\n| **Engine API** | Embedded in-process access | Direct async SQL, transactions, views, triggers, procedures, and query stats |\n| **Collection API** | Typed document and key-value access | `Collection\u003cT\u003e`, nested path indexes, point reads, scans, and path/range queries |\n| **ADO.NET Provider** | Standard .NET data access | `DbConnection`, `DbCommand`, `DbDataReader`, and `DbTransaction` support |\n| **Client SDK** | One C# API across transports | Direct, HTTP, and gRPC transports plus maintenance and diagnostics |\n| **REST API** | HTTP integration and automation | 30+ endpoints with OpenAPI and Scalar for SQL, schema, data, collections, and maintenance |\n| **gRPC Daemon** | Long-running remote host | Strongly typed RPC surface for SQL, schema, procedures, collections, and maintenance |\n| **CLI REPL** | Terminal-first workflows | Interactive SQL shell, schema inspection, backup/restore, and migration commands |\n| **MCP Server** | AI assistant integration | Tool-based schema inspection, query execution, and row operations for MCP-compatible clients |\n| **Admin UI** | Browser-based database studio | Query editor, visual query designer, CRUD, schema editing, procedures, and storage diagnostics |\n| **Forms + Reports** | Internal app workflows and printable output | Database-backed forms designer/runtime plus banded reports with grouping, expressions, preview, and print |\n| **Pipelines** | ETL and automation | Package-based runtime, visual pipeline designer, transforms, dry-run, checkpoints, and run history |\n| **VS Code Extension** | IDE integration | Schema explorer, `.csql` support, query results, CRUD, and storage diagnostics |\n| **Native FFI** | Polyglot embedding | NativeAOT C library for Python, Go, Rust, Swift, Kotlin, Dart, Android, and iOS |\n| **Node.js Package** | JavaScript and TypeScript access | Local embedded wrapper over the native library for Node.js apps and tooling |\n\n---\n\n## Use from Any Language\n\n**Node.js:**\n```javascript\nimport { Database } from 'csharpdb';\n\nconst db = new Database('mydata.db');\ndb.execute(\"INSERT INTO demo VALUES (1, 'Alice')\");\nfor (const row of db.query('SELECT * FROM demo')) console.log(row);\ndb.close();\n```\n\n**Python:**\n```python\nfrom csharpdb import Database\n\nwith Database(\"mydata.db\") as db:\n    db.execute(\"INSERT INTO demo VALUES (1, 'Alice')\")\n    for row in db.query(\"SELECT * FROM demo\"):\n        print(row)\n```\n\nThe 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.\n\n---\n\n## How CSharpDB Compares\n\n| Feature | CSharpDB | SQLite | LiteDB | RocksDB |\n|---------|:--------:|:------:|:------:|:-------:|\n| Pure .NET / no native binaries | ✅ | ❌ | ✅ | ❌ |\n| Full SQL (JOINs, CTEs, subqueries) | ✅ | ✅ | ❌ | ❌ |\n| NoSQL Collection API | ✅ | ❌ | ✅ | ❌ |\n| ACID transactions | ✅ | ✅ | ✅ | ✅ |\n| REST API / gRPC | ✅ | ❌ | ❌ | ❌ |\n| Admin UI | ✅ | ❌ | ❌ | ❌ |\n| MCP server (AI agents) | ✅ | ❌ | ❌ | ❌ |\n| VS Code extension | ✅ | ❌ | ❌ | ❌ |\n| Multi-language SDKs | ✅ | ✅ | ❌ | ✅ |\n| Mature ecosystem / battle-tested | ❌ | ✅ | ✅ | ✅ |\n\n---\n\n## Architecture\n\n```\n  SQL string              Collection\u003cT\u003e API\n      |                        |\n  [Tokenizer]            [JSON serialize]\n      |                        |\n  [Parser -\u003e AST]         (bypassed)\n      |                        |\n  [Query Planner]              |\n      |                        |\n  [Operator Tree]              |\n      |                        |\n  [B+Tree]  ---------------  [B+Tree]\n      |\n  [Pager + WAL]              (page cache, write-ahead log)\n      |\n  [File I/O]                 (4 KB pages, slotted layout)\n      |\n  mydata.db + mydata.db.wal\n```\n\n---\n\n## Documentation\n\n| | |\n|---|---|\n| [Getting Started](https://csharpdb.com/docs/getting-started.html) | Step-by-step walkthrough |\n| [Architecture Guide](https://csharpdb.com/architecture.html) | Engine design deep dive |\n| [Tools \u0026 Ecosystem](https://csharpdb.com/docs/ecosystem.html) | APIs, hosts, designers, and integrations |\n| [EF Core Provider](https://csharpdb.com/docs/entity-framework-core.html) | Embedded EF Core 10 provider guide |\n| [Trusted C# Callbacks](docs/trusted-csharp-functions/README.md) | Register in-process C# functions, commands, and validation rules for SQL, forms, reports, and pipelines |\n| [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 |\n| [Admin UI Guide](https://csharpdb.com/docs/admin-ui.html) | Querying, schema, pipelines, forms, reports, and storage |\n| [CSharpDB.Client](src/CSharpDB.Client/README.md) | Unified client API and transports |\n| [Pipelines](https://csharpdb.com/docs/pipelines.html) | ETL package model and visual designer |\n| [Reports](https://csharpdb.com/docs/reports.html) | Visual banded report designer and preview |\n| [Native FFI](https://csharpdb.com/docs/tutorials/native-ffi.html) | C library API and cross-language examples |\n| [REST API Reference](https://csharpdb.com/docs/rest-api.html) | HTTP API, schema/data CRUD, and maintenance |\n| [MCP Server](https://csharpdb.com/docs/mcp-server.html) | AI assistant integration |\n| [CLI Reference](https://csharpdb.com/docs/cli.html) | REPL commands |\n| [VS Code Extension](vscode-extension/README.md) | Local NativeAOT-backed extension |\n| [Benchmark Suite](tests/CSharpDB.Benchmarks/README.md) | Full results and comparisons |\n| [CSharpDB and SharpCoreDB](docs/comparisons/sharpcoredb.md) | Evidence-based comparison and fit guidance |\n| [SQL Reference](https://csharpdb.com/docs/sql.html) | Supported SQL syntax |\n| [Internals \u0026 Contributing](https://csharpdb.com/docs/internals.html) | Project structure and concurrency model |\n| [FAQ](https://csharpdb.com/docs/faq.html) | Common questions |\n| [Roadmap](https://csharpdb.com/roadmap.html) | Project goals |\n\n---\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxakbar%2Fcsharpdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxakbar%2Fcsharpdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxakbar%2Fcsharpdb/lists"}