DEV Community

loading...
Cover image for Documenting the DB: Data dictionaries

Documenting the DB: Data dictionaries

Anderson. J
Estudiante de ingeniería Back End Developer 👽
・3 min read

Hello DEV community! It's projects month in my college. I've been working for weeks in two projects, has been so stressfull but I learned a lot. One of the requirements that my teacher gived to me was a "Data dictionary" for the app's database. I found it interesting since I've never heard of that term. So today we all going to learn what is a data dictionary and how it can help us with our databases. Let's begin.

Data Dictionaries

"A data dictionary is a centralized repository of information about data such as meaning, relationships to other data, origin, usage, and format."

  • IBM Dictionary of Computing.

"Information about data" is the most important part about definition by IBM. A data dictionary provides detailed information about data, like default values, data types, allowed values, meanings of attributes and much more. We can call it a plus for documentation, because it gives to us concrete details about the attributes of our entities.

Key elements

Data dictionaries contain elements and necessaries features.

  • Name of all tables
  • Name and details of the attributes (optional/required, NOT NULL, data type, length, etc.)
  • Details of permissions
  • Table constraints (PK, FK, etc)
  • DB views
  • Comments about the function that fulfills an specific attribute.

Example

Field Name Data Type Field Size Description Example
ID Integer 10 Unique ID for each employee 143212
name TEXT 20 Name of the employee Anderson
Date_of_Birth Date/Time 10 DOB of Employee 08/03/1998

Documentation, Documentation, Documentation.

Now we are understanding data dictionaries right? It's obviously that everything is about documentation. We all know that we should write docs for other developers rather than for us. This kind of documentation it's aimed for DB admins, designers, developers, analysts, and any person whom has the permission to execute some SQL against the DB. And like the docs of your favourite library, data dictionaries improve development productivity, avoid errors and bugs, makes changes easy, improve team communication, and gives to us all benefits of a well written documentation.
It's a real problem when we work with databases that are growing and becoming more and more complex every day, we start to forget the table names, constraints, db views, permissions and more. Or also when we join to a new team and we need to get familiar with the DB relationship structure to start to be productive.
In that moment is when we need a data dictionary to the rescue.

How to create one?

Exist different tools when we're creating a data dictionary. The choice depends of the project complexity. There are tools that provide us simple solutions, they generate a .PDF with all information about the tables and columns. In the other hand exists tools more professionals that, in addition to the information matrix, provide us diagrams and other utilities for model our DB, these tools fit better with big teams and big DB's.

Some of the tools more populars are:

Conclusion

If you want to documentate your database in detail, the best would be use a data dictionary as reference. Add many details as you require and follow the best practices like you're writting documentation. Your future self will appreciate it, and also your co-workers.

Discussion (0)