SurrealDB 快速上手教程

SurrealDB 是一个专为现代应用程序设计的端到端云原生数据库，支持 Web、移动、无服务器、Jamstack、后端和传统应用。它旨在简化数据库和 API 基础设施，缩短开发时间，并帮助您快速、经济高效地构建安全、高性能的应用程序。

1. SurrealDB 简介与核心特性

SurrealDB 是一个多模型数据库，这意味着它能够以多种范式存储和查询数据，包括：

图数据库 (Graph Database)
文档数据库 (Document Database)
时间序列数据库 (Time-Series Database)
向量数据库 (Vector Database)

所有这些数据模型都可以通过其强大的查询语言 SurrealQL 进行查询。

主要特性：

减少开发时间： 将数据库、查询层、API 和认证层整合到一个平台，减少对传统后端组件的依赖。
实时协作 API 后端服务： 既是数据库，也是 API 后端服务，支持实时协作。
支持多种查询语言： 支持从客户端设备进行 SQL 查询、GraphQL（即将推出）、ACID 事务、WebSocket 连接、结构化和非结构化数据、图查询、全文索引和地理空间查询。
细粒度访问控制： 提供行级权限控制，精确管理数据访问。
多模型支持： 允许开发者使用多种技术存储和建模数据，无需预先选择特定方法。
高级文档间关系： 通过记录链接和图边连接实现高效的关联查询，避免复杂的 JOIN 操作。
简单模式定义： 统一数据库和 API 模式定义，简化前端和后端开发。
直接从客户端连接： 允许 Web 浏览器和客户端设备直接连接并查询，内置权限控制。
实时查询和数据变更： 实时同步数据修改到客户端，支持高级过滤和高效的数据格式（如 DIFFing 和 PATCHing）。
轻松扩展： 可作为单节点内存数据库运行，也可扩展到分布式集群，提供高可用性和可伸缩性。
通过 JavaScript 函数扩展： 支持嵌入式 JavaScript 函数，将计算逻辑移至数据层。
可嵌入或云端部署： 完全用 Rust 构建，可作为嵌入式库或分布式数据库服务器使用。

2. 安装 SurrealDB

SurrealDB 提供了多种安装方式，您可以根据自己的操作系统和偏好选择。

2.1 通过安装脚本 (macOS / Linux)

这是在 macOS 或 Linux 上安装 SurrealDB 最简单和推荐的方式。

bash 复制代码

curl -sSf https://install.surrealdb.com | sh

安装完成后，您可以通过运行 surreal help 来验证安装是否成功。

2.2 通过 Homebrew (macOS)

如果您是 macOS 用户并使用 Homebrew，可以通过以下命令安装：

bash 复制代码

brew install surrealdb/tap/surreal

要更新 SurrealDB，请运行：

bash 复制代码

brew upgrade surrealdb/tap/surreal

2.3 通过 PowerShell (Windows)

在 Windows 上，您可以使用 PowerShell 脚本进行安装：

powershell 复制代码

iwr https://windows.surrealdb.com -useb | iex

要更新 SurrealDB，请运行：

powershell 复制代码

surreal upgrade

如果遇到 DLL 错误（如 VCRUNTIME140.dll），可能需要安装 Microsoft Visual C++ Redistributable for Visual Studio。

2.4 通过 Docker

Docker 是运行 SurrealDB 实例的便捷方式，无需安装任何命令行工具。

启动一个内存数据库实例：

bash 复制代码

docker run --rm --pull always --name surrealdb -p 8000:8000 surrealdb/surrealdb:latest start

启动一个带认证的内存数据库实例（用户名为 root，密码为 root）：

bash 复制代码

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

启动一个持久化数据到磁盘的实例（使用 RocksDB 存储引擎）：

bash 复制代码

mkdir mydata # 创建一个目录来存储数据库，由当前用户拥有
docker run --rm --pull always -p 8000:8000 --user $(id -u) -v $(pwd)/mydata:/mydata surrealdb/surrealdb:latest start rocksdb:/mydata/mydatabase.db

更多 Docker 运行选项和持久化配置，请参考官方文档。

3. 启动 SurrealDB 服务器

安装完成后，您可以使用 surreal start 命令启动数据库服务器。您需要指定存储引擎，例如 memory（内存）、rocksdb（单节点磁盘）或 tikv（多节点集群）。

启动一个内存数据库：

bash 复制代码

surreal start memory

默认情况下，用户名和密码都设置为 root。您可以使用 -u 和 -p 标志来设置自定义的用户名和密码。

4. SurrealQL 快速入门

SurrealQL 是 SurrealDB 的查询语言，灵感来源于传统 SQL，但更加灵活和富有表现力。

4.1 创建数据 (CREATE)

使用 CREATE 语句向数据库添加新记录。

创建 category 表的记录：

sql 复制代码

CREATE category SET name = 'Technology', created_at = time::now();

创建指定 ID 的 person 记录：

sql 复制代码

CREATE person:john SET name = 'John Doe', age = 30, admin = true, signup_at = time::now();

使用子查询创建关联记录：

sql 复制代码

CREATE article SET title = 'My First Article', category = (SELECT id FROM category WHERE name = 'Technology')[0];

4.2 查询数据 (SELECT)

使用 SELECT 语句检索数据。

选择所有 article 记录：

sql 复制代码

SELECT * FROM article;

选择指定 ID 的 person 记录：

sql 复制代码

SELECT * FROM person:john;

结合过滤和关联查询：

sql 复制代码

SELECT title, author.name.full FROM article WHERE author.age < 30 FETCH author;

4.3 修改数据 (UPDATE)

使用 UPDATE 语句修改现有记录的内容。

更新 person:john 的年龄：

sql 复制代码

UPDATE person:john SET age = 31;

合并新数据到匹配条件的记录：

sql 复制代码

UPDATE user WHERE status = 'active' MERGE { last_login = time::now() };

UPSERT (更新或创建)： UPSERT 语句在记录不存在时创建它，存在时更新它。

sql 复制代码

UPSERT user:alice SET email = 'alice@example.com' ON DUPLICATE KEY UPDATE last_updated = time::now();

4.4 删除数据 (DELETE)

使用 DELETE 语句从数据库中删除记录。

删除 person:john 记录并返回被删除的记录：

sql 复制代码

DELETE person:john RETURN BEFORE;

5. 高级概念速览

5.1 数据类型与类型转换

SurrealDB 支持强类型数据，包括布尔值、字符串、数字（decimal, int, float）、日期时间、持续时间、数组、嵌套对象和 GeoJSON 地理空间数据。

示例：类型转换

sql 复制代码

UPDATE person SET
    waist = <int> "34",
    height = <float> 201,
    score = <decimal> 0.3 + 0.3 + 0.3 + 0.1
;

5.2 动态计算字段 (Future)

可以将字段定义为 future 类型，其值仅在查询时计算。

示例：计算倒计时

sql 复制代码

CREATE product SET
    name = "SurrealDB",
    launch_at = <datetime> "2021-11-01",
    countdown = <future> { launch_at - time::now() }
;

5.3 模式定义与约束

可以定义表的模式（schemafull 或 schemaless），并为字段添加类型、断言（ASSERT）和默认值。

示例：定义用户表模式

sql 复制代码

-- 创建一个带模式的表
DEFINE TABLE user SCHEMAFULL;

-- 指定用户表的字段
DEFINE FIELD name ON TABLE user TYPE object;
DEFINE FIELD name.first ON TABLE user TYPE string;
DEFINE FIELD name.last ON TABLE user TYPE string;
DEFINE FIELD email ON TABLE user TYPE string ASSERT string::is::email($value);

-- 在 email 字段上添加唯一索引，防止重复值
DEFINE INDEX email ON TABLE user COLUMNS email UNIQUE;

-- 当用户邮箱地址改变时创建一个新事件
DEFINE EVENT email ON TABLE user WHEN $before.email != $after.email THEN (
    CREATE event SET user = $value, time = time::now(), value = $after.email, action = 'email_changed'
);

5.4 图关系 (RELATE)

使用 RELATE 语句在记录之间创建图边连接。

示例：创建"写入"关系

sql 复制代码

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

5.5 权限控制 (PERMISSIONS)

为表定义细粒度的访问权限，控制用户对数据的选择、创建、更新和删除操作。

示例：定义 post 表的权限

sql 复制代码

DEFINE TABLE post SCHEMALESS
    PERMISSIONS
        FOR select
            -- 已发布的帖子可以被选择
            WHERE published = true
            -- 用户可以查看自己的所有帖子
            OR user = $auth.id
        FOR create, update
            -- 用户可以创建或更新自己的帖子
            WHERE user = $auth.id
        FOR delete
            -- 用户可以删除自己的帖子
            WHERE user = $auth.id
            -- 或者管理员可以删除任何帖子
            OR $auth.admin = true
;

5.6 嵌入式 JavaScript 函数

在数据库中编写自定义的 JavaScript 函数，将计算逻辑移至数据层。

示例：计算电影评分

sql 复制代码

CREATE film SET
    ratings = [
        { rating: 6, user: user:bt8e39uh1ouhfm8ko8s0 },
        { rating: 8, user: user:bsilfhu88j04rgs0ga70 },
    ],
    featured = function() {
        return this.ratings.filter(r => {
            return r.rating >= 7;
        }).map(r => {
            return { ...r, rating: r.rating * 10 };
        });
    }
;

6. 更多资源

官方文档： surrealdb.com/docs
教程： surrealdb.com/docs/tutori...
SurrealDB 大学： surrealdb.com/learn/funda...
GitHub 示例： github.com/surrealdb/e...
Docker Hub： hub.docker.com/r/surrealdb...
Ollama GUI： ollaman.com/

希望这份教程能帮助您快速上手 SurrealDB！