tbls
github.com
- Free plan
- Windows
- macOS
- Linux
- Self-hosted
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.
Plans
Every plan and priceOpen-source software
Free plan
Getting started
- Install tbls for Linux, macOS or Windows, or use a self-hosted deployment
- Connect a documented data source or configure an external tbls-driver executable
- Set the database connection details, including TLS settings where required
- Run tbls to generate documentation or schemas
- Use diff, coverage or lint rules in the command line
- 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.