YugabyteDB Architecture

YugabyteDB runs the actual PostgreSQL query layer on top of DocDB, a distributed document store built on a RocksDB-derived engine with Raft replication.

Components

• YB-TServer — stores and serves data. Hosts tablets and runs the query layer processes.
• YB-Master — holds cluster metadata: table definitions, tablet locations, placement policy. Replicated by Raft; it is not on the data path.
• YSQL — the PostgreSQL-compatible API, reusing PostgreSQL's parser, planner and executor.
• YCQL — a Cassandra-compatible API over the same storage.

Tablets

A table is split into tablets, each a Raft group with (by default) three replicas. One replica is the tablet leader and handles writes and consistent reads.

Splitting can be automatic as data grows, or pre-configured at creation:

-- Pre-split a hash-sharded table into 24 tablets.
CREATE TABLE events (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL,
    created_at TIMESTAMPTZ NOT NULL
) SPLIT INTO 24 TABLETS;
 
-- Range sharding with explicit split points.
CREATE TABLE readings (
    device_id UUID,
    ts TIMESTAMPTZ,
    value DOUBLE PRECISION,
    PRIMARY KEY (device_id ASC, ts ASC)
) SPLIT AT VALUES (('00000000-…'), ('40000000-…'), ('80000000-…'));

HASH sharding (the default for the first primary key column) distributes evenly; ASC/DESC gives range sharding, which supports efficient range scans and requires attention to hotspots.

PostgreSQL compatibility

Reusing the PostgreSQL query layer means high fidelity for SQL features, data types, and many extensions — a meaningful difference from engines that reimplement the wire protocol.

Read paths

• Leader reads — strongly consistent, served by the tablet leader.
• Follower reads — served by any replica with a bounded staleness, avoiding a cross-region hop.

SET yb_read_from_followers = true;
SET yb_follower_read_staleness_ms = 30000;

Hotspots

Clocks

YugabyteDB uses hybrid logical clocks and assumes bounded skew (max_clock_skew_usec). Run NTP or chrony on every node and alert on offset; the failure mode of large skew is a correctness concern, not merely a performance one.