Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

How to document a database

4,868 views

Published on

Why and how to document relational databases.

Published in: Software
  • Hello! Get Your Professional Job-Winning Resume Here - Check our website! https://vk.cc/818RFv
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Thank you for sharing this material, simple and concret
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Your starting point for was is documented is an (implemented) database. It should (at least in some version) but documented from the user's perspective, for the user. This particularly means that all the terms (entity and attribute names) should be in terms of the business. AND they should be fully defined. That should be done without any consideration of physical implementation, as in a DBMS. This would include omitting any intersection entity to represent a many-to-many relationship (unless the relationship has attributes, in other words, if there is some other information which is determined by or dependent upon the composite key, that is BOTH of the entities in the relationship),
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • @hansmichielscom thank you. If you can use source control then your development will be more managed. Those two approaches can work together nicely.
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Thank you sir for the expressive informative explanation of the importance , methods , and means of database documentation
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here

How to document a database

  1. 1. How to document a database Piotr Kononow Dataedo https://dataedo.com
  2. 2. Agenda I. Why document II. What is database documentation III. How to document
  3. 3. I. WHY DOCUMENT
  4. 4. Need to data access & analysis is growing Google search https://dataedo.com
  5. 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. 6. Databases are complex Sample table in Oracle e-Business Suite (ERP) https://dataedo.com
  7. 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. 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. 9. You need a map https://dataedo.com
  10. 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. 11. II. WHAT IS DATABASE DOCUMENTATION
  12. 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. 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. 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. 15. List of Values Column Description MaritalStatus M = Married, S = Single, NULL = Unknown ActiveFlag 1 = Active, 0 = Inactive https://dataedo.com
  16. 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. 17. Usage View: employees_active_v Used by: Employees search form, Active employees report https://dataedo.com
  18. 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. 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. 20. Meaningful Descriptions Instead of this: Column Description number Invoice number date Invoice date https://dataedo.com
  21. 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. 22. 2. ERDs – The Good https://dataedo.com
  23. 23. ERDs – The Bad https://dataedo.com
  24. 24. ERD is not this: https://dataedo.com
  25. 25. But this: https://dataedo.com
  26. 26. 3. Document Code https://dataedo.com
  27. 27. Metadata, Change History https://dataedo.com
  28. 28. III. HOW TO DOCUMENT
  29. 29. Rule of thumb: Document as you design and develop https://dataedo.com
  30. 30. What tools to use? • MS Excel, MS Word, Notepad • Database console • Dedicated tool https://dataedo.com
  31. 31. Database console – Description Not most convenient https://dataedo.com
  32. 32. Dedicated tools • Dataedo • Redgate SQL Doc • ApexSQL Doc https://dataedo.com
  33. 33. Dedicated tools https://dataedo.com
  34. 34. Dedicated tools https://dataedo.com
  35. 35. Thank you Piotr Kononow Learn more at: https://dataedo.com/blog

×