surrealdb-cli

SurrealDB CLI

用于驱动 surreal 命令行二进制文件的技能——SurrealDB 的一体化工具，可用于运行服务、查询数据以及导入和导出数据。

此技能涵盖 surreal 二进制文件本身的操作。要编写通过它运行的 SurrealQL，请使用 surrealql 技能；要进行声明式架构迁移和类型生成，请使用 surrealkit 技能。

何时使用此技能

遇到以下情况时，请参考这些指南：

• 在本地或容器中启动 SurrealDB 服务（surreal start）
• 打开 SQL shell，或从文件传入查询（surreal sql）
• 导入或导出数据库，以进行备份、填充数据或迁移（surreal import / surreal export）
• 在脚本或 CI 中检查服务是否可用（surreal is-ready）
• 升级二进制文件，或在升级后修复磁盘存储（surreal upgrade / surreal fix）
• 导入或导出 SurrealML 模型（surreal ml）

安装

方法	命令
curl（macOS / Linux）	curl -sSf https://install.surrealdb.com | sh
Windows（PowerShell）	iwr https://windows.surrealdb.com -useb | iex
Homebrew	brew install surrealdb/tap/surreal
Docker	docker run --rm --pull always -p 8000:8000 surrealdb/surrealdb:latest start

使用 surreal version 验证安装。生产环境请固定使用特定镜像标签（而非 latest）。当前支持的安装方式请参阅安装文档。

命令一览

命令	用途	参考
surreal start [PATH]	使用选定的存储后端运行数据库服务	start.md
surreal sql	交互式 REPL 或通过管道进行非交互式查询	sql.md
surreal import <FILE>	将 SurrealQL 脚本加载到数据库中	import-export.md
surreal export [FILE]	将数据库转储为 SurrealQL（写入文件或标准输出）	import-export.md
surreal is-ready	在服务接受连接时以状态码 0 退出（别名 isready）	maintenance.md
surreal version	输出本地工具和远程服务的版本	maintenance.md
surreal upgrade	将二进制文件替换为较新的版本	maintenance.md
surreal fix [PATH]	将磁盘存储迁移为当前格式	maintenance.md
surreal ml <sub>	导入 / 导出 SurrealML 模型	maintenance.md

surreal validate（SurrealQL 文件检查）和格式化功能由 surrealql 技能介绍。较新的子命令（mcp、module）也已推出——运行 surreal help 和 surreal <command> --help，以确认已安装版本支持的命令。

连接标志和环境变量

sql、import、export 和 ml 使用相同的连接标志。每个标志都有对应的 SURREAL_* 环境变量作为回退值；显式指定的标志优先。

标志（别名）	环境变量	说明
-e, --endpoint	—	sql 使用 ws://localhost:8000；import / export 使用 http://localhost:8000
--namespace（--ns）	SURREAL_NAMESPACE	import / export / ml 必填
--database（--db）	SURREAL_DATABASE	import / export / ml 必填
-u, --username（--user）	SURREAL_USER
-p, --password（--pass）	SURREAL_PASS
-t, --token	SURREAL_TOKEN	JWT；使用此项代替用户名和密码
--auth-level	SURREAL_AUTH_LEVEL	root（默认值）、namespace / ns 或 database / db

请通过环境变量传递密钥，而不要使用标志，以免密钥泄露到 shell 历史记录或进程列表中。

快速开始

# 1. Start an authenticated in-memory server (foreground)
surreal start --user root --pass root memory

# 2. In another shell, open the SQL REPL on namespace/database "main"
surreal sql --endpoint ws://localhost:8000 \
  --user root --pass root --ns main --db main --pretty

# 3. Load a dump into that database
surreal import --endpoint http://localhost:8000 \
  --user root --pass root --ns main --db main backup.surql

规则与约定

• 默认启用身份验证。 surreal start 需要 --user/--pass；仅对临时本地实例使用 --unauthenticated。
• 谨慎选择存储后端。 memory（默认值）是临时存储——退出后数据会消失。使用 rocksdb:/surrealkv:// 实现持久化，使用 tikv:// 连接分布式集群。请参阅 start.md。
• 导出默认写入标准输出。 surreal export 会写入 -（标准输出），除非你指定文件路径；请相应地重定向或使用管道。
• 在 CI 中使用 is-ready 进行检查。 在服务器接受连接之前，它会返回非零退出代码——非常适合用于健康检查和脚本。
• 主要版本升级后运行 fix，前提是服务器报告存储版本不兼容；运行时将其指向与 start 相同的 PATH。
• CLI 会不断演进。 请对照已安装版本的 surreal <command> --help 确认标志和子命令；本技能对应 v3.x。

参考资料

• 运行服务器和存储后端 — references/start.md
• 交互式查询和管道查询 — references/sql.md
• 导入和导出数据 — references/import-export.md
• 版本控制、升级、就绪状态、修复和 ML 模型 — references/maintenance.md