Beekeeper Studio 连接 SurrealDB 完整指南：WebSocket/HTTP 连接、认证方式与当前功能支持现状

Beekeeper Studio 连接 SurrealDB 完整指南：WebSocket/HTTP 连接、认证方式与当前功能支持现状

【免费下载链接】beekeeper-studioModern and easy to use SQL client for MySQL, Postgres, SQLite, SQL Server, and more. Linux, MacOS, and Windows.项目地址: https://gitcode.com/GitHub_Trending/be/beekeeper-studio

Beekeeper Studio 是一款面向 MySQL、Postgres、SQLite、SQL Server 等多数据库的现代易用 SQL 客户端，在其连接类型列表中同样内置了对 SurrealDB 的支持（连接类型定义）。本文围绕官方文档 surrealdb.es.md 展开，详细讲解如何在 Beekeeper Studio 中通过ws/wss/http/https协议连接 SurrealDB 实例、各个连接字段的含义与认证方式，并结合仓库源码（连接表单、驱动注册、方言实现与数据库迁移）深入说明底层实现与当前支持边界。读完本文，你将能够独立完成 SurrealDB 连接配置、正确选择认证方式，并清楚了解哪些功能可用、哪些仍处于规划阶段。

一、连接 SurrealDB 的快速上手

按照官方文档的说法，连接一个 SurrealDB 实例非常简单：

1. 在新建连接界面中，从数据库类型下拉菜单里选择SurrealDB；
2. 依次填写协议（Protocol）、主机（Host）、端口（Port）、用户名（Username）和密码（Password）等字段；
3. 点击Conectar（连接）按钮完成连接。

对应的连接表单实现在 SurrealDBForm.vue，该表单顶部还会显示一条警告提示，说明当前 SurrealDB 支持仍处于 alpha 阶段（SurrealDB support is in alpha），并给出支持功能文档与问题反馈入口，方便使用者在遇到问题时快速上报。

从源码结构看，Beekeeper Studio 的 SurrealDB 驱动与连接类型注册于 数据库客户端注册表，其在连接类型枚举与下拉列表中均以surrealdb作为内部标识（见 types.ts 与 ConnectionTypes 列表）。

二、SurrealDB 连接参数详解

官方文档列出了连接 SurrealDB 实例所需的全部信息，下面逐项结合表单源码 SurrealDBForm.vue 进行说明：

需要特别说明的是：

• 协议是必选项。在 SurrealDBForm.vue 中，协议字段是一个下拉选择框，第一项为占位的 "Select a protocol..."（禁用且隐藏），实际可选项由源码中的protocols: ['http', 'https', 'ws', 'wss']提供（见 SurrealDBForm.vue），与官方文档列出的协议清单完全一致。
• 端口字段类型为数字。表单中端口输入框显式声明了type="number"（见 SurrealDBForm.vue），因此只接受数字输入。
• 用户名/密码与 Token 互斥显示。表单根据所选认证方式动态切换：当认证方式不是 Token 时显示"用户 + 密码"输入框；当选择 Token 认证时，则只显示 Token 输入框（见 SurrealDBForm.vue）。
• Namespace 与 Database 是附加字段。表单底部还提供命名空间（Namespace）与数据库（Database）两个输入框（见 SurrealDBForm.vue）。由于 SurrealDB 采用"命名空间 → 数据库 → 表"的三层逻辑组织方式，这两项用于在连接时定位到具体的数据域，其中数据库值对应连接配置中的defaultDatabase。

从连接配置的数据模型看，上述协议、认证方式、命名空间与 Token 均存储在surrealDbOptions对象中，其接口定义为（见 types.ts）：

export interface SurrealDBOptions { authType?: SurrealAuthType; protocol?: 'http' | 'https' | 'ws' | 'wss'; namespace?: string; token?: string; }

该字段通过数据库迁移 20250702_add_surrealdb_options.js 写入saved_connection与used_connection两张表（以text类型存储、默认值为'{}'），用于持久化 SurrealDB 专属的连接选项，兼容历史连接记录。

三、SurrealDB 认证方式（Authentication Method）

官方文档提到"从 SurrealDB 提供的多种认证方式中选择一种"，具体可选项定义在 types.ts 中。当前表单实际开放以下四种认证方式：

需要指出的是，源码中枚举还包含RecordAccess（记录级访问）与Anonymous（匿名访问）两种类型，但目前均被注释禁用（见 types.ts）。代码注释给出的原因是：RecordAccess需要更多实现工作，而Anonymous匿名模式"似乎不生效，且无法访问表或查询数据"。因此从源码结构看，当前可用的认证方式以 Root、Namespace、Database、Token 四类为准。

认证方式与输入框的联动逻辑体现在 SurrealDBForm.vue 的isTokenAuth计算属性中——当authType === SurrealAuthType.Token时，表单切换为纯 Token 输入模式。

四、源码视角：SurrealDB 方言与功能边界

除了连接表单，仓库中还包含 SurrealDB 的方言（dialect）定义 surrealdb.ts，它决定了客户端中关于 SurrealDB 的数据类型、SQL 转义与可用功能范围：

• 数据类型：支持string、text、number、int、float、decimal、bool、datetime、date、time、duration、uuid、object、array、bytes、any、null、record、geometry、option等类型（见 surrealdb.ts），其中string/text/number/decimal支持长度设置，默认长度分别为 255 与 10。
• 值转义：实现了surrealEscapeString、surrealEscapeValue等工具函数，能够对字符串做单引号转义、识别 record ID（形如表名:记录ID，对应正则RECORD_ID_REGEX）并保留其不加引号的原生形式，同时尝试将字符串自动转换为 JSON 对象/数组、布尔值与数字等原生类型。
• 功能禁用清单：通过disabledFeatures明确声明了当前未开放的能力（见 surrealdb.ts），包括手动提交事务（manualCommit）、结果内编辑（resultEditing）、AI Shell、表结构变更（alter 一切）、触发器（SurrealDB 使用 events 而非 triggers）、备份、排序规则、schema 编辑、事务、建表/删表、复合主键以及文件导入等。这与官方文档"Todavía pendiente（仍待实现）"清单在整体方向上一致，也解释了为什么某些菜单项在 SurrealDB 连接下不可用。

五、当前已支持的功能

官方文档明确列出，Beekeeper Studio 的 SurrealDB 支持目前处于早期 alpha 实现阶段，以下功能已经可用：

• 表数据视图（Table data view）：浏览表中的记录数据；
• 表数据排序与过滤（Table data sorting, filtering）：对表数据进行排序和条件过滤；
• 表结构视图（Table structure view）：针对 schemafull（完整模式）表可查看表结构；
• 实体侧边栏（Entity sidebar）：在侧边栏中浏览数据库实体（对应组件见 SurrealNamespaceDropdown.vue 与 CoreSidebar.vue）；
• 数据编辑（Editing data）：支持编辑表数据；
• 执行查询（Running queries）：可在查询编辑器中直接对数据库执行 SurrealQL/SQL 查询；
• 导出（Export）：支持将数据导出；
• SSH 隧道（SSH tunneling）：支持通过 SSH 隧道连接 SurrealDB 实例（连接配置中的通用高级选项，见表单中的CommonAdvanced组件）。

六、尚待实现的功能（TBD）

以下功能官方文档明确标注为"Todavía pendiente（仍待实现）"，在使用时需要注意规避：

• 导入（Import）：暂不支持从文件向 SurrealDB 导入数据；
• Schema 编辑（Schema Editing）：暂不支持修改表结构/模式；
• 备份/恢复（Backup/Restore）：暂不支持备份与恢复操作。

这一点也可以从方言的disabledFeatures配置中得到印证：importFromFile（文件导入）、alter（结构变更）、backup（备份）等能力在 SurrealDB 方言下均被显式禁用（见 surrealdb.ts）。

七、连接 SurrealDB 的注意事项

综合官方文档与仓库实现，连接 SurrealDB 时有以下几点值得留意：

1. alpha 阶段定位：官方文档明确说明"这是对 SurrealDB 支持的早期实现"，团队正在持续更新，建议定期关注文档与新版发布；连接表单也会以警告横幅提示当前支持状态（见 SurrealDBForm.vue）。
2. 协议选择影响底层通信：ws/wss走 WebSocket 通道，http/https走 HTTP 通道，两种通道适用于不同的 SurrealDB 部署形态（本地开发常用ws/http，生产环境建议使用带 TLS 的wss/https）；选择错误将导致无法连通。
3. 命名空间与数据库必须对应：SurrealDB 的逻辑层级是"命名空间（Namespace）→ 数据库（Database）→ 表"，连接时填写的 Namespace 与 Database 必须与实例中实际创建的一致，否则即使认证通过也可能无法看到目标数据。
4. 认证方式影响可访问范围：Root 拥有最高权限，Namespace/Database 级用户仅能在其授权范围内操作；选择 Token 认证时无需填写用户名密码，但 Token 本身应具备足够的权限。
5. 功能边界要心中有数：导入、Schema 编辑、备份/恢复等功能尚未就绪，涉及这些操作时需要通过 SurrealDB 官方工具或命令行完成。

结语

本文以官方文档 surrealdb.es.md 为核心，完整梳理了在 Beekeeper Studio 中连接 SurrealDB 的流程、连接参数、认证方式与功能支持现状，并结合仓库源码（连接表单 SurrealDBForm.vue、连接配置模型 types.ts、方言定义 surrealdb.ts 与数据库迁移 20250702_add_surrealdb_options.js）做了底层印证。虽然 SurrealDB 支持尚处 alpha 阶段，但表数据浏览、排序过滤、查询执行、数据编辑、导出与 SSH 隧道等核心能力已经可用，足以支撑日常开发调试；后续随着导入、Schema 编辑与备份恢复等能力补齐，Beekeeper Studio 对 SurrealDB 的支持将更加完整。

【免费下载链接】beekeeper-studioModern and easy to use SQL client for MySQL, Postgres, SQLite, SQL Server, and more. Linux, MacOS, and Windows.项目地址: https://gitcode.com/GitHub_Trending/be/beekeeper-studio