# SurrealDB

> Multi-model database for web, mobile, serverless, and traditional applications.

- Category: Database Stacks
- Difficulty: beginner
- Components: surrealdb
- Tags: surrealdb, multi-model, sql, graph, realtime
- Source: https://docker.recipes/databases/surrealdb

## Overview

SurrealDB is a next-generation cloud-native database that combines SQL, document, and graph database capabilities into a single, unified system. Developed to address the complexities of modern application architectures, SurrealDB offers real-time subscriptions, row-level security, and a powerful query language called SurrealQL. Unlike traditional databases that force developers to choose between relational, document, or graph models, SurrealDB supports all three paradigms simultaneously, eliminating the need for multiple database systems. This Docker configuration deploys SurrealDB as a containerized service with file-based storage, making it ideal for development environments and small to medium-scale production deployments. The setup uses persistent volumes to ensure data durability and exposes the database through its HTTP API on port 8000, enabling direct interaction through REST calls or the SurrealDB CLI. SurrealDB excels in modern full-stack applications, serverless backends, and real-time systems where developers need flexible data modeling combined with live data synchronization. Its ability to run embedded or in server mode, coupled with built-in authentication and multi-tenancy support, makes it particularly valuable for startups building MVP products and developers prototyping complex data relationships without the overhead of managing multiple database technologies.

## Features

- Multi-model database supporting SQL, document, and graph data paradigms simultaneously
- SurrealQL query language with advanced filtering, aggregation, and graph traversal capabilities
- Real-time subscriptions for live data synchronization across connected clients
- Row-level security with fine-grained permissions and authentication built-in
- Schema-less or schema-full operation with flexible data validation rules
- Full-text search capabilities integrated directly into the database engine
- Multi-tenancy support with namespace and database isolation
- HTTP/WebSocket API endpoints for language-agnostic database access

## Use cases

- Real-time collaborative applications requiring live data synchronization
- Serverless backend development with edge deployment capabilities
- Social networking platforms needing graph relationships and document storage
- IoT data collection systems with time-series and relational data requirements
- Content management systems requiring full-text search and flexible schemas
- Gaming applications with player profiles, leaderboards, and real-time updates
- Financial applications needing complex relationships and audit trails

## Prerequisites

- Docker and Docker Compose installed on the host system
- Minimum 256MB RAM available, recommended 1GB+ for production workloads
- Port 8000 available for SurrealDB HTTP API access
- Basic understanding of SQL and NoSQL database concepts
- Familiarity with SurrealQL syntax for advanced query operations
- Environment variables SURREAL_USER and SURREAL_PASS configured for authentication

## docker-compose.yml

```yaml
services:
  surrealdb:
    image: surrealdb/surrealdb:latest
    container_name: surrealdb
    restart: unless-stopped
    command: start --user ${SURREAL_USER} --pass ${SURREAL_PASS} file:/data/database.db
    volumes:
      - surreal_data:/data
    ports:
      - "8000:8000"
    networks:
      - surreal-network

volumes:
  surreal_data:

networks:
  surreal-network:
    driver: bridge
```

## .env

```bash
SURREAL_USER=root
SURREAL_PASS=changeme
```

## Usage notes

- Docs: https://surrealdb.com/docs
- HTTP API at http://localhost:8000 - use SurrealQL for queries
- Connect: surreal sql --conn http://localhost:8000 --ns test --db test
- Multi-model: documents, graphs, full-text search in one
- Built-in authentication, permissions, and real-time subscriptions
- Great for serverless and edge deployments

## Troubleshooting

- Connection refused on port 8000: Verify container is running and port mapping is correct in docker-compose.yml
- Authentication failed errors: Ensure SURREAL_USER and SURREAL_PASS environment variables are properly set and exported
- Database file corruption after container restart: Check that surreal_data volume has proper permissions and sufficient disk space
- SurrealQL syntax errors: Verify query syntax against SurrealDB documentation, as it differs from standard SQL
- Memory allocation errors during startup: Increase Docker memory limits or reduce other running containers
- WebSocket connection drops in real-time subscriptions: Check firewall settings and ensure persistent network connectivity

