tbls

tbls is a free command-line tool for documenting and checking database schemas, written in Go. It generates GitHub Flavored Markdown documentation and can output schemas in formats including DOT, PlantUML, Mermaid, SVG, PNG, JPG, JSON, YAML, Excel, and configuration files. Configurable lint rules can require column comments or set column-count limits. Its diff command compares a database schema with generated documents or another database, while 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, among others. The project documents Docker usage and a GitHub Action, and external drivers can extend database support. tbls runs on Linux, macOS, and Windows, or in a self-hosted setup. SQL Server use requires version 2017 or later and database compatibility level 110 or higher. The tool is released under the MIT License. Its listed plan is free, with a single-binary CLI.

tbls combines database documentation with linting, schema diffs, and coverage checks across many documented sources. SQL Server users need to meet its stated version and compatibility requirements.

tbls suits developers and database teams who want schema documentation, linting, comparison, or documentation-coverage checks in a command-line workflow. It can fit teams using the listed databases and CI integrations.

Overview

tbls is a free command-line tool for generating database documentation and checking schemas. It suits teams that want those checks in a self-hosted workflow or CI pipeline. Its appeal is the range of formats and databases it supports; teams looking for a hosted visual workspace should consider other tools.

Key features

tbls turns database schemas into GitHub Flavored Markdown and can also produce diagrams, images, structured data, spreadsheets, and configuration files. That makes it useful when a team wants documentation and other schema outputs generated from the same source. The many output choices add flexibility, though teams still need to choose formats that fit their workflow.

Linting, schema comparison, and coverage checks address different maintenance tasks. Configurable rules can require column comments or set column-count limits; diff compares a database with generated documents or another database; and coverage measures documentation for descriptions and comments. Used in CI, these checks can flag missing documentation and schema drift as part of a change workflow. They do not decide which rules a project should enforce.

Documented sources span relational databases, cloud warehouses, NoSQL systems, and inputs such as JSON, HTTP, and GitHub. BigQuery requires bigquery.datasets.get, bigquery.tables.get, and bigquery.tables.list permissions. External executables named tbls-driver-* can extend support by reading TBLS_DSN and returning schema JSON, a path for teams prepared to supply a compatible driver.

Docker usage, an official container image, and a GitHub Action support automated runs. For PostgreSQL, MySQL, MariaDB, and Microsoft SQL Server, TLS settings cover CA certificates, client certificates and keys, and hostname verification. SQL Server requires version 2017 or later and database compatibility level 110 or higher.

Pricing

The Open-source software plan costs nothing and provides an MIT-licensed, single-binary CLI. It is suited to individuals and teams comfortable running a command-line tool in their own environment. The MIT License permits use, modification, distribution, sublicensing, and sale subject to its conditions.

Platforms

tbls supports Linux, macOS, Windows, and self-hosted deployment. Its command-line and CI orientation fits teams that manage their own development workflows; no web platform is part of this offering.

Who it's for

Choose tbls if you need database documentation that can be regenerated and checked alongside schema changes, especially across several documented data sources. It is a less natural fit for readers who want a hosted interface or prefer a point-and-click schema exploration tool.

Pros and cons

• Pros: Documentation, linting, diffs, and coverage checks bring several schema-maintenance tasks into one CLI.
• Pros: Broad documented data-source and output-format support suits teams with varied databases and publishing needs.
• Pros: The free MIT-licensed single-binary plan avoids a software charge and supports self-hosting.
• Cons: The command-line, self-hosted workflow asks teams to manage their own integration and execution.
• Cons: SQL Server support has a minimum server version and compatibility level, which can rule out older installations.

Alternatives

Database Documentation Tools is the broader category to browse when you want to compare documentation products. MySQL is a freemium option with replication and high-availability components, making it relevant when those capabilities are part of the need. Azimutt offers schema and data exploration, with a free plan capped at one user, three databases per project, and two layouts per project; choose it when exploration is the priority. DataDocs has a web-based free plan for one data source, 25 assets, and weekly refreshes, a fit for teams seeking a hosted catalog within those limits. dbdocs offers free public sharing and password protection for one user, and a paid single-user plan; consider it when sharing documented schemas is central. dbForge Studio for PostgreSQL includes code completion, formatting, query history, and visual data editing in its Express plan, suiting PostgreSQL users who want a database studio. DbSchema offers schema synchronization in its Pro plan, relevant when synchronization is the main requirement. dbt Semantic Layer has a free Developer plan limited to one developer seat, 3,000 successful models per month, and one project, for teams focused on that layer. LLMSchema is another free, MIT-licensed CLI option for readers comparing command-line schema tools.

Verdict

tbls is a strong choice for teams that want free, self-hosted database documentation tied to linting, schema diffs, and coverage checks in CI. Its broad database and export support is the main reason to choose it; look elsewhere if you need a hosted visual workspace or your SQL Server installation falls below its requirements.