mysql 数据表导出为 markdown（附 go 语言 gorm 的实际使用）

前言

通常业务系统开发中，数据库的设计与维护是至关重要的环节。而数据库的文档化则是确保团队成员之间有效沟通、快速理解系统架构的基础。

但目前数据文档都是手动写的，耗时费力，由于当前项目使用的是 mysql 作为存储引擎，找找看有没有比较好用的工具，发现了一个比较契合的 mysql_markdown。

mysql_markdown 的使用

可以直接上 GitHub 上下载源码，自行编译。

快速使用

# 帮助
➜  mysql_markdown -h
flag needs an argument: -h
Usage: mysql_markdown [options...]
--help  This help text
-h      host.     default 127.0.0.1
-u      username. default root
-p      password. default root
-d      database. default mysql
-P      port.     default 3306
-c      charset.  default utf8
-o      output.   default current location
-t      tables.   default all table and support ',' separator for filter, every item can use regexp
-l      language. default cn,support: cn,en

# 使用
➜ mysql_markdown -p 123456 -d test
connecting to MySQL to export markdown document file.
 100% |█████████████████████████████████████████████████████████████████████████████████████| (1/1, 394 it/s)
convert to document finished in test_20241122_103043.md

go gorm 生成表/字段描述

使用过 gorm 的，对于生成数据库字段描述应该不陌生，只需要在对应的结构体上添加 tag 即可，如下：

type User struct {
	Name string `gorm:"comment:姓名"`
	Age  int    `gorm:"comment:年龄"`
}

生成表的描述信息，注意：gorm 没有提供类似 TableName 设置表名的方式来设置描述，得用 gorm:table_options 来设置，如果不是新建的表，这种设置方式也不能生效。

db.Set("gorm:table_options", "COMMENT '用户表'").AutoMigrate(&User{})

实际例子

package main

import (
	"gorm.io/driver/mysql"
	"gorm.io/gorm"
	"gorm.io/gorm/logger"
	"log"
	"os"
)

type User struct {
	Name string `gorm:"comment:姓名"`
	Age  int    `gorm:"comment:年龄"`
}

func (User) TableName() string {
	return "user"
}

func getLocalTestDb() (db *gorm.DB, err error) {
	newLogger := logger.New(log.New(os.Stderr, "\r\n", log.LstdFlags), logger.Config{
		LogLevel:                  logger.Info,
		IgnoreRecordNotFoundError: true,
		Colorful:                  true,
	})
	db, err = gorm.Open(mysql.New(mysql.Config{
		DSN: "root:123456@tcp(127.0.0.1:3306)/test",
	}), &gorm.Config{Logger: newLogger, CreateBatchSize: 1000})
	return
}

func main() {
	db, err := getLocalTestDb()
	if err != nil {
		log.Fatal(err)
	}

	db = db.Debug()

	// gorm:table_options 会在创建 table 的语句后添加相关的语句，不是新建的表不能生效
	err = db.Set("gorm:table_options", "COMMENT '用户表'").AutoMigrate(&User{})
	if err != nil {
		log.Fatal(err)
	}

	log.Println("OK")
}

程序输出

2024/11/22 10:23:08 main.go:41
[0.000ms] [rows:-] SELECT DATABASE()

2024/11/22 10:23:08 main.go:41
[5.769ms] [rows:1] SELECT SCHEMA_NAME from Information_schema.SCHEMATA where SCHEMA_NAME LIKE 'test%' ORDER BY SCHEMA_NAME='test' DESC,SCHEMA_NAME limit 1

2024/11/22 10:23:08 main.go:41
[2.575ms] [rows:-] SELECT count(*) FROM information_schema.tables WHERE table_schema = 'test' AND table_name = 'user' AND table_type = 'BASE TABLE'

2024/11/22 10:23:09 main.go:41
[49.289ms] [rows:0] CREATE TABLE `user` (`name` longtext COMMENT '姓名',`age` bigint COMMENT '年龄')COMMENT '用户表'
2024/11/22 10:23:09 OK

使用 mysql_markdown 工具导出 md 文档

mysql_markdown -p 123456 -d test

可见文档内容如下：

## test tables message
#### 1、 user
用户表

| 序号 | 名称 | 描述 | 类型 | 键 | 为空 | 额外 | 默认值 |
| :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: |
| 1 | `name` | 姓名 | longtext |  | YES |  |  |
| 2 | `age` | 年龄 | bigint |  | YES |  |  |