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

终极tbls配置指南25个.tbls.yml关键参数让数据库文档自动化【免费下载链接】tblstbls is a CI-Friendly tool to document a database, written in Go.项目地址: https://gitcode.com/gh_mirrors/tb/tblstbls是一款基于Go语言开发的CI友好型数据库文档工具能帮助开发者自动生成清晰、专业的数据库文档。通过.tbls.yml配置文件你可以灵活定制文档输出格式、内容筛选、关系定义等关键功能轻松实现数据库文档的自动化管理与维护。快速上手.tbls.yml基础结构.tbls.yml是控制tbls工具行为的核心配置文件采用YAML格式编写。一个基础的配置文件结构如下name: mydatabase # 数据库名称 desc: 项目数据库文档 # 数据库描述 dsn: mysql://user:passlocalhost:3306/dbname # 数据库连接字符串图1tbls自动生成的数据库表结构文档包含字段定义、约束条件和关系图核心配置区域配置文件主要包含以下功能模块数据库连接dsn参数配置数据库连接信息内容筛选include/exclude控制文档包含的表和列关系定义relations手动指定表之间的关联关系文档增强comments为表和字段添加描述信息输出格式format配置文档生成的格式和样式模板定制templates指定自定义模板路径数据库连接配置dsn参数详解dsnData Source Name是连接数据库的关键参数不同数据库类型的DSN格式有所区别# PostgreSQL示例 dsn: postgres://user:passwordlocalhost:5432/dbname?sslmodedisable # MySQL示例 dsn: mysql://user:passwordlocalhost:3306/dbname?charsetutf8mb4提示为避免敏感信息泄露建议通过环境变量传递数据库凭证如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 # 关系描述图2tbls生成的数据库关系图清晰展示表之间的关联关系定义参数说明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:passlocalhost: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配置文件存放位置tbls会按以下顺序查找配置文件当前目录的.tbls.yml用户主目录的.tbls.yml项目根目录的tbls.yml建议将配置文件放在项目根目录并提交到版本控制系统以便团队共享和CI/CD流程使用。常见问题解决连接数据库失败检查dsn格式是否正确数据库服务是否可访问。可以使用tbls ping命令测试连接tbls ping -c .tbls.yml关系图显示异常如果表关系未正确显示可能是外键约束未正确定义需要在relations中手动指定关系表名或列名存在拼写错误文档生成缓慢对于大型数据库可以通过以下方式优化使用include参数只包含必要的表增加exclude规则排除大表或无用表禁用不必要的文档生成功能总结.tbls.yml配置文件是tbls工具的核心通过本文介绍的25个关键参数你可以完全控制数据库文档的生成过程。合理配置这些参数能帮助你创建清晰、专业且易于维护的数据库文档提升团队协作效率。无论是小型项目还是大型企业应用tbls都能满足你的数据库文档需求让文档维护不再成为负担。开始使用tbls体验数据库文档自动化的便捷吧提示更多配置选项和高级功能请参考项目中的testdata/目录下的示例配置文件。【免费下载链接】tblstbls is a CI-Friendly tool to document a database, written in Go.项目地址: https://gitcode.com/gh_mirrors/tb/tbls创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考