Overview

When it comes to well-known tools for automatically generating DB documentation, MySQL Workbench is probably the first to come to mind. However, I looked for other good OSS options and tried a few, so I wanted to share my impressions.

Schemaspy

A Java-based tool that connects to a database and generates DB documentation in HTML format.

There is an image available on Dockerhub, so you can easily try it out.

For MySQL 5.7 (I think 5.8 should work too), you can run it like this: docker run -v "$PWD/schema:/output" --net="host" schemaspy/schemaspy:latest \ -t mysql -host {DBHOST}:{DBPORT} -db {DBNAME} -u {DBUSER} -p {DBPASSWORD}

In a MySQL 5.6 environment, you need to tweak the command a bit: docker run -v "$PWD/schema:/output" --net="host" schemaspy/schemaspy:latest -t mysql -host {DBHOST}:{DBPORT} -db {DBNAME} -u {DBUSER} -p {DBPASSWORD} -connprops useSSL\\=false -s {DBNAME}

Both can be tested easily in a one-liner.

Of course, it works with databases other than MySQL as well.

tbls

github.com - k1Low/tbls

A CI-friendly DB documentation tool that generates documentation in Markdown format.

It can be installed via dep, rpm, brew, go, or docker.

The usage is straightforward, so refer to the README on GitHub.

I want to manage all documentation in Markdown, so I have adopted it for my personal application's documentation.

Impressions

If we compare only ER diagrams, the conclusion might be that MySQL Workbench is the most visually appealing. However, this depends on the number of tables. If there are few tables, any of them should be fine.
MySQL Workbench does not automatically include tables that do not have relational connections in its ER generation, but schemaspy seems to handle that properly.
The ER diagram generated by schemaspy can be difficult to follow when there are many tables, so I think it would be good if the UI could be adjusted somehow. MySQL Workbench allows for manual adjustments, which adds flexibility (there is an automatic arrangement feature, but it seems to have its limits...).
Regarding ER diagrams, I feel there is a physical limit to outputting the relationships of all tables, so some creativity from the user may be necessary. I don't think there are many cases where you want to see the relationships for all tables at once, so it would be good to narrow down the tables. I wonder if schemaspy allows you to filter the tables to generate as ER diagrams... I haven't looked closely, but it doesn't seem like it can be done at a glance...
tbls is CI-friendly, making it easy to integrate into CI, but it seems that schemaspy can also be integrated relatively easily.
rarejob-tech-dept.hatenablog.com - A Story About Integrating Automatic ER Diagram Creation into CI