ChartDB 数据库可视化工具使用指南

1. 框架概述

ChartDB 是一个功能强大的开源数据库可视化工具，支持多种数据库系统，能够快速将数据库结构转换为直观的图表。该工具基于 React + TypeScript + Vite 构建，提供了现代化的 Web 界面和丰富的功能特性。

1.1 核心特性

• 多数据库支持：PostgreSQL、MySQL、SQLite、SQL Server、MariaDB、ClickHouse、CockroachDB
• 智能导入：通过单一查询快速获取数据库结构
• AI 驱动导出：支持跨数据库迁移的 DDL 脚本生成
• 交互式编辑：直观的图表编辑和自定义功能
• 多种导出格式：SQL、DBML、图片、JSON 等

1.2 技术架构

• 前端框架：React 18 + TypeScript
• 构建工具：Vite
• UI 组件：Radix UI + Tailwind CSS
• 图表引擎：React Flow (XYFlow)
• 状态管理：React Context + Hooks
• 国际化：i18next

2. 安装与部署

2.1 本地开发环境

# 克隆项目
git clone https://github.com/chartdb/chartdb.git
cd chartdb

# 安装依赖
npm install

# 启动开发服务器
npm run dev

2.2 Docker 部署

# 使用预构建镜像
docker run -e OPENAI_API_KEY=<YOUR_OPEN_AI_KEY> -p 8080:80 ghcr.io/chartdb/chartdb:latest

# 自定义构建
docker build -t chartdb .
docker run -e OPENAI_API_KEY=<YOUR_OPEN_AI_KEY> -p 8080:80 chartdb

2.3 生产环境构建

# 基础构建
npm run build

# 启用 AI 功能
VITE_OPENAI_API_KEY=<YOUR_OPEN_AI_KEY> npm run build

3. 核心功能详解

3.1 数据库导入

ChartDB 支持三种导入方式：

3.1.1 数据库连接导入

通过执行特定的元数据查询语句获取数据库结构：

PostgreSQL 示例：

SELECT 
    json_build_object(
        'database_name', current_database(),
        'version', version(),
        'tables', (
            SELECT json_agg(
                json_build_object(
                    'schema', schemaname,
                    'table', tablename,
                    'type', 'table'
                )
            )
            FROM pg_tables 
            WHERE schemaname NOT IN ('information_schema', 'pg_catalog')
        ),
        'columns', (
            SELECT json_agg(
                json_build_object(
                    'schema', c.table_schema,
                    'table', c.table_name,
                    'name', c.column_name,
                    'type', c.data_type,
                    'ordinal_position', c.ordinal_position,
                    'nullable', c.is_nullable = 'YES',
                    'default', c.column_default,
                    'comment', col_description(
                        (c.table_schema||'.'||c.table_name)::regclass::oid, 
                        c.ordinal_position
                    )
                )
            )
            FROM information_schema.columns c
            WHERE c.table_schema NOT IN ('information_schema', 'pg_catalog')
        ),
        'pk_info', (
            SELECT json_agg(
                json_build_object(
                    'schema', tc.table_schema,
                    'table', tc.table_name,
                    'column', kcu.column_name
                )
            )
            FROM information_schema.table_constraints tc
            JOIN information_schema.key_column_usage kcu 
                ON tc.constraint_name = kcu.constraint_name
            WHERE tc.constraint_type = 'PRIMARY KEY'
                AND tc.table_schema NOT IN ('information_schema', 'pg_catalog')
        ),
        'fk_info', (
            SELECT json_agg(
                json_build_object(
                    'schema', tc.table_schema,
                    'table', tc.table_name,
                    'column', kcu.column_name,
                    'foreign_key_name', tc.constraint_name,
                    'reference_schema', ccu.table_schema,
                    'reference_table', ccu.table_name,
                    'reference_column', ccu.column_name,
                    'fk_def', tc.constraint_name
                )
            )
            FROM information_schema.table_constraints tc
            JOIN information_schema.key_column_usage kcu 
                ON tc.constraint_name = kcu.constraint_name
            JOIN information_schema.constraint_column_usage ccu 
                ON ccu.constraint_name = tc.constraint_name
            WHERE tc.constraint_type = 'FOREIGN KEY'
                AND tc.table_schema NOT IN ('information_schema', 'pg_catalog')
        ),
        'indexes', (
            SELECT json_agg(
                json_build_object(
                    'schema', schemaname,
                    'table', tablename,
                    'name', indexname,
                    'definition', indexdef
                )
            )
            FROM pg_indexes
            WHERE schemaname NOT IN ('information_schema', 'pg_catalog')
        )
    );

3.1.2 DDL 脚本导入

直接粘贴 CREATE TABLE 等 DDL 语句，ChartDB 会自动解析表结构。

3.1.3 DBML 文件导入

支持导入 DBML (Database Markup Language) 格式的数据库定义文件。

3.2 图表编辑功能

3.2.1 表格操作

• 添加/删除表格：通过拖拽或菜单操作
• 字段管理：支持添加、删除、修改字段属性
• 数据类型：自动识别和转换不同数据库的数据类型
• 约束设置：主键、外键、唯一性约束等

3.2.2 关系管理

• 外键关系：自动识别和可视化外键关联
• 关系线：支持自定义关系线的样式和标签
• 依赖关系：视图与表之间的依赖关系展示

3.2.3 布局与样式

• 自动布局：智能排列表格位置
• 颜色主题：支持亮色和暗色主题
• 过滤器：按表名、字段类型等条件筛选显示
• 缩放和平移：支持画布的缩放和平移操作

3.3 导出功能

3.3.1 SQL 导出

支持导出为多种数据库的 DDL 脚本：

// 导出 PostgreSQL 脚本
const sqlScript = exportBaseSQL({
    diagram: currentDiagram,
    targetDatabaseType: DatabaseType.POSTGRESQL
});

3.3.2 DBML 导出

生成标准的 DBML 格式文件：

// 导出 DBML
const dbmlContent = exportDBML(diagram);

3.3.3 图片导出

支持导出为 PNG、SVG 等图片格式：

// 导出图片
const exportImage = async (format: 'png' | 'svg') => {
    const element = document.getElementById('canvas');
    const dataUrl = await htmlToImage.toPng(element);
    // 下载图片
};

3.3.4 JSON 导出

保存完整的图表配置，便于后续编辑和分享。

4. 高级功能

4.1 AI 辅助功能

ChartDB 集成了 OpenAI API，提供智能的数据库迁移建议：

# 配置 OpenAI API
VITE_OPENAI_API_KEY=your_api_key_here

4.2 版本控制与历史记录

• 撤销/重做：支持操作的撤销和重做
• 历史记录：保存编辑历史，支持版本回滚
• 变更对比：可视化显示不同版本间的差异

4.3 协作功能

• 项目分享：生成可分享的链接
• 权限管理：支持只读和编辑权限设置
• 实时同步：多人协作编辑支持

5. 实际应用场景

5.1 数据库设计

• 新项目的数据库结构设计
• 现有数据库结构的可视化分析
• 数据库重构和优化规划

5.2 团队协作

• 开发团队间的数据库设计讨论
• 数据库文档的生成和维护
• 新成员的数据库结构培训

5.3 系统集成

• 微服务架构的数据库关系梳理
• 数据仓库的 ETL 流程设计
• 数据库迁移方案的制定

6. 最佳实践

6.1 性能优化

• 大型数据库建议分批导入
• 使用过滤器减少同时显示的表数量
• 定期清理不需要的历史版本

6.2 数据安全

• 生产环境数据库谨慎使用连接导入
• 敏感信息在导出前进行脱敏处理
• 定期备份重要的图表配置

6.3 团队协作

• 建立统一的命名规范
• 使用标签和颜色进行分类管理
• 定期进行图表审查和更新

7. 故障排除

7.1 常见问题

导入失败

• 检查数据库连接权限
• 验证 SQL 查询语法
• 确认数据库版本兼容性

导出错误

• 检查目标数据库类型设置
• 验证字段类型映射
• 确认约束关系完整性

性能问题

• 减少同时显示的表数量
• 使用过滤器优化显示
• 检查浏览器内存使用

7.2 调试技巧

// 启用调试模式
localStorage.setItem('debug', 'true');

// 查看图表数据结构
console.log('Diagram:', currentDiagram);

// 检查导入的元数据
console.log('Metadata:', parsedMetadata);

8. 扩展开发

8.1 自定义组件

ChartDB 提供了丰富的组件系统，支持自定义扩展：

// 自定义表格组件
const CustomTableNode: React.FC<TableNodeProps> = (props) => {
    return (
        <div className="custom-table">
            {/* 自定义表格样式 */}
        </div>
    );
};

8.2 插件系统

通过插件机制扩展功能：

// 注册自定义导出器
const customExporter = {
    name: 'Custom Format',
    export: (diagram: Diagram) => {
        // 自定义导出逻辑
        return customFormat;
    }
};

9. 总结

ChartDB 是一个功能强大、易于使用的数据库可视化工具，特别适合：

• 开发团队：快速理解和设计数据库结构
• 架构师：系统设计和重构规划
• 运维人员：数据库维护和优化
• 产品经理：需求分析和系统设计

通过本文档的指导，你可以充分利用 ChartDB 的各项功能，提高数据库设计和管理的效率。无论是个人使用还是团队协作，ChartDB 都能为你提供强大的支持。

10. 参考资料

• ChartDB 官方文档
• GitHub 仓库
• 在线演示
• Discord 社区

---

本文档基于 ChartDB v1.14.0 版本编写，如有更新请参考官方文档。