This document discusses how to properly document a database. It begins by explaining why database documentation is important, as databases can become large, complex, and vague over time. It then defines what database documentation entails, such as a data dictionary, entity relationship diagrams (ERDs), documentation of code, and metadata. The document concludes by recommending that database documentation be done as part of the design and development process and that dedicated documentation tools can help automate and standardize the process.

1. How to document a database
Piotr Kononow
Dataedo
https://dataedo.com

2. Agenda
I. Why document
II. What is database documentation
III. How to document

3. I. WHY
DOCUMENT

4. Need to data access & analysis is growing
Google search
https://dataedo.com

5. Databases are vague
Sample table and column names from real databases:
• MTL_SYSTEM_ITEMS_B – Raw materials?
• tP – Projects. Who would guess…
• BEN_PRTT_RMT_RQST_CTFN_PRVDD - ?
• RSRCSECX - ?
• ATTRIBUTE5 – Who knows…
https://dataedo.com

6. Databases are complex
Sample table in Oracle e-Business Suite (ERP)
https://dataedo.com

7. Databases are large
Number of tables and views in sample applications:
• Sample custom enterprise application: 3,000
• TETA (HRM): 9,000
• Oracle e-Business Suite (ERP): 55,000
• SAP (ERP): 130,000!
https://dataedo.com

8. …but as if addresses had following format:
PA_ADW_R_ACT_CMT_B_V.TXN_ADW_NOTIFY_FLAG
Finding a column is like trying to find an apartment in Manhattan

9. You need a map
https://dataedo.com

10. When is it useful?
• Software Development
• Data Warehousing, BI
• Data Analysis, Data Science, Big Bata
• Packaged application implementation – ERP, CRM, HRM,
billing etc.
• Application Integration (EAI, EII, MDM)
• Software/system maintenance
• Data Migration
• Data Quality
• Master Data Management
https://dataedo.com

11. II. WHAT IS
DATABASE DOCUMENTATION

12. 1. Data Dictionary
Table: employee
Table holds past, current and future company employees.
Column Data type Description
BusinessEntityID int Primary key for Employee records. Foreign key
to BusinessEntity.BusinessEntityID.
NationalIDNumber nvarchar(15) Unique national identification number such as
a social security number.
LoginID nvarchar(256) Network login.
OrganizationNode hierarchyid Where the employee is located in corporate
hierarchy.
OrganizationLevel smallint The depth of the employee in the corporate
hierarchy.
JobTitle nvarchar(50) Work title such as Buyer or Sales
Representative.
https://dataedo.com

13. Relations
https://dataedo.com
Table Role Foreign key column Description
Departments Works in DepartmentID Department where emplyee
People Manager ManagerID Employee superior
JobsDict Job title TitleID Employee job title

14. Statuses
Employee row can be in following statuses based on dates:
• Future – start_date > today or start_date null
• Current – start_date <= today and (end_date > today or null)
• Past – end_date < today
https://dataedo.com

15. List of Values
Column Description
MaritalStatus M = Married, S = Single, NULL = Unknown
ActiveFlag 1 = Active, 0 = Inactive
https://dataedo.com

16. Data Access Interface
To modify and fetch data use this:
• employee_get – returns specified employee row
• employees_get – returns selected employees
• employee_insert – use this to insert new employee
• employee_update – use this to update employee row
• employee_delete – use this to delete employee
https://dataedo.com

17. Usage
View: employees_active_v
Used by: Employees search form,
Active employees report
https://dataedo.com

18. Data Source
Table: employee
Data source: Employees form, sync_employees
Column Source
MaritalStatus Employees form
NationalIDNumber Employees form
Number emp_no trigger
Score Data warehouse, calc_employees_scores
https://dataedo.com

19. Other Metadata
Table: po_headers_all (Purchase orders)
Subject Area: Purchasing
Owner: Piotr Kononow
Column
po_header_id
po_header_number [OBSOLETE]
po_header_code
qty Quantity
value qty * unit_price
https://dataedo.com

20. Meaningful Descriptions
Instead of this:
Column Description
number Invoice number
date Invoice date
https://dataedo.com

21. Meaningful Descriptions
Do this:
Column Description
number Invoice autogenerated number, starting from 1 each
year. Number is generated when invoice gets
approved.
date Invoice issue date. Null for working copy invoices. Set
to today’s date on invoice approval.
https://dataedo.com

22. 2. ERDs – The Good
https://dataedo.com

23. ERDs – The Bad
https://dataedo.com

24. ERD is not this:
https://dataedo.com

25. But this:
https://dataedo.com

26. 3. Document Code
https://dataedo.com

27. Metadata, Change History
https://dataedo.com

28. III. HOW TO
DOCUMENT

29. Rule of thumb:
Document as you design and develop
https://dataedo.com

30. What tools to use?
• MS Excel, MS Word, Notepad
• Database console
• Dedicated tool
https://dataedo.com

31. Database console – Description
Not most convenient
https://dataedo.com

32. Dedicated tools
• Dataedo
• Redgate SQL Doc
• ApexSQL Doc
https://dataedo.com

33. Dedicated tools
https://dataedo.com

34. Dedicated tools
https://dataedo.com

35. Thank you
Piotr Kononow
Learn more at:
https://dataedo.com/blog