使用tbls生成MySQL数据库文档与ER图的正确方法

tbls是一个优秀的数据库文档生成工具，能够自动从数据库中提取结构信息并生成文档和ER图。本文将详细介绍如何正确使用tbls工具生成MySQL数据库文档，特别是针对常见的配置错误进行解析。

基本配置方法

要使用tbls生成数据库文档，首先需要创建一个配置文件。标准的配置文件名为.tbls.yml或tbls.yml，内容示例如下：

dsn: mysql://用户名:密码@主机地址:端口号/数据库名

例如连接本地MySQL的test数据库：

dsn: mysql://root:root@127.0.0.1:3306/test

生成文档的正确命令

配置好yml文件后，可以使用以下命令生成文档：

tbls doc -c tbls.yml

这个命令会在当前目录下创建一个dbdoc文件夹，包含以下文件：

• schema.svg：整体数据库结构图
• 各表的.svg文件：每张表的ER图
• README.md：数据库概览文档
• 各表的.md文件：每张表的详细文档
• schema.json：数据库结构的JSON格式数据

常见错误解析

在实际使用中，用户可能会遇到"invalid database scheme"错误。这通常是由于命令参数使用不当造成的。例如：

tbls doc -c tbls.yml -f erd

这个命令会报错，因为tbls doc命令的参数解析顺序是[DSN] [DOC_PATH]，而erd被错误地解释为数据源名称(DSN)。

正确生成ER图的方法

如果需要指定输出ER图的路径，有以下两种正确方式：

1. 在配置文件中指定输出路径：

dsn: mysql://root:root@127.0.0.1:3306/test
docPath: erd_output

然后运行：

tbls doc -c tbls.yml

2. 直接在命令行中指定输出路径：

tbls doc -c tbls.yml erd_output

版本兼容性说明

本文基于tbls 1.73.2版本编写。不同版本可能有细微差别，建议使用最新版本以获得最佳体验。可以通过以下命令查看当前版本：

tbls version

总结

tbls是一个功能强大的数据库文档生成工具，正确配置和使用可以大大提高数据库文档的编写效率。关键点包括：

1. 确保yml配置文件格式正确
2. 理解命令参数的正确顺序
3. 合理指定输出路径
4. 使用最新版本避免兼容性问题

通过本文的介绍，希望读者能够避免常见的配置错误，顺利生成所需的数据库文档和ER图。