SurrealDB

beginner

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

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

[*]Key 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

[#]Common Use Cases

[1]Real-time collaborative applications requiring live data synchronization
[2]Serverless backend development with edge deployment capabilities
[3]Social networking platforms needing graph relationships and document storage
[4]IoT data collection systems with time-series and relational data requirements
[5]Content management systems requiring full-text search and flexible schemas
[6]Gaming applications with player profiles, leaderboards, and real-time updates
[7]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

[!]

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  surrealdb: 
3    image: surrealdb/surrealdb:latest
4    container_name: surrealdb
5    restart: unless-stopped
6    command: start --user ${SURREAL_USER} --pass ${SURREAL_PASS} file:/data/database.db
7    volumes: 
8      - surreal_data:/data
9    ports: 
10      - "8000:8000"
11    networks: 
12      - surreal-network
13
14volumes: 
15  surreal_data: 
16
17networks: 
18  surreal-network: 
19    driver: bridge

[$].env Template

[.env]

1SURREAL_USER=root
2SURREAL_PASS=changeme

[i]Usage Notes

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

[>]Quick Start

[terminal]

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  surrealdb:
5    image: surrealdb/surrealdb:latest
6    container_name: surrealdb
7    restart: unless-stopped
8    command: start --user ${SURREAL_USER} --pass ${SURREAL_PASS} file:/data/database.db
9    volumes:
10      - surreal_data:/data
11    ports:
12      - "8000:8000"
13    networks:
14      - surreal-network
15
16volumes:
17  surreal_data:
18
19networks:
20  surreal-network:
21    driver: bridge
22EOF
23
24# 2. Create the .env file
25cat > .env << 'EOF'
26SURREAL_USER=root
27SURREAL_PASS=changeme
28EOF
29
30# 3. Start the services
31docker compose up -d
32
33# 4. View logs
34docker 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/surrealdb/run | bash

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

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

surrealdb

## Tags

#surrealdb#multi-model#sql#graph#realtime

## Category

Database Stacks

## Related

Shortcuts: C CopyF FavoriteD Download