SurrealDB with Docker Compose: A Definitive Guide

A hands-on guide to running the multi-model database with Docker, including the Surrealist GUI

Introduction

SurrealDB is a next-generation, multi-model database built in Rust that’s designed to simplify modern application development. Unlike traditional databases that force you to choose between relational, document, or graph models, SurrealDB combines document, graph, relational, time-series, geospatial, and key-value data models into a single, unified platform.

In this comprehensive guide, we’ll explore how to run SurrealDB using Docker and Docker Compose, work with SurrealQL (its powerful query language), and set up the Surrealist GUI for visual database management.

Why SurrealDB?

Before diving into the setup, let’s understand what makes SurrealDB special:

Multi-Model Architecture: SurrealDB natively supports multiple data models without workarounds or added complexity. You can store and query documents, create graph relationships, run relational queries, and work with time-series data—all in a single database.

SurrealQL: A familiar SQL-like query language with enhancements for graph relationships, real-time subscriptions, and advanced data manipulation.

Built for AI: Integrated vector search, full-text search, and hybrid retrieval capabilities make it ideal for AI-powered applications and RAG (Retrieval-Augmented Generation) systems.

Real-time Capabilities: Live queries and WebSocket support enable building collaborative, real-time applications.

Flexible Deployment: Run embedded (in-app), in the browser via WebAssembly, at the edge, or as a distributed cluster in the cloud.

Prerequisites

Before getting started, ensure you have the following installed:

• Docker Desktop (v4.0 or later)
• Docker Compose (usually included with Docker Desktop)
• A terminal or command-line interface

Running SurrealDB with Docker

Quick Start: In-Memory Database

The simplest way to get started with SurrealDB is to run an in-memory instance:

docker run --rm --pull always \
  --name surrealdb \
  -p 8000:8000 \
  surrealdb/surrealdb:latest \
  start --log info --user root --pass root memory

This command:

• Pulls the latest SurrealDB image
• Exposes port 8000 for connections
• Starts with root as both username and password
• Uses in-memory storage (data is lost when the container stops)

Persistent Storage with RocksDB

For development environments where you need data persistence:

# Create a directory for data storage
mkdir -p mydata

# Run SurrealDB with persistent storage
docker run --rm --pull always \
  --name surrealdb \
  -p 8000:8000 \
  --user $(id -u) \
  -v $(pwd)/mydata:/mydata \
  surrealdb/surrealdb:latest \
  start --log info --user root --pass root rocksdb:/mydata/mydatabase.db

Docker Compose Setup

Docker Compose provides a more manageable way to run SurrealDB, especially for development environments or when integrating with other services.

Basic Docker Compose Configuration

Create a docker-compose.yml file:

services:
  surrealdb:
    image: surrealdb/surrealdb:latest
    container_name: surrealdb
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - surrealdb-data:/data
    command:
      - start
      - --log=info
      - --user=root
      - --pass=root
      - file:/data/database.db

volumes:
  surrealdb-data:

Start the database:

docker compose up -d

Production-Ready Docker Compose

For a more robust setup with environment variables:

services:
  surrealdb:
    image: surrealdb/surrealdb:latest
    container_name: surrealdb
    restart: always
    ports:
      - "${SURREAL_PORT:-8000}:8000"
    volumes:
      - surrealdb-data:/data
    environment:
      - SURREAL_USER=${SURREAL_USER:-root}
      - SURREAL_PASS=${SURREAL_PASS:-changeme}
    command:
      - start
      - --log=${SURREAL_LOG_LEVEL:-info}
      - --auth
      - --user=${SURREAL_USER:-root}
      - --pass=${SURREAL_PASS:-changeme}
      - rocksdb:/data/database.db
    healthcheck:
      test: ["CMD", "/surreal", "isready", "--conn", "http://localhost:8000"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

volumes:
  surrealdb-data:
    driver: local

Create a .env file for configuration:

SURREAL_USER=admin
SURREAL_PASS=your_secure_password_here
SURREAL_PORT=8000
SURREAL_LOG_LEVEL=info

Multi-Service Setup with Surrealist GUI

Run SurrealDB alongside the Surrealist web interface:

services:
  surrealdb:
    image: surrealdb/surrealdb:latest
    container_name: surrealdb
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - surrealdb-data:/data
    command:
      - start
      - --log=info
      - --user=root
      - --pass=root
      - rocksdb:/data/database.db
    healthcheck:
      test: ["CMD", "/surreal", "isready", "--conn", "http://localhost:8000"]
      interval: 30s
      timeout: 10s
      retries: 3

  surrealist:
    image: surrealdb/surrealist:latest
    container_name: surrealist
    restart: unless-stopped
    ports:
      - "3000:80"
    depends_on:
      surrealdb:
        condition: service_healthy

volumes:
  surrealdb-data:

Access the services:

• SurrealDB: http://localhost:8000
• Surrealist GUI: http://localhost:3000

Surrealist: The Visual Database Manager

Surrealist is SurrealDB’s official GUI tool for visual database management. It provides an intuitive interface for querying, exploring data, and designing schemas.

Key Features

Query View: Write and execute SurrealQL queries with syntax highlighting, saved queries, and graph visualization of results.

Explorer View: Browse tables, inspect records, and follow relationships visually.

Designer View: Create and visualize your database schema with an interactive diagram.

AI Sidekick: An integrated AI assistant to help write queries and explore data.

Running Surrealist

Option 1: Web App

Visit app.surrealdb.com to use Surrealist directly in your browser.

Option 2: Docker Container

docker run --rm -p 3000:80 surrealdb/surrealist:latest

Option 3: Desktop App

Download from the official releases page for additional features like local database serving.

Connecting to SurrealDB

1. Open Surrealist in your browser
2. Create a new connection with:
   • Endpoint: ws://localhost:8000 (or http://localhost:8000)
   • Namespace: test (or your namespace)
   • Database: test (or your database)
   • Username: root
   • Password: root
3. Click Connect

Getting Started with SurrealQL

SurrealQL is SurrealDB’s query language—familiar to SQL users but enhanced with powerful features for multi-model data.

Connecting via CLI

# Open the SurrealQL shell
docker exec -it surrealdb /surreal sql \
  --conn http://localhost:8000 \
  --user root \
  --pass root \
  --ns test \
  --db test

Basic Operations

Creating Records

-- Create a person with auto-generated ID
CREATE person SET
  name = "Alice Chen",
  email = "alice@example.com",
  age = 28,
  skills = ["Rust", "Go", "JavaScript"];

-- Create with specific ID
CREATE person:bob SET
  name = "Bob Smith",
  email = "bob@example.com",
  age = 32;

Querying Data

-- Select all persons
SELECT * FROM person;

-- Filter with conditions
SELECT name, email FROM person WHERE age > 25;

-- Order and limit results
SELECT * FROM person ORDER BY age DESC LIMIT 10;

Updating Records

-- Update specific record
UPDATE person:bob SET age = 33;

-- Merge data into matching records
UPDATE person SET verified = true WHERE age > 30;

Deleting Records

-- Delete specific record
DELETE person:bob;

-- Delete with condition
DELETE person WHERE age < 18;

Graph Relationships

One of SurrealDB’s most powerful features is native graph support:

-- Create companies
CREATE company:surreal SET name = "SurrealDB";
CREATE company:techcorp SET name = "TechCorp";

-- Create relationship (edge)
RELATE person:alice->works_at->company:surreal SET
  title = "Senior Engineer",
  started = d"2023-01-15",
  department = "Engineering";

-- Query relationships
SELECT
  name,
  ->works_at->company.name AS employer,
  ->works_at.title AS job_title
FROM person;

-- Graph traversal
SELECT * FROM person:alice->works_at->company;

Advanced Features

Live Queries (Real-time)

-- Subscribe to changes on a table
LIVE SELECT * FROM person WHERE age > 21;

Subqueries

-- Calculate average and use in filter
LET $avg_age = (SELECT math::mean(age) AS avg FROM person GROUP ALL).avg;
SELECT name FROM person WHERE age > $avg_age;

Record Links

-- Create article with author reference
CREATE article SET
  title = "Getting Started with SurrealDB",
  author = person:alice,
  published = time::now();

-- Query with automatic link resolution
SELECT title, author.name FROM article FETCH author;

Importing Sample Data

SurrealDB provides sample datasets for testing:

# Download sample dataset
curl -L "https://datasets.surrealdb.com/surreal-deal-store-mini.surql" \
  -o surreal-deal-store-mini.surql

# Import into SurrealDB
curl -X POST \
  -u "root:root" \
  -H "surreal-ns: test" \
  -H "surreal-db: test" \
  -H "Accept: application/json" \
  --data-binary @surreal-deal-store-mini.surql \
  http://localhost:8000/import

Or via Docker:

docker exec -i surrealdb /surreal import \
  --conn http://localhost:8000 \
  --user root \
  --pass root \
  --ns test \
  --db test \
  /path/to/data.surql

SurrealDB MCP Integration

SurrealDB also provides MCP (Model Context Protocol) support for AI integrations, allowing AI tools to connect directly to your database:

{
  "mcpServers": {
    "SurrealDB": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--pull", "always",
        "surrealdb/surrealmcp:latest",
        "start"
      ]
    }
  }
}

This enables seamless integration with AI development environments like VSCode and Cursor.

Conclusion

SurrealDB with Docker Compose provides a powerful, flexible database solution for modern applications. Its multi-model architecture eliminates the need for multiple specialized databases, while Docker makes deployment and management straightforward.

Whether you’re building AI-powered applications, real-time collaborative tools, or complex data systems with graph relationships, SurrealDB offers the features you need in a single, unified platform.

Resources

• SurrealDB Documentation
• SurrealDB GitHub
• Surrealist GUI
• Docker Hub – SurrealDB
• SurrealDB Discord Community

Happy building with SurrealDB!