Clauge数据库模式完全指南:一个编辑器玩转5大数据库,AI懂你的表结构还能跨方言翻译SQL

原创2026-10-26 14:01:561,327 阅读

Clauge数据库模式完全指南:一个编辑器玩转5大数据库,AI懂你的表结构还能跨方言翻译SQL

Clauge 是一款面向开发者的 AI 超级应用,其 SQL 数据库模式用同一个编辑器就能连接 PostgreSQL、MySQL、SQLite、ClickHouse 和 Cloudflare D1 五大数据库引擎,内置的 SQL AI 能感知你的表结构(schema-aware),还能把查询语句跨方言翻译成目标引擎能跑的 SQL。下面这篇指南带你完整上手这套数据库模式。

Clauge 应用图标:AI 数据库超级应用 Clauge

为什么需要「一个客户端,所有引擎」

日常开发里,我们常常被拆散在多个数据库 GUI 之间:Postgres 一个工具、MySQL 一个工具、点查库又一个工具,配置和凭据到处重复。Clauge 的 SQL 模式(App 中的 04 模式)把这些全部收敛进同一个壳:

  • 统一编辑器:所有引擎共用同一个 CodeMirror SQL 编辑器和结果表格;
  • 统一 AI:每个引擎有调校好的专属 AI 提示词,生成「方言正确」的 SQL;
  • 共享 SSH 隧道:在 SSH 模式配置一次堡垒机,SQL 连接直接复用;
  • 本地优先:连接配置和查询脚本保存在本机 SQLite,可选加密云同步。

所有引擎的元数据(显示名、默认端口、解析器配置、标识符引号)集中在方言注册表中,Rust 端是唯一事实来源:

5大数据库支持一览:默认端口与连接方式

引擎 缩写 默认端口 连接方式 说明
PostgreSQL PG 5432 主机/端口 + 账号密码 支持 schema 命名空间
MySQL MY 3306 主机/端口 + 账号密码 标识符用反引号包裹
SQLite SL — 本地文件 免账号,直接打开文件
ClickHouse CH 8123 主机/端口 + 账号密码 HTTP 接口(非原生协议)
Cloudflare D1 D1 — HTTPS + API Token 无主机/端口和账号字段

💡 一个贴心细节:D1 连接时,通用的「主机/端口/用户名/密码」输入框会自动隐藏,换成 Account ID / Database ID / API Token 三个专属字段。连接弹窗会根据所选引擎智能调整表单,相关逻辑见 ConnectionDialog.svelte。

新建数据库连接:最快配置方法

新建连接只需几步:

  1. 在 SQL 模式导航栏(SqlNav.svelte)点击新建连接;
  2. 选择引擎(PG / MY / SL / CH / D1),表单自动切换;
  3. 填入主机、端口(会自动填入默认值,见 defaultPortFor)与账号;
  4. 需要走堡垒机时,选择一个 SSH profile——连接配置中的 sshProfileId 字段会指示运行时通过该隧道转发流量(定义见 types.ts);
  5. 保存后即可在任意 SQL 脚本标签页的下拉框中选用。

连接配置结构非常直白,完整字段可见 SqlConnectionConfig,SSH 隧道支持由迁移脚本 6_ssh_tunnel_support_for_db_connections.sql 建立。

写查询、看结果:编辑器与结果面板

SQL 脚本编辑器(QueryEditor.svelte)按当前引擎加载对应的语法高亮 profile(如 MySQL 引擎用 MySQL 方言,ClickHouse 回退到最接近的 PostgreSQL profile)。执行结果分为两类呈现:

  • SELECT / 未知:渲染表格网格(列名 + 行数据);
  • DML / DDL:渲染影响行数、开始/结束时间等统计卡片。

这个「动词分类」由后端显式返回 queryKind(select | dml | ddl | unknown),避免空结果集 SELECT 被误判(见 QueryKind 注释)。结果表格组件在 ResultsTable.svelte,执行服务在 sqlExecuteService.ts。

🔍 一个隐藏福利:你习惯的 psql / sqlite3 元命令也能用。输入 \dt 或 .tables 这类前缀命令时,psqlMeta.ts 会自动把它翻译成等价的 SELECT 标准 SQL 再发给数据库,不需要你手写查系统表的语句。

浏览表结构:Table Explorer 让 schema 一目了然

左侧的表浏览器(TableExplorer.svelte)按数据库 → 表 → 列逐级展开:

  • 表级信息:名称、类型(TABLE / VIEW)、行数;PostgreSQL 额外展示所属 schema(TableInfo);
  • 列级信息:列名、数据类型、是否可空、是否主键、默认值(ColumnInfo)。

这些信息不只是给你看的——它们会被直接注入 AI 的上下文,这正是「AI 懂你的表结构」的关键。

AI 懂你的表结构:SQL AI 的 9 个专属工具

Clauge 的 SQL AI 不是一个通用聊天机器人,它带着一组真实可调用的数据库工具(清单见 SQL_TOOLS):

工具 用途
list_connections / list_databases 列出已保存连接、列出服务器上的库
list_tables / describe_table / list_schemas 探索库、表、列(PostgreSQL 可到 schema 级)
get_schema 一次调用拿整个库的完整表结构
execute_query 真正执行查询并返回结果
apply_query 把 SQL 写入编辑器(不执行)
explain_query 跑 EXPLAIN ANALYZE 看执行计划

使用逻辑很讲究,系统提示词(SQL_SYSTEM_PROMPT)规定:

  • 问数据就执行:「有多少用户?」「最近的订单是什么?」AI 会直接 execute_query 并给出答案,而不是甩给你一段 SQL 模板;
  • 要 SQL 才写 SQL:只有你明确说「帮我写一条查询」时,它才通过 apply_query 把语句写进编辑器;
  • 不猜列名:不知道 schema 时,它必须先 list_tables + describe_table 验证真实的表名和列名,绝不凭空假设 name、email 这类字段存在。

上下文如何采集(当前标签页绑定的连接、数据库、查询文本、最近结果、schema)由 gatherSqlContext 负责,它会先判断 target_status(已就绪 / 未选库 / 未绑定 / 无 SQL 标签),避免 AI 盲目操作。

智能报错:从「报错」到「告诉我哪里错了」

执行失败时,AI 工具层会把原始错误分类为:瞬时故障、列不存在、表不存在、权限不足、语法错误、连接断开(分类逻辑见 classify_sql_error):

  • 列不存在 → 自动去 describe_table 找真实列名;
  • 表不存在 → 用模糊相似度匹配给出「你是不是想查 xxx」候选(similar_names);
  • 瞬时故障(超时、死锁、5xx)→ 允许有限次重试,且只在补充信息后重试。

错误信息会原样引用数据库原文展示,不会含糊其辞。

跨方言翻译 SQL:Postgres 语句一键改写为 MySQL

多引擎混用最常见的痛点是方言差异:Postgres 的 LIMIT/OFFSET、:: 类型转换、双引号标识符,拿到 MySQL 或 ClickHouse 就报错。

Clauge 的解法是「方言感知的 AI 改写」:

  1. 上下文里始终携带当前引擎的 driver 标识(context.ts 注入),提示词明确要求「按 driver 生成方言正确的 SQL」;
  2. 你只需对 AI 说「把这条查询改写成 MySQL 版」,它会读取你当前的查询与目标引擎,重写后通过 apply_query 放进编辑器;
  3. 标识符引号差异(MySQL 用反引号,其他引擎用双引号)等细节由方言注册表统一定义(identifierQuote),UI 生成的 DDL 也随之适配。

也就是说,Postgres → MySQL → ClickHouse 的翻译不靠人肉记忆语法差异,AI 结合你的真实 schema 完成改写,写出来的语句直接可以跑。

进阶技巧:批量执行、取消与云同步

  • 批量执行:多段语句按批次执行(sqlExecuteBatch),每段结果独立记录耗时与影响行数;
  • 运行中取消:执行中的查询携带 queryId(InFlight),支持一键取消并显示已耗时;
  • 脚本持久化:查询以 SqlScript 形式保存到本地(含连接与库绑定,见 SqlScript),下次打开自动回填;
  • Atlas 画布:把 SQL 标签拖进 Atlas 空间画布,瓦片自带 Run 按钮 + 结果表 + 连接选择器,多库并排对比非常顺手(canvas-adapter.ts);
  • 云同步:SQL 连接配置可随 Pro 同步跨机器,凭据默认不出设备(同步相关实现在 src-tauri/src/cloud/domains/sql.rs)。

总结

Clauge 的数据库模式用一份代码同时驾驭 5 大 SQL 引擎:统一编辑器、按方言智能适配的连接表单、能读懂 schema 的 AI、会分类报错的智能重试,以及跨方言翻译 SQL 的能力。如果你的日常在 Postgres、MySQL 和分析库之间反复横跳,这套「一个客户端,所有引擎」的体验值得试试。

核心源码导航:前端在 src/lib/modes/sql/(UI、方言表、AI 提示词),后端在 src-tauri/src/modes/sql/(连接池 client.rs、AI 工具 ai_tools.rs、ClickHouse/D1 专用客户端)。

登录后查看全文
Clauge