$docker.recipes

YugabyteDB

advanced

Distributed SQL database compatible with PostgreSQL and Cassandra APIs.

[i]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

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

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

[$]docker-compose.yml

[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

[i]Usage Notes

  1. [1]Docs: https://docs.yugabyte.com/
  2. [2]Admin UI at http://localhost:7000 | PostgreSQL API on port 5433
  3. [3]Cassandra API on port 9042 - use cqlsh for CQL
  4. [4]PostgreSQL-compatible: psql -h localhost -p 5433 -U yugabyte
  5. [5]Distributed ACID transactions across nodes
  6. [6]Horizontally 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...
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

## Tags

#yugabyte#distributed#sql#postgres-compatible#cassandra

## Category

Database Stacks

## Related