当前位置：首页 > news >正文

终极tbls配置指南：25个.tbls.yml关键参数让数据库文档自动化

news 2026/4/20 11:46:01

终极tbls配置指南：25个.tbls.yml关键参数让数据库文档自动化

【免费下载链接】tblstbls is a CI-Friendly tool to document a database, written in Go.项目地址: https://gitcode.com/gh_mirrors/tb/tbls

tbls是一款基于Go语言开发的CI友好型数据库文档工具，能帮助开发者自动生成清晰、专业的数据库文档。通过.tbls.yml配置文件，你可以灵活定制文档输出格式、内容筛选、关系定义等关键功能，轻松实现数据库文档的自动化管理与维护。

快速上手：.tbls.yml基础结构

.tbls.yml是控制tbls工具行为的核心配置文件，采用YAML格式编写。一个基础的配置文件结构如下：

name: mydatabase # 数据库名称 desc: 项目数据库文档 # 数据库描述 dsn: "mysql://user:pass@localhost:3306/dbname" # 数据库连接字符串

图1：tbls自动生成的数据库表结构文档，包含字段定义、约束条件和关系图

核心配置区域

配置文件主要包含以下功能模块：

数据库连接：dsn参数配置数据库连接信息
内容筛选：include/exclude控制文档包含的表和列
关系定义：relations手动指定表之间的关联关系
文档增强：comments为表和字段添加描述信息
输出格式：format配置文档生成的格式和样式
模板定制：templates指定自定义模板路径

数据库连接配置：dsn参数详解

dsn（Data Source Name）是连接数据库的关键参数，不同数据库类型的DSN格式有所区别：

# PostgreSQL示例 dsn: "postgres://user:password@localhost:5432/dbname?sslmode=disable" # MySQL示例 dsn: "mysql://user:password@localhost:3306/dbname?charset=utf8mb4"

提示：为避免敏感信息泄露，建议通过环境变量传递数据库凭证，如：dsn: "${DB_USER}:${DB_PASS}@tcp(localhost:3306)/dbname"

内容筛选：include与exclude参数

通过include和exclude参数，你可以精确控制哪些表和列出现在文档中：

# 仅包含指定表 include: tables: - users - posts - comments # 排除特定表和列 exclude: tables: - logs - temp_* # 支持通配符 columns: - "*.password" # 排除所有表的password列 - users.created_at

高级筛选技巧

使用通配符*匹配多个项
通过.分隔符指定"表.列"格式
支持正则表达式进行模式匹配

关系定义：relations参数配置

tbls能自动检测表关系，但复杂场景下你可能需要手动定义：

relations: - table: posts columns: user_id parentTable: users parentColumns: id def: "posts->users" # 关系描述

图2：tbls生成的数据库关系图，清晰展示表之间的关联

关系定义参数说明

table：子表名称
columns：子表外键列
parentTable：父表名称
parentColumns：父表主键列
def：关系描述文本

文档增强：comments参数使用

comments参数让你为数据库对象添加富描述：

comments: - table: users tableComment: "系统用户表，存储用户登录信息和基本资料" columnComments: id: "用户唯一标识，自增主键" username: "登录用户名，唯一" email: "用户邮箱，用于登录和通知" indexComments: idx_username: "用户名索引，加速登录查询"

支持的注释类型

tableComment：表级描述
columnComments：字段级描述
indexComments：索引描述
constraintComments：约束描述
triggerComments：触发器描述

输出格式控制：format参数

format参数控制文档的输出样式和行为：

format: number: true # 为表和列添加编号 hideColumnsWithoutValues: true # 隐藏无值列 hideTableDefinition: false # 是否隐藏表定义

常用格式选项

number：启用编号功能
hideColumnsWithoutValues：隐藏空值列
font：指定文档字体
output：设置输出文件格式

模板定制：templates参数

通过自定义模板，你可以完全控制文档的输出样式：

templates: dot: schema: "templates/schema.dot.tmpl" table: "templates/table.dot.tmpl" md: index: "templates/index.md.tmpl" table: "templates/table.md.tmpl"

项目内置模板位于output/目录下，如output/md/templates/包含Markdown格式的默认模板

质量检查：lint参数配置

lint功能帮助你检查数据库设计问题：

lint: requireColumnComment: enabled: true exclude: - "logs.*" # 排除logs表的检查 columnCount: enabled: true max: 20 # 表最大列数限制

常用lint规则

requireColumnComment：检查是否所有列都有注释
columnCount：限制表的最大列数
primaryKey：检查是否定义主键
foreignKey：验证外键关系

标签管理：labels参数

labels参数让你对表和列进行分类标记：

labels: - name: "敏感信息" color: "#ff4444" tables: - users - user_options - name: "审计日志" color: "#00C851" tables: - logs

标签会显示在生成的文档中，帮助读者快速识别表的用途和重要性。

最佳实践：.tbls.yml配置示例

以下是一个完整的配置示例，涵盖了主要功能参数：

name: blogdb desc: 博客系统数据库文档 dsn: "postgres://user:pass@localhost:5432/blogdb" include: tables: - users - posts - comments - tags exclude: columns: - "*.password" - "*.created_at" - "*.updated_at" relations: - table: posts columns: user_id parentTable: users parentColumns: id def: "作者" - table: comments columns: post_id parentTable: posts parentColumns: id def: "所属文章" comments: - table: users tableComment: "系统用户信息表" columnComments: id: "用户ID，自增主键" username: "登录用户名" email: "用户邮箱，用于登录和通知" format: number: true hideColumnsWithoutValues: true templates: md: index: "templates/custom_index.md.tmpl" lint: requireColumnComment: enabled: true columnCount: enabled: true max: 15