YugabyteDB

advanced

Distributed SQL database compatible with PostgreSQL and Cassandra APIs.

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.

Key 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

Common Use Cases

1E-commerce platforms requiring global product catalogs with local inventory management
2Financial services applications needing distributed transactions across regions
3SaaS applications migrating from PostgreSQL that hit single-node scaling limits
4IoT data collection systems requiring high write throughput with SQL analytics
5Multi-tenant applications needing automatic data partitioning by customer
6Gaming platforms with global leaderboards and player data synchronization
7Microservices 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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  yb-master: 
3    image: yugabytedb/yugabyte:latest
4    container_name: yb-master
5    command: yugabyted start --daemon=false --ui=false
6    volumes: 
7      - yb_data:/home/yugabyte/yb_data
8    ports: 
9      - "7000:7000"
10      - "9000:9000"
11      - "5433:5433"
12      - "9042:9042"
13    networks: 
14      - yb-network
15
16volumes: 
17  yb_data: 
18
19networks: 
20  yb-network: 
21    driver: bridge

.env Template

.env

1# YugabyteDB default configuration

Usage Notes

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

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  yb-master:
5    image: yugabytedb/yugabyte:latest
6    container_name: yb-master
7    command: yugabyted start --daemon=false --ui=false
8    volumes:
9      - yb_data:/home/yugabyte/yb_data
10    ports:
11      - "7000:7000"
12      - "9000:9000"
13      - "5433:5433"
14      - "9042:9042"
15    networks:
16      - yb-network
17
18volumes:
19  yb_data:
20
21networks:
22  yb-network:
23    driver: bridge
24EOF
25
26# 2. Create the .env file
27cat > .env << 'EOF'
28# YugabyteDB default configuration
29EOF
30
31# 3. Start the services
32docker compose up -d
33
34# 4. View logs
35docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/yugabytedb/run | bash

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

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

yugabytedb

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download