tbls
A CI-friendly tool to automatically document, lint, diff, and visualize database schemas across many database systems.
What is tbls?
tbls is a command-line tool that automatically generates documentation for database schemas. It connects to various database systems, extracts schema information, and produces detailed documentation in formats like Markdown, ER diagrams, and JSON. It solves the problem of maintaining accurate, up-to-date database documentation by automating the process and integrating with CI/CD pipelines.
Database administrators, backend developers, and DevOps engineers who need to document, version-control, and lint database schemas across multiple environments and database technologies.
Developers choose tbls for its simplicity, extensive database support, and strong CI/CD integration. Its single binary distribution, built-in linting, diffing, and visualization capabilities provide a comprehensive, automation-friendly solution for database schema management.
Overview
tbls is a CI-Friendly tool to document a database, written in Go.
Use Cases
Best For
- Automatically generating Markdown documentation for PostgreSQL or MySQL schemas
- Integrating database schema checks into CI/CD pipelines using GitHub Actions
- Visualizing database relationships with ER diagrams in SVG or Mermaid format
- Enforcing documentation standards with linting rules for column comments
- Detecting schema drift between development and production databases
- Documenting schemas for databases without native commenting features like SQLite
Not Ideal For
- Teams needing real-time, collaborative database documentation editing
- Organizations with strict security policies prohibiting CLI tools or external binary installations
- Projects relying heavily on experimental database support like Snowflake or Databricks
- Non-technical users who prefer a graphical interface for browsing and updating documentation
Pros & Cons
Pros
The single binary design and dedicated GitHub Action allow seamless integration into continuous integration pipelines, as demonstrated in the README with example workflows for automated documentation generation.
tbls connects to over a dozen databases including PostgreSQL, MySQL, SQLite, and MongoDB, with detailed DSN examples provided for each, making it versatile for mixed environments.
It generates documentation in multiple formats like Markdown, DOT, PlantUML, Mermaid, and images (SVG, PNG, JPG), enabling flexible use cases from static docs to visual ER diagrams.
The tool includes configurable linting rules to enforce documentation standards, such as requiring column comments and limiting column counts, which helps maintain consistency across teams.
Cons
The .tbls.yml file has numerous options for linting, filtering, relations, and templates, which can be overwhelming for new users and requires careful setup to avoid errors.
Databases like Snowflake and Databricks are marked as experimental in the README, indicating potential instability, incomplete features, or lack of robust testing for these systems.
tbls generates static documentation files that require manual regeneration or CI runs to update, lacking real-time synchronization with database changes, which can lead to stale docs.
Frequently Asked Questions
Related Projects
Schema SpyDatabase documentation built easy
DBMLDatabase Markup Language (DBML), designed to define and document database structures
SchemaCrawlerFree database schema discovery and comprehension tool
dbdocsCreate web-based database documentation using DSL code
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.