SurrealDB：一条命令启动的多模型数据库

SurrealDB：一条命令启动的多模型数据库

【免费下载链接】surrealdbA scalable, distributed, collaborative, document-graph database, for the realtime web项目地址: https://gitcode.com/GitHub_Trending/su/surrealdb

核心关键词：SurrealDB 多模型数据库

长尾关键词：SurrealDB 快速安装与启动、SurrealDB 内存存储与磁盘存储、SurrealDB 图查询 RELATE、SurrealDB 实时查询 live query、SurrealDB Docker 部署

你写一条"取某用户的帖子和好友"的查询，可用户表在 Postgres、关系在图数据库、标签在文档数据库，权限判断还得在 API 层手写一层。SurrealDB 是用 Rust 写的多模型数据库，把文档、图、关系型收进同一个引擎，权限与实时推送都内置。

📦 一句话说清 SurrealDB 是什么

SurrealDB 是一个多模型数据库：文档、图、关系型（可强制 schema 也可不强制）、时序、地理位置、键值，六种形态共用一套引擎和同一个查询语言 SurrealQL（一种 SQL 风格的查询语言，你可以把它理解为"会写图遍历的 SQL"）。

它同时兼任 API 后端：行级权限写在表定义里，由数据库本身强制，客户端可以直接连上来查，不用你在中间再垫一层鉴权代码。边界也要说清楚——它不是托管平台，部署形态（嵌进应用里、单机服务、分布式集群）要你自己选，本文只讲自己部署这一侧。

🚀 从启动到第一条查询的最快路径

全程用 Docker，不用在本地装任何东西。

第 1 步，起一个内存版开发服务。memory表示数据放在内存里，不落盘、重启即失，正好用来试水：

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

--user/--pass顺手把 root 账号建好了，后面连接要用。

第 2 步，打开 SQL 交互终端连上去。镜像里自带 CLI，--ns和--db是 SurrealDB 的两级命名空间，不先选定它们，你的数据就像没找到目录：

docker exec -it surrealdb /surreal sql -e http://localhost:8000 \ -u root -p root --ns demo --db demo --pretty

第 3 步，建表并插入第一条记录，直接键入 SurrealQL：

DEFINE TABLE person; CREATE person SET name = "Tobie", marketing = true;

第 4 步，查回来验证：

SELECT * FROM person;

看到刚写入的记录，就说明整条链路通了。如果你已经通过其他途径装好了surreal命令（安装方式以项目仓库 README 为准），上面第 1、2 步就简化成surreal start --log info --user root --pass root memory加surreal sql。

🔍 它到底怎么 work 的

第一个关键点：同一个 Rust 代码库，跑法是可选的。它可以作为库嵌进你的应用进程，可以编译成 WebAssembly 在浏览器里跑，也可以像上面那样作为服务端单节点运行，甚至多个节点组成分布式集群。存储层是可插拔的后端：内存、RocksDB、TiKV 等，选哪个在启动时通过参数决定——相当于一个程序，既能当桌面应用装，也能当服务端跑，数据落在哪你自己挑。

第二个关键点：一切都写成 SQL 声明。表结构（DEFINE TABLE）、字段类型与校验（DEFINE FIELD ... TYPE string ASSERT ...）、唯一索引、变更事件（DEFINE EVENT）、权限（PERMISSIONS FOR select WHERE ...）全部用 SurrealQL 声明在 schema 里。schema 就是你和前端、客户端之间唯一的契约，改一处，所有连接方同时生效。

第三个关键点：关系是一等公民，而且能订阅。用RELATE建的是一条带属性的有向边，查询时用->边->直接做多级遍历，不需要 JOIN 也不要把数据拉到客户端再拼；再叠加 live query——订阅一次，之后这条数据变了，服务端会主动推给订阅方，做协作编辑、实时通知这类需求不用自己轮询。

RELATE user:tobie->write->article:surreal SET time.written = time::now();

⚙️ 四个真正影响体验的配置

存储参数memory还是rocksdb:/路径→ 决定数据放内存还是写成本地磁盘文件 → 感受：内存版最快，但容器一停数据全没；切到rocksdb:前缀后重启还在，本地开发想留数据就换它。

--user/--pass→ 指定 root 账号凭据（也可用环境变量SURREAL_USER/SURREAL_PASS）→ 感受：忘了设，连接时就没有能登录的人；生产环境务必改掉默认的root/root。

表级SCHEMAFULL/SCHEMALESS→ 声明后是否强制校验字段定义 → 感受：SCHEMAFULL的表会拒绝写入未声明的字段，前后端共用同一份结构约束；SCHEMALESS则随意写，适合探索期数据。

--log info（或SURREAL_LOG）→ 日志详细程度 → 感受：排查查询卡在哪时提到debug/trace，日常跑info就够，避免日志刷爆终端。

🧭 环境兼容与已知边界

• 运行形态：macOS、Linux、Windows 单节点均可，也可分布式集群；同时支持嵌入进程和 WASM 浏览器内运行。
• 从源码构建：官方 CI 覆盖 macOS、Ubuntu、Windows；Windows 下编译需要管理员权限，musl、树莓派等交叉编译目标目前尚未打通，具体以仓库 doc/BUILDING.md 实际状态为准。
• 存储后端：memory、RocksDB、TiKV、SurrealKV 等，通过构建特性与启动参数选择（详见仓库Cargo.toml的 features 列表）。
• 许可：核心代码为 BSL 1.1，SDK 与相关库为 Apache 2.0 / MIT。
• 版本号：以项目仓库实际为准，当前工作区标注为 3.1.0-alpha，说明仍处于快速迭代期，升级前先看发布说明。

🛠️ 踩坑了先看这里

现象：服务重启后数据没了→ 大概率原因：启动时用的是memory引擎，数据只存在 RAM 里 → 处理动作：把存储参数换成rocksdb:/你的数据目录再启动。

现象：surreal sql连上了，查询却返回空→ 大概率原因：没选 NS/DB，或者和你写数据时用的命名空间不是同一套 → 处理动作：连接时带上--ns和--db，核对账号一致。

现象：连接 8000 端口被拒或端口被占用→ 大概率原因：端口映射或绑定地址被别的服务占用 → 处理动作：换映射-p 8080:8000并同步修改连接地址，或查一下主机上 8000 端口的占用情况。

🔁 让它持续可用

• 升级与回滚：CLI 自带surreal upgrade处理数据升级（参数以仓库surrealdb/server/src/cli/upgrade.rs为准）；Docker 部署时回滚就是改回旧镜像 tag 重启。
• 数据出入与体检：surreal export/surreal import做数据迁移，surreal validate校验 schema。
• 日志与遥测：--log管普通日志，--log-otel-level单独管 OpenTelemetry 追踪粒度；仓库dev/docker目录里有一套现成的可观测栈（Prometheus + Grafana + Tempo），开发时直接docker compose拉起来。

如果你的项目现在要同时伺候几个数据库、再垫一层 API 代码做权限和拼装，SurrealDB 的思路是把这份胶水收进一份 schema 声明里——少维护的系统，往往比多一套更少的出问题的系统。

【免费下载链接】surrealdbA scalable, distributed, collaborative, document-graph database, for the realtime web项目地址: https://gitcode.com/GitHub_Trending/su/surrealdb