Database documentation plays a crucial role in maintaining and scaling systems. Clear and well-organized documentation can significantly improve communication between team members and enhance project longevity.

One of the most efficient ways to document a database is through dbdocs and DBML - an open sourced Database Markup Language.

In this guide, I’ll show you how to create database documentation using these tools, step by step.

What is dbdocs?

dbdocs is a platform that generates database documentation from your schema, easily shareable via a link. Using DBML (Database Markup Language), you can create clear, shareable, and updatable documentation of your database structure.

Prerequisites

Before we begin, ensure you have the following:

• Basic knowledge of databases and SQL.
• A database schema to document (we’ll use a PostgreSQL example in this guide).

Step 1: Install DBML CLI and dbdocs

Start by installing the DBML CLI, which helps convert your database schema into a DBML format. You also need the dbdocs CLI to generate and publish your documentation.

npm install -g dbdocs

Step 2: Export Your Database Schema to DBML

If you’re working with an existing database, you can export the schema into DBML using the DBML CLI tool.

For PostgreSQL, run the following command:

$ dbdocs db2dbml postgres <connection-string> -o database.dbml

✔ Connecting to database <db-name>... done.
✔ Generating DBML... done.
✔ Wrote to database.dbml

This command will export your database schema and save it into a file called database.dbml.

Here’s an example of how a generated DBML file might look:

Table users {
  id int [pk, increment]
  username varchar(50) [not null]
  email varchar(100) [not null, unique]
  created_at timestamp [not null]
}

Table orders {
  id int [pk, increment]
  user_id int [not null, ref: > users.id]
  total decimal [not null]
  created_at timestamp [not null]
}

In this example:

• The users and orders tables are defined.

• Fields are annotated with types and constraints.

• The relationship between orders.user_id and users.id is established using ref.

Step 3: Edit and Add Notes to the DBML File

You may want to clean it up or add extra documentation like table descriptions and field descriptions to communicate with other members in the team.

Step 4: Generate Documentation with dbdocs

Once your DBML file is ready, the next step is to generate the documentation using dbdocs. First, you need to login to dbdocs:

dbdocs login

After logging in, publish the DBML file:

dbdocs build database.dbml

This command will generate a shareable documentation link that you can access via the dbdocs platform. You can also set access permissions and collaborate with your team.

This seamless workflow ensures that your documentation always reflects the latest state of your database.

Benefits of Using dbdocs with DBML

• Simplicity: The DBML syntax is simple and easy to learn, making it a perfect fit for teams.
• Automation: You can automate your database documentation updates as part of your CI/CD pipeline.
• Collaboration: Easily share documentation links with your team or stakeholders for easy access and discussion.
• Version Control: Use schema changelog to track database schema changes over time.
• Visualization: dbdocs provides a clean interface to visualize your database schema, relationships, and annotations. Try this demo to learn more.

Conclusion

In this tutorial, we explored how to export a database schema, customize it, and generate shareable documentation using dbdocs.

By incorporating this workflow into your development process, you’ll improve your team’s collaboration, enhance your project’s scalability, and ensure that everyone stays on the same page. Happy documenting!