YugabyteDB — Getting Started

A self-paced learning project to understand YugabyteDB end-to-end: what it is, how it works internally, and how to build against it.

YugabyteDB is a distributed SQL database that combines PostgreSQL-compatible APIs with the horizontal scalability and resilience of NoSQL systems like Cassandra and Google Spanner.

Learning Roadmap

Work through these in order. Each phase has reading material in docs/ and hands-on exercises in exercises/.

Phase 1 — Foundations

• What is YugabyteDB? — distributed SQL, history, when to use it
• Architecture overview — YB-TServer, YB-Master, DocDB, Raft

Phase 2 — APIs

• YSQL vs YCQL — the two query layers and when to choose each
• Exercises: YSQL basics and YCQL basics

Phase 3 — Internals

• Sharding and replication — tablets, leader/follower, Raft groups
• Distributed transactions — hybrid logical clocks, isolation levels

Phase 4 — Operations

• Performance & tuning — tablet splitting, colocation, indexes
• Setup guide — Docker, native install, multi-node clusters

Phase 5 — Application

• Sample app — a Node.js + Fastify service that uses YSQL for an order-management workflow

Quick start

# Spin up a single-node YugabyteDB locally with Docker
cd setup && docker compose up -d

# Connect via ysqlsh (PostgreSQL-compatible shell)
docker exec -it yugabyte ysqlsh -h yugabyte

Then jump into exercises/ysql/01_basics.sql.

Reference

• Cheatsheet — common commands and SQL patterns
• Resources — official docs, talks, deep-dive blog posts