# free-db

**Repository Path**: gobkc/free-db

## Basic Information

- **Project Name**: free-db
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-16
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Free DB — 基于 GTK4 的数据库管理工具

Free DB 是一款使用 **Python 3 + GTK4（PyGObject）** 开发的图形化数据库管理软件。
**默认支持 PostgreSQL**，并通过插件机制支持 **MySQL、Redis、MongoDB**。
界面采用**扁平化、无边框暗红风格**（参考 free-music 设计语言）：左侧侧边栏 +
中央编辑/数据区 + **底部全宽 SQL 控制台**，全部操作使用自绘的 **SVG 图标按钮**
（`styles/icons/*.svg`，通过 librsvg 渲染并按主题着色）。

## 功能特性

- 连接管理（PostgreSQL 默认 + 动态插件）
- 数据库 / 表（集合 / 键空间）列表浏览
- 创建表、删除表、修改表结构（增 / 改 / 删字段）
- 表数据分页查看，支持过滤（WHERE）和字段选择
- 双击单元格编辑、新增行、删除行
- 任意 SQL / 命令执行，结果网格显示
- SQL 控制台（时间戳、状态、影响行数，支持清空 / 复制）
- 导入 `.sql` 文件（事务包裹）、导出表结构 + 数据为 `.sql`
- 快捷键：`Ctrl+Enter` 执行、`Ctrl+S` 导出、`Ctrl+F` 过滤

## 一、安装系统依赖（Debian / Ubuntu）

```bash
sudo apt update
sudo apt install python3 python3-gi gir1.2-gtk-4.0 gir1.2-rsvg-2.0 python3-cairo python3-psycopg2
# 可选：插件支持
sudo apt install python3-redis python3-pymongo
# MySQL 驱动（如需）
pip install mysql-connector-python
# 可选：PostgreSQL 客户端
sudo apt install postgresql-client
```

## 二、从源码运行

```bash
cd free-db
python3 main.py
# 或
make run
```

首次启动会在 `$HOME/free-db/config.json` 创建默认配置。

## 三、配置文件

路径：`$HOME/free-db/config.json`，由 `utils/config_manager.py` 管理。
保存连接、最近连接、插件开关与 UI 设置（页大小、字体等）。

## 四、插件机制

插件位于 `services/plugins/`，每个文件实现一个继承 `DatabaseBackend`
的后端类（如 `MySQLService`、`RedisService`、`MongoDBService`）。
启动时 `PluginManager` 自动扫描并按 `config.json` 中 `plugins` 开关加载。
连接对话框的"类型"下拉会动态列出可用后端。

- **MySQL**：与 PostgreSQL 兼容的 SQL / 表操作。
- **Redis**：keys 作为"表"，查看 / 编辑值，命令输入框执行 Redis 命令。
- **MongoDB**：列出数据库 / 集合，JSON 显示文档，执行 `db.coll.find({...})` 等。

不支持的操作（如 Redis 修改表结构）会弹出友好提示。

## 五、构建 Debian 软件包（.deb）

```bash
make deb
```

生成 `build/free-db_1.0.0_all.deb`。安装：

```bash
sudo apt install ./build/free-db_1.0.0_all.deb
# 或
sudo dpkg -i build/free-db_1.0.0_all.deb && sudo apt -f install
```

安装后运行：

```bash
free-db
```

`.deb` 通过 `Depends` 字段自动安装 `python3`、`python3-gi`、
`gir1.2-gtk-4.0`、`python3-psycopg2` 等依赖。

## 六、示例数据

`sql/init_sample.sql` 提供 PostgreSQL 示例表与数据，可通过：

```bash
psql -U postgres -d postgres -f sql/init_sample.sql
```

或在 Free DB 中使用"导入 SQL"执行。

## 七、运行测试

```bash
make test
# 或
python3 -m pytest tests/ -v
```

## 八、目录结构

```
free-db/
├── main.py              应用入口
├── Makefile             含 deb 打包目标
├── app/                 Gtk.Application + CSS 加载
├── context/             全局上下文
├── ui/                  窗口、面板、控件、对话框
├── handlers/            事件处理（与 UI 解耦）
├── services/            后端抽象 + PostgreSQL + 插件
├── styles/style.css     暗红扁平主题（无边框）
├── styles/icons/        SVG 图标资源
├── ui/icons.py          SVG 渲染 + 图标按钮工厂
└── utils/               配置、异步、日志、SQL 辅助
```

## 九、主题定制注意事项

### 弹窗标题栏（HeaderBar）去浅色边框

GTK4 窗口/对话框的 CSD（Client-Side Decoration）会渲染默认的浅色标题栏元素。
要彻底去掉弹窗 headerbar 两侧的浅色竖条，需在 CSS 中覆盖以下 GTK4 内部节点：

```css
/* 消除 dialog 窗口 headerbar 的浅色竖条 */
window.freedb headerbar,
window.freedb > headerbar {
    background-color: @surface;
    background-image: none;
    border: none;
    box-shadow: none;
    outline: none;
}
/* headerbar 内部 windowhandle / box 强制透明 */
window.freedb headerbar > windowhandle,
window.freedb headerbar > box,
window.freedb headerbar > * {
    background-color: transparent;
    background-image: none;
    border: none;
    box-shadow: none;
}
/* 彻底覆盖 windowhandle 内的 box 节点 */
window.freedb headerbar windowhandle > box {
    background-color: transparent !important;
    background-image: none !important;
    border: none !important;
}
```

关键点：
- GTK4 的 `headerbar` 内部有一个 `windowhandle` → `box` 节点链，默认会渲染浅色背景
- 需要用 `!important` 覆盖 GTK 内置主题的默认背景，但 `window.freedb` 类选择器已有足够特异性
- decoration 节点也需要同时设为透明（`background: transparent !important`）

## 许可证

MIT