Ridge DB Architecture

Ridge is a bounded single-node database designed for deterministic ownership, recovery, and explicit limits. The same storage, schema, transaction, and SQL contracts are shared by the embedded API and pgwire service.

For the complete process and trust-boundary view, see the Ridge runtime architecture and its interactive Archify map.

Process models

Model Use
Embedded ridge library One seed process owns database access
ridged Loopback pgwire service for tools and application drivers
Ridge Admin Local browser UI whose seed backend owns pgwire and SSH

ridged is not intended to listen on a public interface. Reach a remote loopback service through verified SSH direct-tcpip.

Storage

Persistent recursive B+Trees store catalog, table, version-head, version, and index data. Generation-2 rows and schemas carry stable identifiers, type metadata, bounds, and checksums. General indexes use ordered composite keys; derived entries can be reconstructed from authoritative committed state.

Every configured bound is part of behavior. Oversized rows, messages, result sets, index keys, or unsupported structures return an explicit error rather than growing without limit.

Durability and recovery

Ridge uses a logical CRC-32 WAL. Commit persists the transaction before publication is acknowledged. Recovery:

  1. validates WAL framing, sequence, and checksums;
  2. ignores unpublished or uncommitted work;
  3. replays committed transactions idempotently;
  4. repairs a supported torn tail;
  5. reconstructs derived heads and indexes;
  6. rejects mid-log corruption.

This is a logical recovery contract, not PostgreSQL physical WAL compatibility.

MVCC and transactions

Ridge maintains persistent transaction and commit identifiers plus a visible commit watermark. Statement-refreshing read committed and pinned repeatable read snapshots use the same visibility rules for scans, keys, indexes, SQL, backup, and pgwire.

Disjoint writers can stage concurrently. Expected-head and unique-key validation produce deterministic conflicts when state overlaps. Atomic multi-table transactions provide read-your-writes and statement rollback. SELECT ... FOR UPDATE uses bounded nonblocking locking and returns SQLSTATE 55P03 on contention.

Vacuum and maintenance

Vacuum protects the oldest live snapshot, rewires retained version chains, and reuses bounded free pages. Online/incremental maintenance is limited to the documented Ridge operations. Do not edit storage files directly.

Specialized workloads

The v0.3 packages add canonical JSON, bounded analytics and windows, time-series storage, full-text search, and exact plus bounded-HNSW vector search. These are Ridge-native bounded implementations, not extension compatibility layers.

Evidence

The architecture is closed by crash, recovery, migration, differential, isolation, concurrency, backup, vacuum, and reopen gates. See grove/apps/ridge/V3_CONTRACT.md, CAPABILITIES.md, and the V3 test runners for normative detail.