tbls

1. Introduction

In the dynamic world of database management, keeping documentation accurate and current is a constant challenge for development teams. tbls emerges as a powerful solution, offering a CI-friendly approach to database documentation. It transforms how teams manage and maintain their database schemas. This command-line tool, built with Go, automates the generation of comprehensive database documentation, proving itself to be an essential tool for development teams of all sizes. Think of it as a way to ensure your database documentation is always in sync with your actual database structure—pretty neat.

Currently, what sets tbls apart is its extensive database support, covering everything from traditional relational databases to modern cloud solutions. Whether you're working with PostgreSQL, MySQL, and SQLite, or cloud-native services like Amazon Redshift, Google BigQuery, and Cloud Spanner, tbls has you covered. This broad compatibility makes tbls an invaluable tool for organizations with diverse database ecosystems or those planning to scale their infrastructure across different database platforms.

The real magic of tbls is how it bridges the gap between database schema changes and documentation updates. Traditional documentation methods quickly become outdated, leading to confusion and errors, not to mention wasting precious development time. tbls tackles these issues head-on by providing an automated, reliable way to generate and maintain database documentation that evolves alongside the database itself. It's like having a personal assistant for your database, constantly keeping everything tidy and up-to-date.

tbls was originally created as an open-source project by k1LoW and has gained widespread adoption across various industries. Because it’s open-source, the community is always contributing new features, bug fixes, and improvements, ensuring it keeps up with modern documentation needs. It’s a testament to the power of community-driven development.

GitHub Star History

star-history.com

At its core, tbls automates database documentation by directly analyzing schemas and generating output in Markdown, PlantUML, and DOT formats. Like our Liam ERD, tbls shares the vision of making technical documentation both accessible and current. Its seamless CI pipeline integration ensures documentation stays synchronized with database changes, effectively preventing documentation drift throughout the development lifecycle.

2. Understanding tbls Core Features

Documentation Generation

tbls shines in its primary role of generating thorough database documentation. It automatically creates detailed documentation that covers table definitions, column specifications, indexes, and constraints. This documentation is presented in an organized format, making it easy for everyone on the team to understand the database structure. The generated documentation doesn't just include the basics; it also includes relationships between tables, making it a great resource for both new and experienced developers. It's like having a detailed map of your database, making it easy to navigate.

Format Flexibility

One of tbls's most impressive features is its support for multiple output formats. It can generate documentation in Markdown, DOT, PlantUML, and even visual formats like SVG and PNG for ER diagrams. This flexibility allows teams to choose the format that best suits their needs, whether it’s detailed technical documentation or visual representations of database relationships. It’s all about picking the right tool for the job, and tbls gives you plenty of options.

tbls/sample/mysql/logs.svg at main · k1LoW/tbls

github.com

Integration Capabilities

tbls is designed to fit into modern development workflows, offering seamless integration with CI/CD pipelines. It can be easily incorporated into existing processes, allowing teams to automatically verify and update documentation as part of their regular build and deployment cycles. This ensures that documentation remains current with every schema change, reducing the risk of outdated information. It’s like having a vigilant guardian, ensuring your documentation is always up-to-date and accurate.

3. Benefits of Database Documentation with tbls

Improved Documentation Accuracy

The automated nature of tbls drastically improves the accuracy of your database documentation. By generating documentation directly from the database schema, tbls eliminates human errors and ensures that documentation always reflects the current state of the database. This is particularly valuable in fast-paced environments where manual updates can easily be overlooked. It’s like having a meticulous scribe, ensuring every detail is captured correctly.

Enhanced Team Collaboration

tbls fosters better team collaboration by providing a single source of truth for database documentation. Team members can rely on the generated documentation to understand the database structure, relationships, and constraints without digging through code or making assumptions. This shared understanding reduces miscommunication and improves development efficiency. It’s like having a common language that everyone on the team understands.

Streamlined Onboarding Process

New team members benefit significantly from the clear, comprehensive documentation that tbls provides. The tool's ability to create visual representations of database relationships, along with detailed table and column descriptions, accelerates the onboarding process. New developers can quickly understand the database structure and contribute more effectively, reducing the time and resources needed for training. It’s like having a welcoming guide that helps new team members get up to speed quickly.

4. Implementing tbls in Your Workflow

Installation and Basic Setup

Since tbls is a single-binary tool, the installation process is simple. It can be installed via popular package managers or by using Docker.

For macOS users, Homebrew provides an easy way to install tbls by running the following command in the terminal:

brew install k1LoW/tap/tbls

If you prefer to use a .deb or .rpm package, you can download the appropriate file from the releases page and install it using dpkg -i or rpm -ivh.

Alternatively, Docker offers another installation option. To pull the latest version, execute:

docker pull ghcr.io/k1low/tbls:latest

For those who use Go, the tool can be installed directly with:

go install github.com/k1LoW/tbls@latest

Once installed, the next step is to create a configuration file—.tbls.yml or tbls.yml—in the root of your project. This file defines how tbls interacts with your database. The most critical settings include:

• The DSN (Data Source Name), which specifies how tbls connects to the database (e.g., postgres://user:password@host:5432/dbname).
• The documentation path, indicating where generated files should be stored (e.g., doc/schema).

With these settings in place, tbls knows both where to retrieve schema information and where to store the generated documentation.

Quick Setup

Setting up tbls follows a straightforward workflow.

Installing tbls

The first step is to install the tool using one of the methods outlined above, then verify the installation by running:

tbls version

Creating a Configuration File

To configure tbls, create a .tbls.yml file in your project directory with the following structure:

dsn: postgres://dbuser:dbpass@localhost:5432/dbname
docPath: doc/schema

This should be adjusted according to your database type and the preferred output directory.

Generating Documentation

Once the configuration is set up, documentation can be generated using:

# Specify the DSN directly
tbls doc postgres://dbuser:dbpass@localhost:5432/dbname
 
# Or rely on the configuration file
tbls doc

After execution, the docPath directory (e.g., doc/schema) will contain schema documentation in Markdown format, along with ER diagrams and other useful files.

Managing Changes

To maintain up-to-date documentation:

• Version control: Commit generated documentation files to track changes.
• CI/CD automation: Incorporate checks such as tbls diff for schema changes and tbls lint for validation, making it easier to integrate with platforms like GitHub Actions.

Integration Practices

To ensure consistency across teams, adopting a few best practices can improve documentation quality and reliability.

Using a Dedicated Documentation Environment

Generating documentation from a clean, isolated database instance prevents inconsistencies caused by incomplete migrations or test data. This approach ensures stable and reproducible documentation.

Automating with Makefile

A Makefile can simplify the documentation process by automating database setup and schema generation:

doc/schema:
  docker-compose run --rm -e ENV=tbls db bundle exec rake db:setup
  docker-compose run --rm -e ENV=tbls db bundle exec rake db:migrate
  docker-compose run --rm tbls doc -f

By resetting the database and executing tbls doc, this ensures the documentation reflects the current schema accurately.

Continuous Integration

Integrating tbls into CI/CD pipelines ensures documentation remains updated. By running:

tbls diff
tbls lint

on every push or pull request, discrepancies can be identified early, preventing outdated documentation from affecting production.

By incorporating these steps into your workflow, tbls becomes a seamless tool for maintaining clear and accurate database documentation. For the latest details and updates, refer to the official tbls documentation.

5. Advanced Features of tbls

Customization and Templates

tbls offers extensive customization options through its configuration system. The tool supports personalized templates that allow teams to tailor the documentation format to their specific needs. Through the templates section in the configuration file, you can modify how both Markdown documents and ER diagrams are generated. This flexibility enables organizations to maintain consistency with their existing documentation standards while leveraging tbls’s automation. It’s about making the tool fit your specific style and needs.

The template system supports various output formats, including:

• Markdown for readable documentation
• DOT format for customized ER diagrams
• PlantUML for alternative visualization
• JSON/YAML for machine-readable schema information

Advanced Configuration Options

Beyond basic setup, tbls provides sophisticated configuration options for managing complex documentation needs. The tool supports features like filtering tables, managing relations without foreign keys, and customizing documentation comments without altering the database schema. These capabilities are particularly valuable in environments where direct database modifications are restricted or when dealing with legacy systems. It’s like having a toolkit with specialized instruments for different situations.

For example, you can define virtual relations in your configuration:

relations:
  - table: logs
    columns:
      - user_id
    parentTable: users
    parentColumns:
      - id
    def: "logs->users"

This allows documentation to reflect logical relationships even when they’re not explicitly defined in the database schema. It’s about making sure your documentation captures the full picture, even the parts that aren’t obvious.

6. Case Studies

Organizations across various industries have successfully implemented tbls to improve their database documentation practices. Below are a examples that illustrate how tbls can be adapted to different environments and business needs. It's always inspiring to see how others are using the tool.

• Mercari
  Mercari, a leading e-commerce platform, integrated tbls to manage the complexities of its evolving database schema, especially within its Merpay Smart Payment service. By automating ER diagram generation and labeling tables by functional domain, Mercari streamlined internal documentation. The team also used custom templates to enhance readability, showcasing tbls’s flexibility in large-scale, rapidly changing environments. It’s a great example of how tbls can scale to meet the needs of a large organization.

• Money Forward
  Money Forward adopted tbls to maintain up-to-date documentation for its extensive financial database schema. The automation significantly reduced the time spent on manual updates, helping teams stay aligned on schema changes and ensuring critical financial data was accurately documented. It’s about keeping everyone on the same page when dealing with complex financial data.

• GMO Makeshop
  GMO Makeshop integrated tbls into its CI/CD pipeline, eliminating documentation drift by continuously generating documentation that aligned with their evolving database schema. This approach provided immediate feedback to developers, ensuring every change was reflected and verified in real time. It’s about catching errors early and keeping everything in sync.

• Pepabo Tech (Color Me)
  Pepabo Tech’s Color Me e-commerce platform introduced tbls for maintaining ongoing documentation across multiple database management systems, including PostgreSQL and BigQuery. Their experience highlights tbls’s versatility in supporting diverse DBMS environments while keeping documentation consistent. It’s a testament to the tool's ability to handle different types of databases.

The practical impact of tbls has been substantial in real-world database documentation. Teams have experienced significant improvements in documentation accuracy through automated generation directly from database schemas, effectively eliminating inconsistencies and manual errors.

Developer productivity has increased as the automated documentation process integrated with CI/CD pipelines removes the need for manual updates, allowing engineers to focus on core development tasks.

The standardized documentation format and visual ER diagrams have streamlined cross-team communication, enabling quick comprehension of data structures across technical teams and accelerating knowledge transfer during onboarding. This clarity has proven particularly valuable in complex database environments where maintaining accurate documentation is critical for system maintenance and evolution

7. Evolving Database Documentation with tbls

Starting with tbls opens up powerful automation opportunities for your database documentation workflow. While the initial setup involves basic configuration through CLI and .tbls.yml, the tool's true potential emerges through CI/CD integration.

Key enhancement paths include integrating documentation checks with schema migrations, implementing automated drift detection, and establishing environment-specific configurations. Security considerations are addressed through environment variables and secure credential management patterns.

Advanced implementations often leverage custom templates to combine technical schema details with business context. The output can serve as a foundation for interactive documentation portals, effectively turning your database documentation into a reliable, auto-updating source of truth.

As your system grows, tbls adapts - from handling simple schemas to managing complex multi-environment setups. Each schema iteration naturally updates documentation, maintaining accuracy without manual intervention. This systematic approach to documentation makes database changes more predictable and helps teams maintain high-quality documentation even as systems scale.

8. tbls and Liam ERD

tbls has achieved seamless integration with our Liam ERD, a complementary tool that renders interactive ER diagrams from tbls-generated schema.json files.

Developers can now instantly access interactive ER diagrams in their browser by simply prepending 'liambx.com/erd/p/' to a public schema.json URL. This visualization feature significantly enhances understanding of database structures.

Furthermore, team members can share live diagrams without requiring additional plugins or tools, making schema comprehension more accessible across different roles. This streamlines collaboration and enables more efficient teamwork.

This integration represents a crucial step in making database documentation more user-friendly and accessible, transforming how teams interact with and understand their database structures.

Getting Started

If you already use tbls to output schema.json:

Public Projects

• Host schema.json in a public repo.
• Prepend liambx.com/erd/p/ to its URL to visualize the ER diagram.

Private/Local Projects

# Generate schema.json
tbls out -t json schema.json
 
# Build ER diagram from schema.json
npx @liam-hq/cli erd build --format tbls --input schema.json

Serve or view locally for private setups.

Learning Resource: This content is designed to help Liam users learn and grow their skills. For the most current information, please check our official documentation and vendor-specific resources.

GitHub - liam-hq/liam: Automatically generates beautiful and easy-to-read ER diagrams from your database.

github.com