Runtime architecture
How the single-node EngineHost composes SQL, storage, WAL, PSI, telemetry, and transports in one process.
The current functional profile is a single nyxdb process. EngineHost owns
the catalog, SQL pipeline, local WAL, table shards, immutable parts, compaction,
PSI, transforms, and system-table snapshots. Raw TCP and WebSocket are transport
adapters over that same host; they do not contain alternate database logic.
TCP / WebSocket
|
v
EngineHost
|
+-- parse -> bind -> plan -> optimize -> execute
+-- catalog + local journal
+-- relation shards + committed tails
+-- local WAL + NYXP parts + compaction
+-- PSI event routing + streaming channels
+-- telemetry + system.* snapshotsOne process, process-local shards
SHARD BY ... SHARDS n partitions a table inside the process. A shard owns its
write state, committed tail, part set, index state, and publication work.
Sharding improves process-local parallelism and pruning; it does not distribute
data across nodes.
| Capability | Current status |
|---|---|
One all-in-one nyxdb process | Implemented |
| Per-table shards inside that process | Implemented |
| Separate query, storage, WAL, or controller services | Stub / Design-only |
| Cross-node replication | Stub |
| High availability and failover | Unsupported |
The experimental service binaries are development scaffolds. They are not alternate deployment profiles and must not appear in a production topology.
The SQL path
The query path is interface-first:
SQL text
-> ISqlParser
-> IQueryBinder
-> ILogicalPlanner
-> IQueryOptimizer
-> IQueryExecutorThe parser recognizes function-shaped syntax without owning the function catalog. The binder resolves names, types, active function versions, relation identity, and PSI routing. The planner and optimizer produce the executable operator tree, and the executor reads one coherent relation frontier.
The write path
A durable statement is validated and staged behind the target relation's publication fence. Its data records and commit manifest are appended to the local journal according to the selected storage policy. Only a successful commit is published to readers and PSI. A journal failure rolls the tentative store state and physical journal tail back before the statement returns an error.
After publication, background work seals committed-tail chunks into immutable NYXP parts, builds index regions, and compacts parts. Those operations are outside the client acknowledgement path.
Architecture invariants
PSI is a core engine primitive, not a memory-service implementation detail. Indexes, materialized views, transforms, schema/cache invalidation, streaming reads, and future subscribers use the shared PSI contract.
Routing and DAG edges match stream:key pairs, never stream names alone.
Transport code calls EngineHost. Durability claims are local unless a
capability explicitly says otherwise.
For implementation-level interfaces, see the generated API documentation instructions and the engine source map.