As developers, we know that comprehensive database documentation is critical to any project. Whether we're introducing new team members, debugging, or merely trying to keep track of increasingly complex structures, a clear and up-to-date database diagram can be a lifesaver.

Recently, while working on an upcoming "The ETL Journey" blog post series, I needed a neat, comprehensive database model diagram that I could link directly to my GitHub repository. My goal was to provide a clear picture of all the tables and relationships that my application handles. The solution I discovered is worth sharing - introducing DBDocs!

How DBDocs Works

DBDocs is a fantastic tool that allows you to create database documentation and share it in a neat, easy-to-understand way. Here's how you can get started:

  1. Install DBDocs via the terminal using the npm command.
  2. Define your database structure using DBML (Database Markup Language) syntax.
  3. Connect to DBDocs cloud, automatically generating a link to an elegant UI displaying your defined database structure.

The Pros of DBDocs

  • It's completely free!
  • It's easy to set up.
  • It integrates seamlessly with GitHub actions to automatically update live documentation when your DBML definition changes.
  • You can search through tables, view column descriptions, and understand the relationships between models at a glance.
  • The user interface is clean and appealing.
  • DBDocs has a well-defined roadmap on its website, pointing to promising future developments.

The Cons of DBDocs

  • It's still in beta, so future pricing is uncertain, although it's currently free for individual database enthusiasts and open-source projects.
  • You don't "own" your diagrams since they're stored on the DBDocs cloud. This storage approach, however, enables the DBDocs team to release features and iterate more rapidly.

Final Thoughts

If you are looking for an efficient way to document and share your database structures, I highly recommend giving DBDocs a try, even out of curiosity. The tool provides an excellent balance between simplicity and functionality, saving you considerable time and effort.