Open-source project
k1LoW/tbls avatar
k1LoW/tbls

tbls: a single Go binary that turns a live database into Markdown docs, diffs and lint reports

tbls is a CI-Friendly tool to document a database, written in Go.

4,375 stars218 forksGoMIT

At a glance

What is it?
tbls connects to a database, writes its schema as GitHub-flavoured Markdown, and can then diff, lint and score that documentation in CI. Its strengths are the single binary and the long list of datasources; its sharp edges are stale files, Markdown-only diffs and connection strings that carry passwords.
Who is it for?
tbls suits teams that want database documentation regenerated in CI and reviewed as ordinary Markdown in pull requests. It is a weaker fit if you need diffs that reach beyond the generated documents, or if you cannot keep database credentials out of a committed .tbls.yml.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 1 day ago.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • k1LoW/tbls4,375 ★ · +25
Star history
Repository2026-09-232026-11-15
k1LoW/tbls4.4k4.4k

25 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

One command and a DSN produce the whole document set

tbls is pronounced like the word tables and is described as a CI-friendly tool to document a database, written in Go. The quickest route is a single command that takes a database source name:

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

The same call works through the published Docker image, with the current directory mounted as the working directory:

console
$ docker run --rm -v $PWD:/work -w /work ghcr.io/k1low/tbls doc postgres://dbuser:dbpass@hostname:5432/dbname

The output is GitHub-flavoured Markdown, so the generated pages render directly in a repository. The repository ships a sample/postgres/README.md as an example of the result. The main reason the project calls itself CI-friendly is that it is one binary: a pipeline step needs nothing but that binary and network access to the database.

The password sits inside the DSN, and special characters must be URL-encoded

Day-to-day use moves the DSN into a .tbls.yml file, or tbls.yml, at the root of your repository. The shipped example sets dsn to a postgres URL with a user and password and sets docPath to doc/schema. If docPath is left out, the default is dbdoc.

Two consequences follow. First, a DSN written like that puts a database password into a file that is meant to be committed, so you should decide early how the credentials reach the file in your pipeline. The table of contents lists a section on expanding environment variables, which is the place to look. Second, a password containing a symbol such as # or < must be URL-encoded, otherwise the connection string will not parse as intended. The project flags this in a notice because it is an easy way to lose an hour.

tbls diff compares Markdown documents only

Once documentation is committed, tbls diff shows the difference between the live database schema and the generated document. In the example, a column added with an ALTER TABLE statement makes the Columns count for the users table disagree with the stored page, and the diff prints the changed row in unified diff form with the password masked as asterisks in the header.

The command also accepts two database URLs, for example a local and a production database, to compare databases with each other.

The limit is stated in a notice: tbls diff shows the difference Markdown documents only. It compares what tbls would write, not the raw schema. That makes it a good drift alarm for documentation, but it does not produce migration SQL, and anything the generated pages do not render is outside what it can detect.

Regeneration with --force leaves stale pages behind

Re-running tbls doc against existing output needs one of two flags. The --force flag overwrites existing documents, but it does not remove the files of tables that no longer exist. After a table is dropped, its old Markdown page stays in the directory, and any link to it keeps working even though the table is gone.

The --rm-dist flag removes the files in docPath before generating the documents, which cleans up dropped tables. It deletes everything in that directory, so it is only safe when docPath contains nothing but generated output. Keep hand-written pages somewhere else, or you will lose them on the first run. A pipeline that must stay accurate after schema deletions should use --rm-dist; one that shares its directory with other files has to live with --force and clean up by hand.

Lint rules and coverage turn missing comments into failures

tbls also works as a linter. Rules are written under a lint key in .tbls.yml. The example enables requireColumnComment with id, created and updated excluded, and columnCount with a maximum of 10:

yaml
# .tbls.yml
lint:
  requireColumnComment:
    enabled: true
    exclude:
      - id
      - created
      - updated
  columnCount:
    enabled: true
    max: 10

Running tbls lint prints one line per violation, such as users.username: column comment required, or posts: too many columns. [12/10], and ends with a count like 11 detected. The tbls coverage command measures how much of the database has descriptions and comments, and its sample output reports 16.1% across all tables with per-table figures below it. Both commands only judge what the database itself carries, so comments kept outside the database count as missing.

Each install route carries a different cost

The deb and RPM routes both set a TBLS_VERSION variable and download a package named for that version, and the examples point at amd64 files:

console
$ export TBLS_VERSION=X.X.X
$ curl -o tbls.deb -L https://github.com/k1LoW/tbls/releases/download/v$TBLS_VERSION/tbls_$TBLS_VERSION-1_amd64.deb
$ dpkg -i tbls.deb

Homebrew and MacPorts install with brew install tbls and sudo port install tbls, and aqua uses aqua g -i k1LoW/tbls. You can also download a binary from the releases page. The go install route pulls the latest source:

console
$ go install github.com/k1LoW/tbls@latest

That route needs a Go toolchain recent enough for the project, whose go.mod declares go 1.26.8. For CI there is a setup-tbls action, used after checkout in the example workflow. A Temporary route sources a script fetched with curl from the main branch, which means you run whatever that script contains at the time, so pin to a release for anything repeatable.

Datasource coverage is wide, but the test setup shows which versions are exercised

The go.mod lists drivers for BigQuery, Spanner, ClickHouse, DynamoDB, Databricks, MySQL, SQL Server, SQLite, Snowflake, MongoDB and PostgreSQL through lib/pq. The sample directory matches: azuresql, bigquery, clickhouse, databricks, dynamodb, mariadb, mongo, mssql, mysql, mysql56, postgres and postgres95, among others.

The compose.yml used for tests pins specific server versions: PostgreSQL 9.5 and 15, MySQL 5.6 and 8, MariaDB 10.5, SQL Server 2019, DynamoDB local, MongoDB 4.4.18 and ClickHouse 24.4. Those are the versions with evidence behind them. A newer or older engine may work, but nothing in the repository shows it. Note also that the sample names include mermaid, png and font, so ER diagram output has several forms, and the Graphviz library in the dependency list supports image rendering.

Releases are recent, and the project tracks them with tagpr

The newest releases are v1.96.1 on 2026-09-28, v1.96.0 on 2026-09-03 and v1.95.0 on 2026-07-11, and the last push to the repository was on 2026-10-31. The repository carries a CHANGELOG.md, a .tagpr file and a .goreleaser directory, so release notes and builds follow a defined process.

The license is MIT. The Makefile ci target runs a long chain of checks across the database samples, including license checks, JSON output and jsonschema tests, so changes are exercised against real servers started from the compose file. For you, that means releases come at a steady pace but are tested against that fixed set of engines. If you depend on an unusual engine version, run tbls against a copy of your own database before wiring it into a pipeline.

Editorial conclusion

tbls suits teams that want database documentation regenerated in CI and reviewed as ordinary Markdown in pull requests. It is a weaker fit if you need diffs that reach beyond the generated documents, or if you cannot keep database credentials out of a committed .tbls.yml. Before adopting it, confirm that your database engine and version appear in the sample directories and the test setup, because that is the evidence of what the project exercises.

Frequently asked questions

What does tbls do?

tbls is a CI-friendly tool written in Go that documents a database. It writes the schema as GitHub-flavoured Markdown and can also diff, lint and measure document coverage.

How do I run tbls with Docker?

Run docker run --rm -v $PWD:/work -w /work ghcr.io/k1low/tbls doc followed by your database URL. The image is also available with docker pull ghcr.io/k1low/tbls:latest.

Can tbls diff compare two databases?

Yes. tbls diff accepts two database URLs, such as a local and a production database. It shows the difference in the Markdown documents only.

Official sources

  1. Issues
  2. k1LoW/tbls on GitHub
  3. License: MIT
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/k1low-tbls.svg)](https://hysenlabs.com/projects/k1low-tbls)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/k1low-tbls.svg)](https://hysenlabs.com/projects/k1low-tbls)

Was this useful?