SurrealDB

beginner

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

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

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

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

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

Usage Notes

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

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download