Last updated: 2026-10-27. Figures are generated by scripts/project_facts.py; maturity labels are in Maturity.

Project Summary

Orbit-RS is a distributed database that speaks several wire protocols over one durable, replicated store. Its goal is full compatibility with PostgreSQL 18, measured against the PostgreSQL 18 conformance corpus; each other protocol layer targets the latest version of the system it imitates (see the protocol table). Compatibility, maturity and performance are stated only as measured: a conformance pass rate with its date, a maturity label with its evidence, and benchmark results with their method. (ADR 0017)

Status

What exists for PostgreSQL: a durable RocksDB SQL engine replicated by Raft (ADR 0004), schemas (ADR 0003, 0012), and roles, ownership and privileges with SCRAM login (ADR 0013). Known gaps: pg_dump cannot read it, privileges on functions, types and columns, row-level security, and CONNECTION LIMIT.

Project Statistics

Counted by scripts/project_facts.py at commit 222ac1c2 on 2026-10-25:

• Test functions: 3,986
• Rust source: 457,233 non-blank lines
• PostgreSQL conformance floor: 768 of 816 records (94.1%)

Workspace Structure

orbit-rs/
├── orbit/server/          # Main server binary (orbit-server)
├── orbit/client/          # Client library (OrbitClient)
├── orbit/shared/          # Shared types, traits, clustering
├── orbit/engine/          # Storage engine (OrbitQL, adapters)
├── orbit/compute/         # Hardware acceleration (SIMD, GPU)
├── orbit/ml/              # Machine learning inference
├── orbit/proto/           # Protocol Buffer definitions
├── orbit/cli/             # Interactive CLI client
├── orbit/operator/        # Kubernetes operator
├── orbit/application/     # Application configuration
├── orbit/util/            # Core utilities
├── orbit/client-spring/   # Spring framework integration
├── orbit/server-etcd/     # etcd integration
└── orbit/server-prometheus/ # Prometheus metrics

Architecture Overview

Core Innovation: In-Process Communication

Recent refactoring eliminated gRPC overhead for local connections:

┌─────────────────────────────────────────────────────────┐
│                   OrbitServer                           │
│  ┌──────────────────────────────────────────────────┐   │
│  │         Protocol Handlers                        │   │
│  │  ┌──────┐  ┌────-──-┐  ┌──────┐  ┌──────┐        │   │
│  │  │Redis │  │Postgres│  │MySQL │  │ CQL  │        │   │
│  │  │:6379 │  │:5432   │  │:3306 │  │:9042 │        │   │
│  │  └───┬──┘  └───┬─--─┘  └───┬──┘  └───┬──┘        │   │
│  └──────┼─────────┼─────────--┼─────────┼───────────┘   │
│         │         │           │         │               │
│         └─────────┴─────--────┴─────────┘               │
│                     │                                   │
│         ┌───────────▼───────────┐                       │
│         │  OrbitClient (Local)  │                       │
│         │  In-Process Channels  │                       │
│         └───────────┬───────────┘                       │
│                     │                                   │
│         ┌───────────▼───────────┐                       │
│         │  ServerConnectionSvc  │                       │
│         │  Message Processing   │                       │
│         └───────────┬───────────┘                       │
│                     │                                   │
│         ┌───────────▼───────────┐                       │
│         │    Actor Registry     │                       │
│         │   Virtual Actors      │                       │
│         └───────────┬───────────┘                       │
│                     │                                   │
│         ┌───────────▼───────────┐                       │
│         │   RocksDB Storage     │                       │
│         │  Persistent LSM-Tree  │                       │
│         └───────────────────────┘                       │
└─────────────────────────────────────────────────────────┘

Protocol layers and targets

One table, kept in ADR 0006. Each layer is a separate compatibility layer with its own conformance corpus (ADR 0005).

The earlier “Complete” labels counted implemented commands, not measured compatibility; they are withdrawn (ADR 0002).

Performance

Not yet benchmarked. Earlier figures (message throughput, memory, binary size, cold start, P99 latency and comparisons with JVM systems) were removed because no benchmark backed them (ADR 0016). Unreleased measurements on debug builds exist but are not quotable.

Safety

• Rust ownership and borrowing for memory and thread safety; async runtime on tokio.
• The PostgreSQL listener refuses to start without users (ORBIT_PG_USERS) unless --dev-mode is set; the MySQL, CQL and Redis listeners take their credentials from the environment.

Testing

• Test functions: see Project Statistics above.
• PostgreSQL conformance: make conformance replays a corpus recorded from real PostgreSQL 18 over the wire, with a ratchet in tests/conformance/baseline.json; make conformance-reference checks that PostgreSQL 18 itself passes it.
• Replication: a three-node test kills the leader while roles and grants are in use (raft/sql_tests.rs).
• Tenant isolation on a cluster is tested for Symphony (see ADR 0009).

Storage

RocksDB is the default durable store for the SQL engine. Other backends (in-memory, LSM tree, COW B+tree, TiKV, memory-mapped, SQLite) and the hot/warm/cold tier design are Experimental; see Maturity.

Decisions and status

All architecture decisions are in docs/adr/. Proposed records (0015 to 0017) are drafts until the owner accepts them.