📦 Tabularis 详细部署教程

Tabularis 是一个开源桌面 SQL 工作区，支持 PostgreSQL、MySQL/MariaDB、SQLite 以及 15 种以上的数据库（如 DuckDB、ClickHouse、Redis、Firestore）。它内置了 MCP (模型上下文协议) 服务器，允许 Claude、Cursor 和 Devin 等 AI 代理直接读取你的数据库 Schema 并执行查询。

⚙️ 部署前准备

Tabularis 是一个桌面应用，不需要复杂的服务端部署。你只需要根据操作系统选择对应的安装方式即可。

  • 操作系统：Windows、macOS 或 Linux。
  • （可选）AI 功能：如果要使用 AI 驱动的 Text-to-SQL 或查询解释功能，需要准备 OpenAI、Anthropic、OpenRouter 等服务的 API Key，或配置本地的 Ollama 服务。
  • （可选）MCP 集成：如果要让 AI 代理（如 Claude Desktop、Cursor）连接，需安装对应的客户端。

🚀 安装 Tabularis

根据你的操作系统，选择以下任一官方推荐方式进行安装。

Windows

方式一：WinGet (推荐)

打开终端 (PowerShell 或 CMD)，运行：

1
winget install Debba.Tabularis

方式二：直接下载安装包

  1. 访问项目的 Releases 页面。
  2. 下载最新的 tabularis_x.x.x_x64-setup.exe 安装包。
  3. 运行下载的 .exe 文件，按照屏幕提示完成安装。

macOS

方式一：Homebrew (推荐)

1
brew install --cask tabularis

方式二：直接下载 (注意版本)

  • 从 v0.13.1 版本开始，安装包经过 Apple 签名和公证，可以直接打开。
  • 如果使用更早的版本，下载后可能需要：
    1. 在“系统设置 > 隐私与安全性”中，为 Tabularis 允许“辅助功能”访问。
    2. 如果从旧版本升级，需要先从辅助功能列表中移除旧的 Tabularis 条目，再添加新版本。
    3. 在终端运行 xattr -c /Applications/tabularis.app 移除扩展属性。

Linux

Tabularis 支持多种 Linux 包格式。

Snap (推荐)

1
sudo snap install tabularis

Flatpak

1
2
flatpak remote-add --if-not-exists flatpark https://dl.flatpark.org/flatpark.flatpakrepo
flatpak install flatpark dev.tabularis.Tabularis

AppImage

  1. 从 Releases 页面下载 .AppImage 文件。
  2. 赋予执行权限并运行：
1
2
chmod +x tabularis_x.x.x_amd64.AppImage
./tabularis_x.x.x_amd64.AppImage

Arch Linux (AUR)

如果你使用 Arch Linux，可以通过 AUR 安装：

1
yay -S tabularis-bin

🗄️ 配置存储与数据位置

Tabularis 的配置和连接信息存储在以下默认位置：

  • Linux：~/.config/tabularis/
  • macOS：~/Library/Application Support/tabularis/
  • Windows：%APPDATA%\tabularis\

你可以通过 Settings → Storage 或设置环境变量 TABULARIS_DATA_DIR 来更改此位置（例如，同步到云盘以实现多机共享连接）。已安装的插件始终保留在本地。

🔌 连接到数据库

  1. 启动 Tabularis，在主界面点击“新建连接”或“+”按钮。
  2. 选择数据库类型：PostgreSQL、MySQL/MariaDB 和 SQLite 是内置支持的。其他数据库（如 DuckDB、ClickHouse、Redis）需要先通过 Settings → Available Plugins 安装对应的驱动程序插件。
  3. 填写连接参数：主机、端口、用户名、密码、数据库名等。
  4. （可选）配置 SSH 隧道或设置连接的外观（图标、颜色）。
  5. 点击“测试连接”，成功后保存。

🤖 启用 AI 功能 (可选)

Tabularis 支持可选的 Text-to-SQL 和查询解释功能。

  1. 打开 Settings → AI。
  2. 选择你偏好的 AI 提供商：
    • 云端：OpenAI、Anthropic、MiniMax、OpenRouter 或任何 OpenAI 兼容的 API（如 Groq、Perplexity、Azure OpenAI）。
    • 本地：Ollama（无需 API Key，完全本地运行，保护隐私）。
  3. 填入对应的 API Key 或本地服务地址。
  4. 点击“保存”。之后，在 SQL 编辑器中选中文本，即可使用 AI 辅助功能。

🤝 集成 MCP 服务器 (让 AI 代理访问数据库)

Tabularis 内置了 MCP 服务器，可以让 AI 代理（如 Claude Desktop、Cursor、Devin）直接操作你的数据库。

1. 启动 MCP 服务器

在终端中运行以下命令：

1
tabularis --mcp

这会启动一个本地 MCP 服务进程。

2. 一键配置客户端

  1. 在 Tabularis 应用中，打开 Settings → MCP Server Integration。
  2. 你会看到支持一键配置的客户端列表（如 Claude Desktop、Cursor）。
  3. 点击对应客户端旁的 Install Config 按钮。Tabularis 会自动将配置写入客户端的配置文件中。
  4. 重启你的 AI 客户端。

3. 可用的 MCP 工具

一旦连接成功，你的 AI 代理可以使用以下工具：

  • list_connections：列出所有保存的数据库连接。
  • list_databases：列出特定连接下的所有数据库。
  • list_tables：列出连接中的表（可按 Schema 过滤）。
  • describe_table：获取表的完整 Schema（列、索引、外键）。
  • run_query：执行任意 SQL 查询并返回结果。

示例提示词

  • “显示我生产数据库中所有的表，并描述 orders 表的结构。”
  • “编写并运行一个查询，找出本月总订单价值最高的前 10 位客户。”
  • “检查 users 表是否有缺失的索引。”

🛠️ 从源码开发 (面向贡献者)

如果你想从源码构建或修改 Tabularis。

环境要求

  • Node.js (项目使用 Node 24)
  • pnpm
  • Rust (用于 Tauri 后端)

步骤

1
2
3
4
5
6
7
8
9
10
11
12
# 1. 克隆仓库
git clone https://github.com/TabularisDB/tabularis.git
cd tabularis

# 2. 安装前端依赖
pnpm install

# 3. 启动开发模式
pnpm tauri dev

# 4. 构建生产版本
pnpm tauri build

❓ 常见问题

  • Linux 下 AppImage 无法运行？
    • 确保已安装 FUSE (sudo apt install fuse)，并给文件添加了执行权限 (chmod +x)。
  • macOS 提示“无法验证开发者”？
    • 这是 macOS 的安全机制。如果是 v0.13.1 及以后版本，应已签名。如果是旧版，请在“系统设置 > 隐私与安全性”中点击“仍要打开”。
  • 找不到某个数据库的驱动？
    • 首先检查 Settings → Available Plugins，看看该数据库的插件是否已发布。如果没有，你可以在项目的 Issues 中请求，或者参考 plugins/PLUGIN_GUIDE.md 自行编写插件。
  • MCP 连接后 AI 代理无法执行查询？
    • 确保 Tabularis 正在运行 (以 tabularis --mcp 模式)，并且 AI 客户端的配置文件已正确指向该本地服务。
    • 检查 AI 客户端的配置文件中，MCP 服务器的地址和端口是否正确（通常是 http://127.0.0.1:端口）。

更详细的配置指南、插件开发教程和完整功能参考，请查阅 Tabularis 官方文档。