# Dgraph Graph Database

> Dgraph distributed graph database with Ratel UI.

- Category: Database Stacks
- Difficulty: intermediate
- Components: dgraph-zero, dgraph-alpha, dgraph-ratel
- Tags: dgraph, graph, distributed, graphql, nosql
- Source: https://docker.recipes/databases/dgraph-graph-database

## Overview

Dgraph is a horizontally scalable and distributed graph database written in Go, designed to handle complex graph queries with native GraphQL support and a SQL-like query language called GraphQL+-. The database architecture separates concerns through specialized components: dgraph-zero acts as the cluster orchestrator managing metadata, group membership, and transaction timestamps, while dgraph-alpha serves as the data node handling actual graph storage and query processing. This configuration includes Ratel, Dgraph's web-based UI that provides an intuitive interface for schema management, data exploration, and query execution with real-time visualization of graph relationships.

The three-component stack creates a production-ready distributed graph database where dgraph-zero coordinates the cluster state and dgraph-alpha processes queries against the actual graph data, while Ratel offers a powerful administrative interface for database operations. Unlike traditional relational databases, this setup excels at handling complex interconnected data with multi-hop traversals, making relationship queries that would require expensive JOINs in SQL databases execute efficiently through native graph algorithms. The distributed architecture allows horizontal scaling by adding more alpha nodes while maintaining ACID compliance and strong consistency across the cluster.

Data engineers working with knowledge graphs, recommendation engines, and fraud detection systems will find this stack particularly valuable, as will developers building social networks, IoT device management platforms, and any application requiring complex relationship modeling. The combination of native GraphQL support, distributed architecture, and the intuitive Ratel interface makes this configuration ideal for teams transitioning from traditional databases to graph-based solutions, or organizations needing to scale existing graph workloads across multiple nodes while maintaining query performance and data consistency.

## Features

- Native GraphQL and GraphQL+- query language support with automatic schema inference
- Horizontal scaling through dgraph-alpha node replication with automatic sharding
- ACID transaction compliance with distributed consensus using Raft protocol
- Real-time graph visualization and query execution through Ratel web interface
- Multi-version concurrency control enabling consistent reads during writes
- Built-in full-text search with configurable analyzers and tokenizers
- Automatic background compaction and garbage collection for optimal storage
- Type system with predicate-based schema validation and indexing strategies

## Use cases

- Social networking platforms requiring friend-of-friend recommendations and social graph analysis
- E-commerce recommendation engines analyzing user behavior and product relationships
- Fraud detection systems tracking complex transaction patterns and entity connections
- Knowledge management platforms organizing interconnected documents and concepts
- IoT device networks modeling sensor relationships and data flow dependencies
- Supply chain management tracking product origins and distribution networks
- Content management systems with complex taxonomies and cross-referenced articles

## Prerequisites

- Minimum 4GB RAM allocation for dgraph-alpha with additional memory for large datasets
- Docker Engine 20.10+ with Docker Compose v2 support for proper networking
- Available ports 5080, 6080, 8000, 8080, and 9080 for inter-service communication
- Basic understanding of graph database concepts and GraphQL query syntax
- SSD storage recommended for optimal query performance and data persistence
- Network connectivity allowing container-to-container communication on bridge network

## docker-compose.yml

```yaml
services:
  zero:
    image: dgraph/dgraph:latest
    container_name: dgraph-zero
    restart: unless-stopped
    volumes:
      - dgraph_zero:/dgraph
    ports:
      - "5080:5080"
      - "6080:6080"
    command: dgraph zero --my=zero:5080
    networks:
      - dgraph-network

  alpha:
    image: dgraph/dgraph:latest
    container_name: dgraph-alpha
    restart: unless-stopped
    volumes:
      - dgraph_alpha:/dgraph
    ports:
      - "${ALPHA_PORT:-8080}:8080"
      - "9080:9080"
    command: dgraph alpha --my=alpha:7080 --zero=zero:5080 --security whitelist=0.0.0.0/0
    depends_on:
      - zero
    networks:
      - dgraph-network

  ratel:
    image: dgraph/ratel:latest
    container_name: dgraph-ratel
    restart: unless-stopped
    ports:
      - "${RATEL_PORT:-8000}:8000"
    networks:
      - dgraph-network

volumes:
  dgraph_zero:
  dgraph_alpha:

networks:
  dgraph-network:
    driver: bridge
```

## .env

```bash
# Dgraph
ALPHA_PORT=8080
RATEL_PORT=8000
```

## Usage notes

- Ratel UI at http://localhost:8000
- Alpha API at http://localhost:8080
- GraphQL support built-in
- Native distributed graph

## Troubleshooting

- Error 'zero server is not ready': Wait 30-60 seconds for dgraph-zero initialization before alpha connection attempts
- Ratel UI shows 'Connection failed': Verify dgraph-alpha is accessible at localhost:8080 and check firewall settings
- Query timeout errors: Increase memory allocation for dgraph-alpha or add query complexity limits in schema
- Port binding conflicts: Modify ALPHA_PORT and RATEL_PORT environment variables if default ports are occupied
- Data persistence issues: Ensure Docker volumes dgraph_zero and dgraph_alpha have proper write permissions
- High memory usage during imports: Use chunked data loading through live loader or bulk loader utilities

