# YugabyteDB

> Distributed SQL database compatible with PostgreSQL and Cassandra APIs.

- Category: Database Stacks
- Difficulty: advanced
- Components: yugabytedb
- Tags: yugabyte, distributed, sql, postgres-compatible, cassandra
- Source: https://docker.recipes/databases/yugabytedb

## Overview

YugabyteDB is a distributed SQL database that combines the ACID guarantees of traditional relational databases with the horizontal scalability of NoSQL systems. Originally developed by former Facebook engineers, YugabyteDB provides dual APIs - PostgreSQL-compatible YSQL and Cassandra-compatible YCQL - allowing applications to use familiar SQL interfaces while benefiting from automatic sharding, replication, and fault tolerance across multiple nodes.

This Docker configuration launches YugabyteDB using the yugabyted orchestrator, which manages both the master and tablet server processes in a single container for development purposes. The setup exposes both PostgreSQL (port 5433) and Cassandra (port 9042) APIs simultaneously, along with the master web UI (port 7000) and internal RPC ports. YugabyteDB automatically handles data distribution, consensus through Raft protocol, and provides strong consistency with tunable read replicas.

Developers building globally distributed applications, teams migrating from PostgreSQL who need horizontal scaling, and organizations requiring multi-region deployments with automatic failover will find this stack valuable. The dual API support makes it particularly useful for polyglot applications that need both relational and wide-column data models, while the cloud-native architecture eliminates the operational complexity of managing database sharding and replication manually.

## Features

- Dual API support with PostgreSQL-compatible YSQL and Cassandra-compatible YCQL interfaces
- Automatic data sharding and distribution across nodes without manual intervention
- Distributed ACID transactions with serializable isolation level across multiple tablets
- Built-in Raft consensus for fault tolerance and automatic leader election
- Multi-region deployment capabilities with configurable replication factors
- Online schema changes and rolling upgrades without downtime
- Compatible with existing PostgreSQL drivers, tools, and ORMs
- Geographic data placement with tablespace-level locality control

## Use cases

- E-commerce platforms requiring global product catalogs with local inventory management
- Financial services applications needing distributed transactions across regions
- SaaS applications migrating from PostgreSQL that hit single-node scaling limits
- IoT data collection systems requiring high write throughput with SQL analytics
- Multi-tenant applications needing automatic data partitioning by customer
- Gaming platforms with global leaderboards and player data synchronization
- Microservices architectures requiring consistent data across service boundaries

## Prerequisites

- Minimum 4GB RAM available to Docker (YugabyteDB requires 2GB+ for optimal performance)
- Docker Engine 19.03 or later with compose plugin support
- Available ports 5433, 7000, 9000, and 9042 on the host system
- Basic understanding of SQL and distributed database concepts
- PostgreSQL client tools (psql) or Cassandra client (cqlsh) for database interaction
- Understanding of eventual consistency vs strong consistency trade-offs

## docker-compose.yml

```yaml
services:
  yb-master:
    image: yugabytedb/yugabyte:latest
    container_name: yb-master
    command: yugabyted start --daemon=false --ui=false
    volumes:
      - yb_data:/home/yugabyte/yb_data
    ports:
      - "7000:7000"
      - "9000:9000"
      - "5433:5433"
      - "9042:9042"
    networks:
      - yb-network

volumes:
  yb_data:

networks:
  yb-network:
    driver: bridge
```

## .env

```bash
# YugabyteDB default configuration
```

## Usage notes

- Docs: https://docs.yugabyte.com/
- Admin UI at http://localhost:7000 | PostgreSQL API on port 5433
- Cassandra API on port 9042 - use cqlsh for CQL
- PostgreSQL-compatible: psql -h localhost -p 5433 -U yugabyte
- Distributed ACID transactions across nodes
- Horizontally scalable - add more nodes for capacity

## Troubleshooting

- Container exits with 'insufficient memory' error: Increase Docker memory limit to at least 4GB in Docker Desktop settings
- Cannot connect to PostgreSQL API on port 5433: Wait 60-90 seconds after startup for YugabyteDB initialization to complete
- Web UI shows 'Under-replicated tablets' warning: Normal in single-node setup, indicates need for additional nodes in production
- YCQL queries return 'keyspace does not exist': Create keyspace first using 'CREATE KEYSPACE IF NOT EXISTS' statement
- Connection refused on port 9042: Cassandra API may take longer to initialize than PostgreSQL API, verify with 'docker logs yb-master'
- High CPU usage during startup: YugabyteDB performs initial tablet splitting and load balancing, CPU will normalize after 5-10 minutes

