YugabyteDB Tutorial: Learn Distributed SQL from Scratch (2026)
I have worked with YugabyteDB in several cloud-native projects. Its architecture balances PostgreSQL compatibility with horizontal scalability for cloud-native applications.
We will cover installation, YSQL API, automatic sharding and replication, cluster survivability, and production operations.
Installing YugabyteDB and Starting a Cluster
Install via the yugabyted CLI tool. The yugabyted start command bootstraps a cluster. Multi-node: run on each node and join.
YugabyteDB uses a tablet-centric architecture. Tables split into tablets (1 GB default), replicated via Raft. YB-Master manages placement; YB-TServer handles queries.
yugabyted start --advertise_address 127.0.0.1 --base_dir ~/yb_data
psql -h 127.0.0.1 -p 5433 -U yugabyteYSQL: PostgreSQL-Compatible Distributed SQL
YSQL is built on the PostgreSQL codebase. Most PostgreSQL features work: data types, DML, DDL, indexes, stored procedures.
Distributed transactions use hybrid clock (HLC) for ordering. Default isolation is READ COMMITTED with SERIALIZABLE on demand.
CREATE TABLE user_events (user_id UUID NOT NULL, event_time TIMESTAMPTZ NOT NULL, event_type TEXT NOT NULL, payload JSONB, PRIMARY KEY (user_id, event_time)) SPLIT INTO 16 TABLETS;
BEGIN; UPDATE accounts SET balance = balance - 100 WHERE id = 1; UPDATE accounts SET balance = balance + 100 WHERE id = 2; COMMIT;Sharding, Replication, and Geo-Distribution
Default hash sharding on primary key distributes writes evenly. Range sharding available for ordered scans. Replication factor 3 by default.
Geo-distribution places replicas across data centers and regions. Preferred zones for leaseholders and geo-partitioning for data residency.
SELECT tablet_id, table_name, partition, num_sst_files, on_disk_size FROM yb_table_properties('user_events');
ALTER DATABASE mydb REPLICATION FACTOR 5;
ALTER TABLE user_events SET (leader_hint_preference = '{"cloud.region.zone": "aws.us-east-1a"}');Secondary Indexes and Query Performance
Global indexes in their own tablet space. Local indexes colocate with base tablet. Covering indexes skip the second lookup phase.
Partial indexes reduce size by filtering on WHERE clause. Use EXPLAIN (ANALYZE, DIST) to see distributed execution plans.
CREATE INDEX idx_event_type ON user_events(event_type);
CREATE INDEX idx_event_type_local ON user_events(event_type, user_id, event_time) LOCAL;
CREATE INDEX idx_covering ON user_events(event_type) INCLUDE (payload);
EXPLAIN (ANALYZE, DIST) SELECT * FROM user_events WHERE event_type = 'purchase';Backup, Restore, and Data Migration
Use yb-admin for cluster-level snapshots. pg_dump works for SQL-level backup but is slower for large datasets.
Change Data Capture (CDC) publishes change events to Kafka or Pulsar with exactly-once semantics per tablet.
yb-admin -master_addresses 127.0.0.1:7100 create_keyspace_snapshot ysql.mydb
yb-admin -master_addresses 127.0.0.1:7100 list_snapshots
yb-admin -master_addresses 127.0.0.1:7100 restore_snapshot Monitoring and Cluster Operations
Metrics at http://localhost:7000 (YB-Master UI) and http://localhost:9000 (YB-TServer UI). Prometheus integration for monitoring.
Routine operations: tablet rebalancing, rolling upgrades, decommissioning nodes. Use yb-admin change_leader_config before draining a node.
yb-admin -master_addresses 127.0.0.1:7100 list_all_masters
yb-admin -master_addresses 127.0.0.1:7100 list_all_tservers
yb-admin -master_addresses 127.0.0.1:7100 set_load_balance_enabled 1Frequently Asked Questions
Is YugabyteDB free?
Yes, 100% open-source under Apache 2.0. No paid editions. YugabyteDB Managed is a paid cloud service.
How does YugabyteDB compare to CockroachDB?
YugabyteDB uses custom Raft with RocksDB-based DocDB. CockroachDB has deeper PostgreSQL compatibility. YugabyteDB also offers YCQL (Cassandra-compatible).
Can YugabyteDB handle multi-region deployments?
Yes. Supports geo-partitioning, preferred zone leaders, and async replication across regions. Configure cluster.rf=5 for 5-node survivability.
Does YugabyteDB support online schema migrations?
Yes. Most DDL is non-blocking. Online index backfill creates indexes in the background while serving reads and writes.
Originally published on Ayodhyyya. Last updated June 1, 2026.