Skip to the content
Know your tech before you buy it. Makers: get listed from $49/mo

tbls

github.com

  • Free plan
  • Windows
  • macOS
  • Linux
  • Self-hosted
7.7 Club score Visit github.com

What tbls is

tbls is a database documentation and checking tool designed to fit into CI workflows. It generates database documentation in GitHub Flavored Markdown and can produce schema output in formats such as DOT, PlantUML, Mermaid, SVG, PNG, JPG, JSON, YAML and Excel. Its configurable lint rules can check for required column comments and column-count limits. The `diff` command compares a database schema with generated documentation or another database, while `coverage` measures documentation for descriptions and comments. Documented data sources range from PostgreSQL, MySQL, MariaDB and SQLite to BigQuery, Cloud Spanner, Redshift, SQL Server, DynamoDB, Snowflake, MongoDB, ClickHouse and Databricks. It can run with Docker or the k1low/setup-tbls GitHub Action, and external drivers can add database schemes. The project offers Linux, macOS, Windows and self-hosted use. SQL Server requires version 2017 or later and database compatibility level 110 or higher. tbls is free under the MIT License.

Who it suits

tbls suits developers and database teams who want schema documentation, linting and comparison in a CI workflow. It is also relevant to teams documenting supported databases in self-hosted environments.

Good to know, and what to watch

  • Generates GitHub Flavored Markdown database documentation.
  • Lint rules can require column comments.
  • Compares schemas with documentation or other databases.
  • Measures documentation coverage for descriptions and comments.
  • Works with a broad range of documented data sources.
  • SQL Server requires version 2017 or later.
  • SQL Server compatibility level 110 or higher is required.
  • BigQuery use requires specified dataset and table permissions.

Open-source software

Free

Free plan

Getting started

  1. Install tbls for Linux, macOS or Windows, or use a self-hosted deployment
  2. Connect a documented data source or configure an external tbls-driver executable
  3. Set the database connection details, including TLS settings where required
  4. Run tbls to generate documentation or schemas
  5. Use diff, coverage or lint rules in the command line
  6. Integrate Docker or the k1low/setup-tbls GitHub Action

Limits to check

SQL Server connections require Microsoft SQL Server 2017 or later and database compatibility level 110 or higher. BigQuery use requires bigquery.datasets.get, bigquery.tables.get and bigquery.tables.list permissions.

The verdict

tbls combines schema documentation with linting, comparison and coverage measurement in a free tool. Check its SQL Server requirements and BigQuery permissions against your environment before adopting it.

Questions people ask

What does tbls cost?

tbls is free open-source software under the MIT License.

Which operating systems support tbls?

It runs on Linux, macOS and Windows, and can be deployed self-hosted.

Which databases can it document?

Documented sources include PostgreSQL, MySQL, MariaDB, SQLite, BigQuery, Cloud Spanner, Redshift, SQL Server, DynamoDB, Snowflake, MongoDB, ClickHouse and Databricks, plus others listed by the project.

What output formats are available?

Outputs include Markdown, DOT, PlantUML, Mermaid, SVG, PNG, JPG, JSON, YAML, Excel and configuration files.

Can tbls compare schemas?

Yes. The diff command compares a database with generated documents or another database.

Can its database support be extended?

Yes. Executables named tbls-driver-* can provide additional drivers using TBLS_DSN and schema JSON output.

What the maker publishes

Automatic documentation
It automatically documents databases in GitHub Flavored Markdown and outputs schemas in many formats. source
BigQuery permissions
BigQuery use requires bigquery.datasets.get, bigquery.tables.get and bigquery.tables.list permissions. source
CI integration
The project documents Docker usage and a GitHub Action named k1low/setup-tbls. source
CI integration
The project documents GitHub Actions integration through the k1low/setup-tbls action. source
Container integration
An official container image is published as ghcr.io/k1low/tbls. source
Coverage
The tbls coverage command measures documentation coverage for descriptions and comments. source
Coverage measurement
The tbls coverage command measures documentation coverage for tables and comments. source
Database linting
It can lint databases using configurable rules such as required column comments and column-count limits. source
Documentation
It automatically documents databases in GitHub Flavored Markdown and outputs schemas in many formats. source
Extensibility
Executables named tbls-driver-* can provide external database drivers, receiving TBLS_DSN and emitting schema.json on standard output. source
External drivers
Executables named tbls-driver-* on PATH can provide additional database schemes through TBLS_DSN and schema JSON on standard output. source
Integrations
Documented datasources include PostgreSQL, MySQL, MariaDB, SQLite, BigQuery, Cloud Spanner, Amazon Redshift, Microsoft SQL Server, Azure SQL or Microsoft Fabric Warehouse, Amazon DynamoDB, Snowflake, MongoDB, ClickHouse, Databricks, JSON, HTTP, and GitHub. source
Latest release
The repository's releases page lists v1.96.1, released on 28 September 2026. source
License
tbls is released under the MIT License, which permits use, copying, modification, publication, distribution, sublicensing, and sale subject to the license conditions. source
License
The software is released under the MIT License and permits use, copying, modification, publication, distribution and sublicensing subject to its notice requirement. source
Linting
tbls works as a database linter with configurable rules such as required column comments and column-count limits. source
Maker
The repository owner and copyright holder is Ken'ichiro Oyama. source
Output formats
tbls can output Markdown, DOT, PlantUML, Mermaid, SVG, PNG, JPG, JSON, YAML, Excel, and configuration files. source
Purpose
tbls is a CI-Friendly tool to document a database, written in Go. source
Purpose
tbls is a CI-friendly tool written in Go for documenting databases. source
Schema comparison
The tbls diff command compares database schemas with generated documents or other databases. source
Schema diffing
The tbls diff command compares a database with generated documentation or another database. source
Security policy
The repository security page states that no security policy is detected. source
SQL Server limit
Microsoft SQL Server 2017 or later with database compatibility level 110 or higher is required. source

Checked against the maker's pages on 1 Oct 2026.