Repolode
Submit
k1LoW

k1LoW/tbls

A Go CLI that generates GFM Markdown documentation from a live database schema, with diff, lint and ER diagram support for CI.

View on GitHub
Stars
4,364
Forks
217
Open issues
57
Last commit
8 days ago

What is it?

tbls connects to a database, reads its schema, and generates a browsable Markdown document with tables, columns, indexes, constraints, and relations. It can also produce ER diagrams as SVG, PNG, JPG or Mermaid, and export the schema to formats such as DOT, PlantUML, JSON, YAML and Excel.

Beyond documentation, tbls works as a schema checker. The diff command compares a live database against its generated document or against another database, and the lint command enforces configurable rules such as required column comments, maximum column counts, and foreign key indexes. The coverage command reports how much of the schema is documented.

tbls ships as a single binary and supports PostgreSQL, MySQL, MariaDB, SQLite, SQL Server, BigQuery, Snowflake, Redshift, Cloud Spanner, DynamoDB, MongoDB, ClickHouse and Databricks, among others. Configuration lives in a .tbls.yml file, which makes it straightforward to run in CI pipelines.

Key features

  • 01Generates GitHub-friendly Markdown documentation from a database schema.
  • 02Produces ER diagrams in SVG, PNG, JPG or Mermaid format.
  • 03Diffs a database against its documentation or another database.
  • 04Lints schemas with configurable rules such as required comments and column limits.
  • 05Measures documentation coverage for tables and columns.
  • 06Supports many databases, including PostgreSQL, MySQL, SQLite, BigQuery and MongoDB.

Use cases

  • Keeping a database schema document in the repository and updated alongside code changes.
  • Failing CI builds when schema changes break documentation or lint rules.
  • Comparing a production database against a staging or local copy.
  • Exporting schema definitions to Excel or PlantUML for review with non-developers.

Quick start

  1. 1

    Install via Homebrew

    brew install tbls
  2. 2

    Document a database with one command

    tbls doc postgres://dbuser:dbpass@hostname:5432/dbname

Things to know

  • Documents a live database, so it needs a reachable database connection and credentials.

In collections

CLI & terminal toolsDatabases & SQL tools

Topics

#database#documentation-tool#database-schema#er-diagram#continuous-integration#markdown#golang#cli#bigquery#database-document

FAQ

What is tbls?
A Go CLI that generates GFM Markdown documentation from a live database schema, with diff, lint and ER diagram support for CI. tbls connects to a database, reads its schema, and generates a browsable Markdown document with tables, columns, indexes, constraints, and relations. It can also produce ER diagrams as SVG, PNG, JPG or Mermaid, and export the schema to formats such as DOT, PlantUML, JSON, YAML and Excel.
Is tbls free to use? What license does it have?
tbls is open source under the MIT license. Check the license terms before using it in commercial products.
Is tbls still maintained?
Actively maintained. The last commit to tbls was on Oct 15, 2026.
What can I use tbls for?
Keeping a database schema document in the repository and updated alongside code changes. Failing CI builds when schema changes break documentation or lint rules. Comparing a production database against a staging or local copy. Exporting schema definitions to Excel or PlantUML for review with non-developers.
How do I install tbls?
Install via Homebrew: brew install tbls Document a database with one command: tbls doc postgres://dbuser:dbpass@hostname:5432/dbname
Where can I get tbls?
The source code and installation instructions are on GitHub: https://github.com/k1LoW/tbls

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects