Why document a database?

When managing a complex database, having detailed documentation about your database is the best way to understand your data, and simplify the access to important information for database architects, developers, business analysts, and administrators.

What is the documentation of a database?

The documentation of a database consists of relationship diagrams, lists of the tables and a brief description of what each table holds and how it relates to other tables.

How to document an existing database?

If you want to document an existing database, you have to reverse engineer it to generate the database schema model. (how to reverse engineer an existing database?)

There are many ways to document your model, you can use database management tools, documentation tools or data modeling tools. I will recommend using a data modeling tool (such as ERBuilder that I will use in this post) because of their ability for generating ER Diagrams from an existing database.

ERBuilder is a complete data modeling tool that you can reverse engineer your database with (supported databases: Oracle, MS SQL Server, MySQL, PostgreSQL, Firebird, SQLite, Azure Database and Amazon Redshift). ERBuilder also allows the description of each object of your data model and the generation of an HTML documentation report, including diagrams and all objects of the data model.

To document your database follow these steps:

1- Reverse engineer your database with ERBuilder (how to reverse engineer an existing database?)

2- After reverse engineering, you obtain a data model for your database in the workspace area

3- Browse the TreeView explorer to view imported schema objects. You can now add your description for :

Tables, columns, and relationships (foreign keys)

Views, triggers, and stored procedures

Sequence and domains

4- Now, generate the documentation for the data model by clicking on “Tools” and “Generate Model Documentation”

5- Select what elements of your model you want to include in the generated documentation

6- Select a folder to save the document then click “OK” to generate the model documentation. As shown in the following figure:

7- Once the document generated you can open it with your favorite navigator. As shown in the following figure:

The documentation homepage with ER Diagram included (with the ability to zoom in a part of the diagram)

Navigate into the generated documentation using the left sidebar that contains a menu for each object of the data model.

The tables view contains details about the table metadata.

The columns view contains details for each column of the data model with a link to their table.

Details view for a specific column.

The relationship view contains details about each relationship of the data model.