Architecture
ormDB is a relational database engine written in Rust. It is not a wrapper around PostgreSQL or SQLite. This page explains how it works under the hood.
System Layers
ormDB is organized into five layers, each responsible for a distinct concern:
1. Storage Engine
Row-oriented storage built on sled (embedded key-value store). MVCC for transactional consistency with version keys encoded as (entity_id, version_ts) tuples. Secondary indexes for filters and joins. WAL for durability and replication.
2. Semantic Catalog
The catalog stores entity types, relations (with cardinality and edge semantics), constraints (uniqueness, checks, foreign keys), security policies (row-level and field-level), and versioned schema history. This is what makes ormDB "ORM-aware" — the database knows what your entities and relations mean.
3. Query Engine
The graph fetch compiler translates model-level queries into relational plans. A cost model considers filters, includes, and output shape. Plan cache keyed by query IR signature. Execution runtime handles join strategies, batching, and result assembly into entity/edge blocks.
4. Protocol
Zero-copy wire protocol based on rkyv serialization. Typed query IR + parameters in, structured entity blocks + edge blocks + metadata out. Change stream events carry entity/relation deltas with version tokens. Sub-microsecond deserialization.
5. Observability
Every query can be explained in terms of logical graph steps, chosen join/batch strategy, cost estimates, budget usage, and index usage. Structured audit logs at entity and field granularity.
Execution Modes
ormDB supports two execution modes:
- Graph Fetch Mode — Optimized for ORM workloads. Returns structured entity and edge blocks. Enforces fanout budgets and root-level pagination. This is the primary mode.
- Relational Mode — Flat, columnar results for analytical or reporting workloads. Uses the same catalog and policies. Limited in scope, not intended to replace OLAP systems.
Technology Stack
| Component | Technology | Why |
|---|---|---|
| Language | Rust (Edition 2021) | Memory safety, zero-cost abstractions, no GC |
| Storage | sled 0.34 | Pure Rust, embeddable, MVCC, crash recovery |
| Serialization | rkyv 0.8 | Zero-copy deserialization for large result sets |
| Allocator | mimalloc | High-performance, low fragmentation |
| Networking | async-nng | Req-rep, pub-sub, pipeline patterns; TCP + IPC |
| Async | tokio | Industry-standard async runtime |
Deployment Model
ormDB runs as a single-node server or embedded in your application process. Optional read replicas via WAL-based replication. Schema and policy metadata replicated as part of the catalog.
Learn More
For complete architecture documentation, see the architecture docs or browse the source code on GitHub.
Related Guides
- Graph Queries Explained — how graph fetches work at the query level
- Safe Database Migrations — the A-D grading system
- Real-Time Data with Change Streams — CDC and version tokens
- Performance Optimization — query budgets, fanout limits, tuning
- ormDB vs PostgreSQL — how the architecture compares