Skip to content
Navigation

Type at least two characters. Search covers page titles, headings, tags and database names.

↑ ↓ to navigateEnter to openEsc to close0 pages
Distributed SQLadvanced

YugabyteDB

Distributed SQL database reusing the PostgreSQL query layer over a Raft-replicated DocDB storage engine.

2 min readAdvancedUpdated Edit this page
YugabyteDB

What it is

A distributed SQL database whose YSQL interface reuses the actual PostgreSQL query layer — parser, planner and executor — on top of DocDB, a distributed document store built on a RocksDB-derived engine. The core is Apache-2.0.

Architecture

YB-TServer nodes store data as tablets, each a Raft group with three replicas by default. YB-Master nodes hold cluster metadata and are themselves Raft-replicated, off the data path. A YCQL interface provides a Cassandra-compatible API over the same storage.

Raft replication of a single rangeA client writes to the Raft leader, which appends the entry to its log and replicates it to two followers. Once a majority has persisted the entry it is committed and applied to the state machine, then acknowledged to the client.writeAppendEntriesAppendEntriescommit ackClientLeaderterm 7, log index 42Follower 1log index 42Follower 2log index 41
Raft replication of a single range

Best use cases

  • Transactional workloads outgrowing a single PostgreSQL node, where PostgreSQL feature fidelity matters.
  • Multi-region deployments requiring geo-partitioning for residency or latency.
  • Teams with deep PostgreSQL expertise who want to keep the query layer they know.

When not to use it

  • When a single PostgreSQL node with a replica suffices — which remains the common case.
  • When write latency budgets cannot absorb consensus round trips.
  • When you need a specific PostgreSQL extension or behaviour that depends on PostgreSQL's storage internals.

Data model

PostgreSQL SQL, with sharding expressed in the primary key: HASH for even distribution, ASC/DESC for range sharding with efficient range scans. Tables can be pre-split into tablets at creation.

Consistency and transactions

Distributed ACID transactions across tablets and regions. SERIALIZABLE, REPEATABLE READ (implemented as snapshot isolation) and READ COMMITTED are available. Conflicting transactions abort with SQLSTATE 40001 and must be retried. Follower reads with a configurable staleness bound are available per session.

Scaling model

Add tablet servers; tablets split and rebalance. Throughput scales with node count when the key distributes evenly across tablets.

Replication

Raft per tablet. Placement policy controls how replicas spread across cloud, region and zone. Read replica clusters add distant read capacity without joining the quorum, and xCluster provides asynchronous replication between separate clusters.

Backup and recovery

Distributed snapshots exported to object storage, plus snapshot schedules for point-in-time recovery. ysql_dump works for logical exports through the PostgreSQL interface.

Monitoring

Prometheus metrics from masters and tablet servers, plus master and tablet server web UIs. Watch under-replicated tablets, leader distribution, write latency, queued RPCs and clock skew.

Common mistakes

Production checklist

See YugabyteDB Production Checklist.