Freedom251 › Database Documentation Tools

tbls

Free plan LinuxMacSelf-hostedWindows

What tbls is

tbls is a free command-line tool for documenting and checking database schemas. Written in Go, it generates database documentation in GitHub Flavored Markdown and can export schemas in formats such as DOT, PlantUML, Mermaid, SVG, PNG, JPG, JSON, YAML, and Excel. Its configurable lint rules can check for required column comments or set column-count limits. The diff command compares a schema with generated documentation or another database; coverage measures documentation for descriptions and comments. Documented data sources include PostgreSQL, MySQL, MariaDB, SQLite, BigQuery, Cloud Spanner, Redshift, SQL Server, DynamoDB, Snowflake, MongoDB, ClickHouse, and Databricks, along with others. The project documents Docker use and a GitHub Action, and external drivers can add database schemes. It runs on Linux, macOS, and Windows, and can be self-hosted. SQL Server requires version 2017 or later and database compatibility level 110 or higher. The software is released under the MIT License. GitHub Issues are the listed channel for discussing problems.

Who it suits

tbls may suit database teams that want generated schema documentation, linting, comparisons, or coverage checks in a CI workflow. Its documented data sources and multiple export formats also serve teams maintaining different database systems or documentation outputs.

What it does well

Generates GitHub Flavored Markdown documentation.
Lint rules can require column comments.
Diff compares schemas with documents or other databases.
Coverage measures documentation for descriptions and comments.
MIT License permits use, modification, and distribution under its conditions.

What to know first

SQL Server needs version 2017 or later.
SQL Server needs compatibility level 110 or higher.
Repository security page says no security policy is detected.

Plans

Plan	Billed and limits	Price
Open-source software	MIT license · single-binary CLI	Free

As github.com lists them, read 1 Oct 2026. The maker's own page has the final word.

Getting started

Install or run tbls on Linux, macOS, or Windows.
Configure a documented data source, or provide an external tbls-driver-* executable for another database scheme.
Run tbls to generate database documentation and choose an output format.
Use the lint, diff, or coverage commands for checks.
For CI, use the documented Docker workflow or k1low/setup-tbls GitHub Action.

Verdict

tbls combines database documentation with linting, schema comparison, and coverage measurement in a free CLI. Check its SQL Server requirements if that is your data source.

Questions

How much does tbls cost?

The Open-source software plan is free and is released under the MIT License.

Which platforms does tbls support?

It supports Linux, macOS, and Windows, and can be used in a self-hosted setup.

Which databases can it document?

Documented sources include PostgreSQL, MySQL, MariaDB, SQLite, BigQuery, Cloud Spanner, Redshift, SQL Server, DynamoDB, Snowflake, MongoDB, ClickHouse, and Databricks, among others.

Can tbls run in CI?

The project documents Docker usage and a GitHub Action named k1low/setup-tbls.

What license does tbls use?

It is released under the MIT License.

Are there database-specific requirements?

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

Facts from tbls's own pages

Automatic documentation: It automatically documents databases in GitHub Flavored Markdown and outputs schemas in many formats. · github.com, 1 Oct 2026
BigQuery permissions: BigQuery use requires bigquery.datasets.get, bigquery.tables.get and bigquery.tables.list permissions. · github.com, 1 Oct 2026
CI integration: The project documents GitHub Actions integration through the k1low/setup-tbls action. · github.com, 1 Oct 2026
Container integration: An official container image is published as ghcr.io/k1low/tbls. · github.com, 1 Oct 2026
Coverage: The tbls coverage command measures documentation coverage for descriptions and comments. · github.com, 30 Sept 2026
Coverage measurement: The tbls coverage command measures documentation coverage for tables and comments. · github.com, 1 Oct 2026
Database linting: It can lint databases using configurable rules such as required column comments and column-count limits. · github.com, 1 Oct 2026
Documentation: It automatically documents databases in GitHub Flavored Markdown and outputs schemas in many formats. · github.com, 30 Sept 2026
Extensibility: Executables named tbls-driver-* can provide external database drivers, receiving TBLS_DSN and emitting schema.json on standard output. · github.com, 30 Sept 2026
External drivers: Executables named tbls-driver-* on PATH can provide additional database schemes through TBLS_DSN and schema JSON on standard output. · github.com, 1 Oct 2026
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. · github.com, 30 Sept 2026
Latest release: The repository's releases page lists v1.96.1, released on 28 September 2026. · github.com, 30 Sept 2026
License: The software is released under the MIT License and permits use, copying, modification, publication, distribution and sublicensing subject to its notice requirement. · github.com, 1 Oct 2026
Linting: tbls works as a database linter with configurable rules such as required column comments and column-count limits. · github.com, 30 Sept 2026
Maker: The repository owner and copyright holder is Ken'ichiro Oyama. · github.com, 30 Sept 2026
Output formats: tbls can output Markdown, DOT, PlantUML, Mermaid, SVG, PNG, JPG, JSON, YAML, Excel, and configuration files. · github.com, 30 Sept 2026
Purpose: tbls is a CI-friendly tool written in Go for documenting databases. · github.com, 1 Oct 2026
Schema comparison: The tbls diff command compares database schemas with generated documents or other databases. · github.com, 30 Sept 2026
Schema diffing: The tbls diff command compares a database with generated documentation or another database. · github.com, 1 Oct 2026
Security policy: The repository security page states that no security policy is detected. · github.com, 1 Oct 2026
SQL Server limit: SQL Server 2017 or later with database compatibility level 110 or higher is required for schema introspection. · github.com, 1 Oct 2026
Support channel: The project provides GitHub Issues for reporting and discussing problems. · github.com, 1 Oct 2026
Supported databases: Documented data sources include PostgreSQL, MySQL, MariaDB, SQLite, BigQuery, Cloud Spanner, Redshift, SQL Server, DynamoDB, Snowflake, MongoDB, ClickHouse and Databricks. · github.com, 1 Oct 2026
Transport security: For PostgreSQL, MySQL, MariaDB and Microsoft SQL Server, the DSN supports TLS certificate configuration and hostname verification. · github.com, 1 Oct 2026

Where tbls stands on Freedom251

Database Documentation Tools#14 of 27