Clauge数据库模式完全指南:一个编辑器玩转5大数据库,AI懂你的表结构还能跨方言翻译SQL
Clauge数据库模式完全指南:一个编辑器玩转5大数据库,AI懂你的表结构还能跨方言翻译SQL
Clauge 是一款面向开发者的 AI 超级应用,其 SQL 数据库模式用同一个编辑器就能连接 PostgreSQL、MySQL、SQLite、ClickHouse 和 Cloudflare D1 五大数据库引擎,内置的 SQL AI 能感知你的表结构(schema-aware),还能把查询语句跨方言翻译成目标引擎能跑的 SQL。下面这篇指南带你完整上手这套数据库模式。
为什么需要「一个客户端,所有引擎」
日常开发里,我们常常被拆散在多个数据库 GUI 之间:Postgres 一个工具、MySQL 一个工具、点查库又一个工具,配置和凭据到处重复。Clauge 的 SQL 模式(App 中的 04 模式)把这些全部收敛进同一个壳:
- 统一编辑器:所有引擎共用同一个 CodeMirror SQL 编辑器和结果表格;
- 统一 AI:每个引擎有调校好的专属 AI 提示词,生成「方言正确」的 SQL;
- 共享 SSH 隧道:在 SSH 模式配置一次堡垒机,SQL 连接直接复用;
- 本地优先:连接配置和查询脚本保存在本机 SQLite,可选加密云同步。
所有引擎的元数据(显示名、默认端口、解析器配置、标识符引号)集中在方言注册表中,Rust 端是唯一事实来源:
- 后端注册表:dialects.rs
- 前端镜像:dialects.ts
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。
新建数据库连接:最快配置方法
新建连接只需几步:
- 在 SQL 模式导航栏(SqlNav.svelte)点击新建连接;
- 选择引擎(PG / MY / SL / CH / D1),表单自动切换;
- 填入主机、端口(会自动填入默认值,见 defaultPortFor)与账号;
- 需要走堡垒机时,选择一个 SSH profile——连接配置中的
sshProfileId字段会指示运行时通过该隧道转发流量(定义见 types.ts); - 保存后即可在任意 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 改写」:
- 上下文里始终携带当前引擎的
driver标识(context.ts 注入),提示词明确要求「按 driver 生成方言正确的 SQL」; - 你只需对 AI 说「把这条查询改写成 MySQL 版」,它会读取你当前的查询与目标引擎,重写后通过
apply_query放进编辑器; - 标识符引号差异(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 专用客户端)。