# SurrealDB — Scalable Multi-Model Database for Modern Apps

> SurrealDB is a scalable, distributed, collaborative, document-graph database for the real-time web. Combines relational, document, graph, and time-series models in one database with SurrealQL query language. Built in Rust for performance and reliability.

## Install

Save in your project root:

## Quick Use

```bash
# Install
curl -sSf https://install.surrealdb.com | sh
# Or Docker
docker run -d --name surrealdb -p 8000:8000 \
  surrealdb/surrealdb:latest start --user root --pass root

# Connect
surreal sql --conn http://localhost:8000 --user root --pass root --ns test --db test
```

SurrealQL:
```sql
-- Document model
CREATE user:william SET
  name = "William",
  email = "w@tokrepo.com",
  roles = ["admin", "founder"],
  created_at = time::now();

-- Graph relations
RELATE user:william->founded->product:tokrepo SET year = 2025;
RELATE user:william->uses->tool:claude_code;

-- Query graph
SELECT ->founded->product.name FROM user:william;
SELECT <-founded<-user.name FROM product:tokrepo;

-- Traditional SQL
SELECT * FROM user WHERE roles CONTAINS "admin" ORDER BY created_at DESC;

-- Live queries (real-time)
LIVE SELECT * FROM user;

-- Full-text search
DEFINE INDEX user_name ON user FIELDS name SEARCH ANALYZER ascii BM25;
SELECT * FROM user WHERE name @@ "william";

-- Permissions
DEFINE TABLE user SCHEMAFUL
  PERMISSIONS
    FOR select, create WHERE $auth.role = "admin"
    FOR update, delete WHERE id = $auth.id;
```

## Intro

SurrealDB is a scalable, distributed, multi-model database designed for modern applications. It combines the strengths of relational, document, graph, and time-series databases into a single product with a powerful query language (SurrealQL). Built in Rust by Tobie Morgan Hitchcock and Jaime Morgan Hitchcock.

- **Repo**: https://github.com/surrealdb/surrealdb
- **Stars**: 31K+
- **Language**: Rust
- **License**: BSL 1.1 (converts to Apache 2.0)

## What SurrealDB Does

- **Multi-model** — document, graph, relational, time-series in one DB
- **SurrealQL** — SQL-like with graph traversal, record links, subqueries
- **Graph relations** — RELATE for typed edges between records
- **Record links** — embed references between documents
- **Live queries** — real-time change notifications
- **Full-text search** — BM25 index built in
- **Permissions** — row-level security with JWT auth
- **Multi-tenancy** — namespace and database isolation
- **Embedded or server** — use as library or HTTP/WebSocket server
- **SDK** — JavaScript, Python, Rust, Go, Java, .NET, PHP

## Architecture

Rust binary with multiple storage backends: in-memory, RocksDB (single node), TiKV (distributed), FoundationDB (distributed). HTTP and WebSocket API for clients. SurrealQL parser compiles queries to execution plans.

## Self-Hosting

```bash
# Single-node with persistence
surreal start --log info --user root --pass root file://surreal.db

# Distributed (TiKV backend)
surreal start --log info --user root --pass root tikv://pd:2379
```

## Key Features

- Multi-model (doc + graph + relational)
- SurrealQL query language
- Graph traversal
- Live queries (real-time)
- Full-text search (BM25)
- Row-level permissions
- Multi-tenancy
- Embedded or server mode
- Multiple storage backends
- SDKs for 7+ languages

## Comparison

| Database | Models | Query Lang | Distributed |
|---|---|---|---|
| SurrealDB | Doc + Graph + Relational | SurrealQL | Via TiKV/FDB |
| MongoDB | Document | MQL | Sharding |
| Neo4j | Graph | Cypher | Enterprise |
| PostgreSQL | Relational (+ JSON) | SQL | Logical repl |
| ArangoDB | Doc + Graph + KV | AQL | Native |
| FaunaDB | Document + relational | FQL | Managed |

## 常见问题 FAQ

**Q: 一个数据库解决所有问题？**
A: SurrealDB 的目标是减少 polyglot persistence 的复杂度。文档、图关系、全文搜索在一个引擎里，不用同步多个数据库。适合中等规模项目。

**Q: 生产就绪了吗？**
A: v2.0+ 已经大幅稳定，但相比 PostgreSQL/MongoDB 生态还年轻。适合新项目和创新应用，关键任务系统需要评估。

**Q: BSL 限制？**
A: 自用、嵌入应用完全 OK。不能做托管 SurrealDB 服务与官方竞争。4 年后自动转 Apache 2.0。

## 来源与致谢 Sources

- Docs: https://surrealdb.com/docs
- GitHub: https://github.com/surrealdb/surrealdb
- License: BSL 1.1

---
Source: https://tokrepo.com/en/workflows/9033274f-3649-11f1-9bc6-00163e2b0d79
Author: AI Open Source