4,344 stars · MIT · v1.96.0 (2026-09-03, /releases/latest and ungh agree) · Track this in Scout
Reads a live database and writes its documentation as Markdown with generated diagrams, then lints the schema against rules you set.
▶Repo detailsthe review · specs · pros & cons · install
What it is
tbls is a single Go binary that connects to a database and produces Markdown documentation with a diagram of every table and every relationship. It also includes a linter, so the same command can fail a build when the schema drifts from the rules you agreed.
What it is good for. Anyone who has inherited a database that nobody documented, which is almost everyone. The linting half is for a small team that keeps meaning to write column comments and never does.
- Read-only. It connects, reads the structure, and writes files. There is no version where it changes your data.
- It supports PostgreSQL, MySQL, SQLite, SQL Server, BigQuery, DynamoDB and several more, so one tool covers a mixed estate.
- The output is Markdown and the diagrams are generated, so the documentation lives in the same place as the code and is reviewed like the code.
- It documents structure, not meaning. It will tell you a column is called
statusand an integer; it cannot tell you that 3 means refunded. - The rules of the linter have to be written by somebody, and an empty rule file finds nothing.
- Diagrams of a large database are large. Past about eighty tables the single picture stops being readable and you need to split it by schema.
azimuttapp/azimutt2,183 stars, covered in Edition 28; a visual explorer you click through in a browser, rather than files you commit.
Track this in Scout- schemaspy/schemaspy
3,721 stars, the long-standing Java tool that does the same job and outputs HTML; its last code landed 5 March 2026.
Track this in Scout - holistics/dbml
3,702 stars, a small language for writing a schema by hand and generating diagrams from it, which is the opposite direction.
Track this in Scout
# macOS or Linux with Homebrew brew install k1LoW/tap/tbls # or with Go installed go install github.com/k1LoW/tbls@latest tbls doc "postgres://user:password@localhost:5432/mydb?sslmode=disable" ./dbdoc
