YugabyteDB Primer
YugabyteDB is a distributed SQL database that speaks PostgreSQL wire protocol while scaling horizontally across regions. This recipe walks through the mental model, a minimal cluster bootstrap, and the query patterns that keep latency predictable when nodes span continents. Treat it as the first stop before wiring Meridian workloads onto a YSQL backend.
1. The architecture in one breath
Yugabyte splits the stack into YQL (the query layer, either YSQL or YCQL) and DocDB (the sharded, Raft-replicated storage). Tablets are the unit of distribution; each tablet has a Raft group of three peers by default, and the tablet leader handles writes. Read replicas and follower reads let you trade staleness for proximity.
- YSQL reuses the upstream PostgreSQL parser and planner
- DocDB is a fork of RocksDB with MVCC, snapshot isolation, and Raft
- The yb-master quorum owns metadata; yb-tservers own tablets
2. Bootstrapping a local 3-node cluster
The fastest way to feel the moving parts is the yugabyted wrapper. It boots a master and tserver per node and exposes a 5433 YSQL port that any psql client can hit.
# node 1 (seed) yugabyted start --advertise_address=127.0.0.1 \ --base_dir=/tmp/yb-n1 # node 2 + 3 join the universe yugabyted start --advertise_address=127.0.0.2 \ --join=127.0.0.1 --base_dir=/tmp/yb-n2 yugabyted start --advertise_address=127.0.0.3 \ --join=127.0.0.1 --base_dir=/tmp/yb-n3 # connect with the standard postgres client ysqlsh -h 127.0.0.1 -p 5433 -U yugabyte
3. Query patterns that scale
The biggest delta from vanilla Postgres is that every table is sharded. Pick your primary key with hash vs range intent in mind, lean on tablespaces for geo-partitioning, and reach for follower reads when the workload tolerates bounded staleness. Avoid cross-tablet transactions on the hot path and let colocation handle small reference tables.