🖥️ BLite.Server
BLite.Server turns the embedded BLite engine into a network-accessible database with gRPC, a REST API, user authentication, multi-tenancy, and an integrated Blazor Web Studio — all shipping as a single .exe or Docker image.
What is BLite.Server?
BLite is an embedded NoSQL database — it runs inside your .NET process with no external dependencies. BLite.Server wraps that same engine and exposes it as a standalone service that multiple clients can connect to simultaneously.
- gRPC endpoint — high-throughput, binary protocol on port
2626 - REST API — JSON over HTTP on port
2627with OpenAPI / Swagger UI - Blazor Web Studio — browser-based management UI on port
2628 - Multi-tenancy — isolated databases per user or namespace
- API-key auth — fine-grained per-collection permissions
- BLQL — full MQL-style query language available over both gRPC and REST
- Transactions — cross-collection ACID transactions over the network
Architecture
A single ASP.NET Core 10 host serves all three endpoints and delegates every operation to the embedded engine:
┌──────────────────────────────────────────────────────┐
│ BLite.Server │
│ │
│ ┌──────────┐ ┌─────────────────┐ ┌──────────┐ │
│ │ gRPC │ │ REST /api/v1 │ │ Studio │ │
│ │ :2626 │ │ :2627 │ │ :2628 │ │
│ └────┬─────┘ └─────────┬───────┘ └────┬─────┘ │
│ │ │ │ │
│ └──────────┬────────┘ │ │
│ ▼ │ │
│ ┌────────────────┐ │ │
│ │ EngineRegistry │◄────────────────┘ │
│ │ (singleton) │ │
│ └───────┬────────┘ │
│ │ one BLiteEngine per database │
│ ▼ │
│ ┌────────────────┐ │
│ │ BLiteEngine │ (embedded BLite core) │
│ └────────────────┘ │
└──────────────────────────────────────────────────────┘
Endpoints at a Glance
| Endpoint | Default Port | Protocol | Description |
|---|---|---|---|
| gRPC | 2626 | HTTP/2 | Binary, streaming, high-throughput. Primary interface for the official client SDKs. |
| REST API | 2627 | HTTP/1.1 + HTTP/2 | JSON over HTTP. Full CRUD + BLQL queries. Includes Swagger UI at /swagger. |
| Studio | 2628 | HTTP/1.1 + HTTP/2 | Blazor Server web application. Management UI for databases, collections, users. |
Key Concepts
Databases & Collections
Each database maps to a separate .db file managed by its own BLiteEngine instance. Collections are created on demand. The system database (key "") hosts the _users collection.
Namespaces
Users with a Namespace field work inside a transparent prefix: logical name "orders" is stored as "tenant1:orders". This enables multiple tenants to share a single database engine without data leakage.
API Keys
Every request must carry an API key via the x-api-key header or Authorization: Bearer <key>. Keys are stored as SHA-256 hex hashes — the plaintext is returned exactly once at creation time.
Dev Mode
When no users exist yet (fresh install, before running /setup), the server operates in Dev Mode: all requests are authenticated as a synthetic root user with full permissions. This makes local development frictionless while remaining safe by default in production (setup creates the first real user).