Back to articles list
Entity-relationship diagram (ER diagram) documentation is an important part of any database project. Find out how to use Vertabelo to generate database documentation from SQL.
Writing good documentation is as hard as writing good code. Some say that teams who don’t invest in good documentation early on pay a high price later. Databases and data warehouses are central to business applications. Just like an application mandates good reference documentation for APIs, SDKs, repositories, etc., data models also need to be documented to understand the database, capture changes, and ease future development.
Many different approaches are commonly used for ERD diagram documentation, such as text annotation within the data model, text documentation, SQL model documentation, etc. You can use more than one approach to create documentation for your data model. This article will explain the benefits of documentation and explore the ERD documentation methods offered in Vertabelo.
Why Is Documentation Important?
Data model documentation should not be seen as a mere formality. There are many use cases where documentation is very helpful.
Documentation acts as the map to your data model. It helps you easily navigate the model with the help of images, text, and SQL DDL code. When all the information mentioned above is readily available, you can use the documentation to understand the current state of the database system, think about future changes, and even debug issues.
Data model documentation isn’t just helpful for the application and database administration teams. It helps everyone who will consume the model’s data downstream, such as data engineers, analysts, etc. In ETL, the data model for a source database is central in defining the ETL processes that load the data into the target system. Good ER diagram documentation helps a lot in such scenarios.
Generating Documentation in Vertabelo
There’s no single standard way to create ERD diagram documentation. You can export the data model as an image and annotate that image with text later, as and when required. You can also export the data model DDL, which could well be the only piece of data model documentation you have. Conscious of the need for good documentation, the Vertabelo team built in as much assistance as possible; they provided four different options in Vertabelo for automatically generating data model documentation. Let’s discuss each of them individually.
Exporting the Model to an Image
You can use this feature to export your data model as an image. A single image for complex data models can be challenging to navigate. Using the What to print option, you can choose a part of the data model to export as an image. This is very useful when you have already created logical groupings in your data model, i.e. using subject areas. To export your data model to an image, go to the main toolbar and select Export model to image, as shown below:
You can choose your desired image file format (SVG or PNG); select SVG if you want your images to scale up without losing quality.
Exporting the Model to PDF
People who work with complex data models daily might find it helpful to have a printout at their desks. Vertabelo’s Export to PDF feature allows you to print your data model by first exporting it to a PDF file. To generate the PDF file for printing, go to the main toolbar and click Export model to PDF file, as shown below:
A pop-up with an option to GENERATE the PDF file will open. Once generated, you can download the file.
Data models come in all shapes and sizes. They are organized differently by different teams; there’s no universal way to organize a database model. Considering that fact, Vertabelo gives you options to change the page size, orientation, margins, breaks, and footers. You can make these changes by clicking on the Format option or going to the Format tab in the Model Properties sidebar, as shown below:
For more information on how to configure the printouts, see this Vertabelo blog post.
Generating an SQL Script
Until now, we’ve seen two features that concentrate on the visual aspect of the ER diagram documentation. However, one of the essential documents for an engineer or an analyst using the database is the DDL. Let’s learn how to generate SQL model documentation using Vertabelo’s SQL script generation feature.
The SQL script generation feature is also central to the concept of migration scripts. Databases change from time to time. To migrate data from one state to another or one version to another, Vertabelo’s Generate SQL preview comes in very handy. Our blog has additional information on generating migration scripts in Vertabelo.
In the image below, you see the options to generate a create or a drop SQL script for the selected data model objects:
Generating Model Documentation
This is a text-based export of all essential data model information into a well-formatted and well-organized PDF document. To generate this document, go to the Generate model documentation option in the main toolbar:
Once you click on the main toolbar option, you’ll be asked to choose between one of three formats ( PDF, HTML, or DOCX). Each format serves a different purpose. Although you can edit the documentation after exporting it to any format, editing is easiest in the DOCX format. If you want to upload this document to a central repository, PDF might be your best choice. Finally, choose HTML if you're going to host this on a public or internal website or in your Git repository.
Other ER Diagram Documentation Options
Publishing to the Web
You can publish the data model on the web by simply choosing the Publish to Web option:
Once you publish your data model online, it will be available to anyone with the link. (This is what a data model on the web looks like in Vertabelo.) You always have the option to unpublish the data model, as shown below:
Exporting the Data Model
Although you can export the data model to an image or PDF using the menu bar, you can also perform the same action using the Export option, as shown in the image below:
There’s also an option to export to an XML file, which can also be obtained using the Vertabelo API.
Share Your Thoughts on ER Diagram Documentation
ER diagram documentation is a tedious task, especially for data models with many tables and subject areas. We believe that database engineers and analysts should spend time creating features rather than manually creating documentation.
In this article, you learned the different Vertabelo features that automate data model documentation while still leaving room for you to add additional information about the documentation. It makes your life easier!
We’d be happy to learn about your experiences in database and ERD documentation. Let us know in the comments section or write to us at contact@vertabelo.com.
