# biu-sql

**Repository Path**: wangxy202012/biu-sql

## Basic Information

- **Project Name**: biu-sql
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-06
- **Last Updated**: 2026-08-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <img src="public/logo-sm.png" width="120" height="120" />
</div>

# Capri

一款为开发者打造的轻量级跨平台数据库客户端，基于 Tauri 和 React 构建。

**支持语言：** 英语、意大利语、西班牙语、简体中文

<div align="center">
  <img src="website/public/img/overview.png" width="80%" alt="Capri" />
</div>

## 目录

- [功能特性](#功能特性)
  - [连接管理](#连接管理)
  - [数据库浏览器](#数据库浏览器)
  - [SQL 编辑器](#sql-编辑器)
  - [快捷键](#快捷键)
  - [可视化查询构建器](#可视化查询构建器)
  - [数据表格](#数据表格)
  - [日志](#日志)
  - [插件系统](#插件系统)
  - [授权（License）](#授权license)
  - [代码片段](#代码片段)
- [配置存储](#配置存储)
  - [AI 功能（可选）](#ai-功能可选)
  - [MCP 服务器 — AI Agent 集成](#mcp-服务器--ai-agent-集成)
- [技术栈](#技术栈)
- [开发](#开发)
- [许可证](#许可证)

## 功能特性

### 连接管理

- 支持 **MySQL/MariaDB**、**PostgreSQL**（支持多 Schema）和 **SQLite**。
- **多数据库选择：** 单个连接中可选择多个 MySQL/MariaDB 数据库，每个数据库在侧边栏中以独立的可折叠节点显示。
- 保存、管理和克隆连接配置，安全地本地持久化存储。
- **全新连接页面：** 支持网格和列表视图，实时搜索，各数据库驱动使用官方品牌图标和配色。
- **在编辑器中打开：** 右键点击侧边栏中的任意连接，可通过右键菜单直接在编辑器中打开。
- 从连接管理器管理 **SSH 连接**。
- 支持将密码安全存储在系统 **Keychain** 中。
- **SSH 隧道**支持自动就绪检测。

### 数据库浏览器

- **树形视图：** 浏览表、列、键、外键、索引、视图和存储过程。
- **内联编辑：** 直接在侧边栏中编辑表和列的属性。
- **ER 图：** 交互式实体关系可视化（支持平移、缩放、布局），可选择性地生成表关系图。
- **右键操作：** 查看数据、统计行数、修改表结构、复制/删除表。
- **视图支持：** 浏览、检查和查询数据库视图，支持完整元数据。
- **存储过程：** 查看和管理存储过程与函数，包含参数详情。
- **快速元数据加载：** 并行获取 Schema 信息。
- **SQL 转储与导入：** 一键导出和恢复数据库。

### SQL 编辑器

- **Monaco 编辑器：** 语法高亮和自动补全。
- **标签页界面：** 每个标签页隔离独立的数据库连接。
- **分屏视图：** 在可调整大小的分屏布局中并排打开多个数据库连接。
- **多种执行方式：** 支持运行完整脚本、选中内容或单条语句。
- **保存查询：** 持久化常用 SQL 查询。
- **AI 助手浮层：** 编辑器中直接显示 AI 辅助按钮。

### 快捷键

- **内置快捷键：** 导航、编辑器和数据表格操作（如 `Ctrl+B` 切换侧边栏，`Ctrl+T` 新建标签页，`Ctrl+→/←` 翻页）。
- **完全自定义：** 在 **设置 → 快捷键** 中重新映射任何未锁定的快捷键 — 按下组合键即可录制，点击 ↺ 可重置。
- **平台自适应：** macOS 使用 `Cmd`，Windows/Linux 使用 `Ctrl`。
- **可视化提示：** 在侧边栏中按住 `Ctrl+Shift` 显示数字标签（1–9），快速切换连接。
- **持久化覆盖：** 保存至应用配置目录的 `keybindings.json` 文件中，也可手动编辑。

### 可视化查询构建器

- **拖拽操作：** 使用 ReactFlow 可视化构建查询。
- **可视化 JOIN：** 连接表以创建关系。
- **高级逻辑：** WHERE/HAVING 过滤、聚合函数（COUNT, SUM, AVG）、排序和限制。
- **实时 SQL：** 即时生成对应 SQL 代码。

### 数据表格

- **内联和批量编辑：** 修改单元格并一次性提交多个更改。
- **行管理：** 创建、删除和选择多行。
- **复制选中行：** 将选中内容直接导出到剪贴板。
- **导出：** 将结果保存为 CSV 或 JSON 格式。
- **智能上下文：** 聚合查询自动切换为只读模式，普通表自动启用编辑模式。
- **空间数据支持：** 初步支持 MySQL 的 GEOMETRY 类型，支持原生 SQL 空间函数。

### 日志

- **实时监控：** 在设置中直接查看应用日志。
- **级别过滤：** 按 DEBUG、INFO、WARN 或 ERROR 级别过滤。
- **内存缓冲：** 可配置的日志保留策略。
- **查询展开：** 在日志中自动展开和检查 SQL 查询。
- **导出日志：** 将日志保存为 `.log` 文件，便于调试或审计。
- **开关控制：** 启用/禁用日志记录和调整缓冲区大小，无需重启。
- **CLI 调试模式：** 使用 `capri --debug` 启动，从启动时即开启详细日志（包含 SQLx 内部查询）。

### 插件系统

Capri 支持**外部插件系统**扩展数据库支持。插件是独立的可执行文件，通过 **JSON-RPC 2.0 协议**经 stdin/stdout 与应用通信，可用任何语言编写。

- **安装插件：** 在 **设置 → 可用插件** 中浏览和安装社区驱动 — 无需重启。
- **管理驱动：** 在 **设置 → 已安装驱动** 中查看所有已注册驱动（内置和插件），一键卸载插件。
- **任意数据库：** 通过编写或安装插件，添加对 DuckDB、MongoDB 或其他数据库的支持。
- **插件注册表：** 官方插件列在 [`plugins/registry.json`](./plugins/registry.json) 中。
- **开发指南：** 参见 [`plugins/PLUGIN_GUIDE.md`](./plugins/PLUGIN_GUIDE.md)，用任意语言构建自己的驱动。

### 授权（License）

Capri 内置授权管理，区分免费版与专业版（Pro）：

- **激活方式：** 在 **设置 → License** 中输入激活码激活，或前往账户站点注册 / 登录 / 管理订阅与套餐。
- **功能额度：** 对保存的连接数、编辑器标签页数、数据库操作次数、保存的查询数等设置上限，超出时提示升级专业版。
- **状态管理：** 显示当前套餐、激活状态、设备 ID、许可证 ID、激活与过期时间；支持宽限期（grace period）与一键刷新授权状态。

### 代码片段

在 **设置 → 代码片段** 中定义可展开为 SQL 模板的快捷缩写（snippet）。在编辑器里输入缩写即可快速插入常用 SQL 片段，提升日常查询效率。

## 配置存储

配置文件存储在 `~/.config/capri/`（Linux）、`~/Library/Application Support/capri/`（macOS）或 `%APPDATA%\capri\`（Windows）。

- `connections.json`：连接配置。
- `saved_queries.json`：已保存的 SQL 查询。
- `config.json`：应用设置（主题、语言、每页行数）。
- `themes/`：自定义主题。
- `preferences/`：每个连接的编辑器偏好设置（标签页、查询、布局）。

### 编辑器偏好设置

Capri 会自动为每个数据库连接保存编辑器状态。重新打开连接时，会恢复之前打开的标签页及其查询内容。

**存储位置：** `~/.config/capri/preferences/{connectionId}/preferences.json`

**保存的内容：**

- 标签页标题和类型（控制台、表、可视化查询）
- SQL 查询和查询参数
- 当前活动表和已选列
- 筛选、排序和限制条件
- 可视化查询构建器的流程状态
- 编辑器可见性状态

**不保存的内容：**

- 查询结果（需要重新执行查询）
- 错误信息
- 执行时间
- 未提交的编辑或删除
- 加载状态

这种方式确保快速启动的同时，跨会话保留您的工作区布局。

### `config.json` 选项

- `theme`：主题 ID（如 `"capri-dark"`、`"monokai"`）。
- `fontFamily`：编辑器字体系列。
- `fontSize`：编辑器字体大小（px）。
- `language`：`"auto"`、`"en"`（英语）、`"it"`（意大利语）、`"es"`（西班牙语）、`"zh"`（简体中文）。
- `resultPageSize`：默认每页行数。
- `aiEnabled`：启用/禁用 AI 功能。
- `customRegistryUrl`：自定义插件注册表 URL（覆盖默认的官方注册表）。

### 自定义 AI 模型覆盖

您可以通过编辑 `config.json` 并添加 `aiCustomModels` 对象来覆盖或添加自定义 AI 模型：

```json
{
  "resultPageSize": 1000,
  "language": "en",
  "aiEnabled": true,
  "aiProvider": "openai",
  "aiCustomModels": {
    "openai": ["gpt-4o", "gpt-4-turbo", "gpt-3.5-turbo", "gpt-5-preview"],
    "anthropic": ["claude-3-opus-20240229", "claude-3-sonnet-20240229"],
    "minimax": ["MiniMax-M2.7", "MiniMax-M2.7-highspeed"],
    "openrouter": ["google/gemini-pro-1.5", "meta-llama/llama-3-70b-instruct"]
  }
}
```

### AI 功能（可选）

可选的文本转 SQL 和查询解释功能，由以下服务提供支持：

- **OpenAI**
- **Anthropic**
- **MiniMax**（MiniMax-M2.7 和 MiniMax-M2.7-highspeed，204K 上下文）
- **OpenRouter**（访问 Gemini、Llama、DeepSeek 等）
- **Ollama**（本地 LLM 支持，完全隐私）
- **OpenAI 兼容 API**（Groq、Perplexity、Azure OpenAI、LocalAI 等）

#### 本地 AI（Ollama）

在设置中选择 "Ollama" 作为提供商。Capri 会自动检测运行在端口 `11434`（可配置）上的本地模型。无需 API 密钥。

#### OpenAI 兼容 API

选择 "OpenAI Compatible" 作为提供商，可连接任何实现 OpenAI API 格式的服务。在设置中配置自定义端点 URL 和模型名称。例如：

- **Groq**：`https://api.groq.com/openai/v1`
- **Perplexity**：`https://api.perplexity.ai`
- **本地服务器**：`http://localhost:8000/v1`

#### 动态模型获取

Capri 会自动从已配置的提供商获取最新可用模型。

- **刷新：** 点击设置中的刷新图标，从 API 更新模型列表。
- **缓存：** 模型列表本地缓存 24 小时，确保快速启动。
- **验证：** 当所选模型在当前提供商中不可用时，会提供可视化反馈。

### MCP 服务器 — AI Agent 集成

Capri 内置了 **MCP（Model Context Protocol）服务器**，允许 AI Agent 直接从聊天界面读取您的数据库 Schema 并执行查询。

```bash
capri --mcp
```

#### 支持的客户端

| 客户端 | 一键安装 | 手动配置 |
|--------|----------|----------|
| **Claude Desktop** | 支持（设置 → MCP） | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Cursor** | 支持（设置 → MCP） | `~/.cursor/mcp.json` |
| **Windsurf** | 支持（设置 → MCP） | `~/.codeium/windsurf/mcp_config.json` |

#### 一键配置

1. 在 Capri 中打开 **设置 → MCP 服务器集成**
2. 点击对应 AI 客户端旁的 **安装配置**
3. 重启客户端

#### 手动配置

在客户端的 MCP 配置文件中添加以下内容：

```json
{
  "mcpServers": {
    "capri": {
      "command": "/path/to/capri",
      "args": ["--mcp"]
    }
  }
}
```

#### 可用工具

连接成功后，您的 AI Agent 可以：

| 工具 | 描述 |
|------|------|
| `list_connections` | 列出所有已保存的数据库连接 |
| `list_tables` | 列出连接中的表（支持 Schema 过滤） |
| `describe_table` | 获取完整的表结构：列、索引、外键 |
| `run_query` | 执行任意 SQL 查询并返回结果 |

#### 示例提示

> "显示我生产数据库中的所有表，并描述 `orders` 表的结构"

> "编写并执行一个查询，找出本月订单总金额排名前 10 的客户"

> "检查 `users` 表是否有缺失的索引"

## 技术栈

- **前端：** React 19、TypeScript、Tailwind CSS v4。
- **后端：** Rust、Tauri v2、SQLx。

## 开发

### 环境搭建

```bash
pnpm install
pnpm tauri dev
```

### 构建

```bash
pnpm tauri build
```

## 许可证

本项目基于 [Apache License 2.0](./LICENSE) 开源。