THE SQL Server Blog Spot on the Web

Welcome to - The SQL Server blog spot on the web Sign in | |
in Search

The Rambling DBA: Jonathan Kehayias

The random ramblings and rantings of frazzled SQL Server DBA

The Importance of Good Documentation

When I first became a DBA, one of the first things I did was create a DBA "run book" that contained detailed information about every SQL Server that I was under my realm of responsibility.  I can't tell you the source reference for this idea off hand, but I will admit, that the idea of creating a run book wasn't my own, I read about it online (to be honest, I am pretty sure it was a SQL Server Central article or forums post).  For the last three years I have made a point to review this document quarterly and make updates to it to reflect ongoing changes to my environment.  My intention in doing this was to make sure that a smooth and rapid transition was possible in the event that I was called to Active Duty by the Army Reserves.

However, until recently I didn't quite realize the importance of such a document until I had to sit down in a meeting to plan the hand off of responsibility from myself to another DBA of my companies production environment as a part of my mobilization with the Army.  It turned out that every question that my management staff could ask was covered in my run book already which meant two things.  First it meant that there was a quick reference for while I am going to be gone that covers each server, what it is for, how it is backed up, who to contact in case there is a problem with the server, and any special circumstances related to the particular server like SOX Audited databases.  Second, it further demonstrated my value and worth to the company as a DBA.

So what exactly should a "run book" cover?  Well I basically hit it in the last paragraph.  For each server in your environment, the "run book" should have a section that covers, the applications/databases supported by the server, who the interested parties are for each application/database with their contact information, the backup methodology for the server/databases on the server, the servers hardware and software configurations, and any special circumstances related to the server/databases on the server like SOX Auditing .  I include some basic information in a few Appendix's that cover environment specific information like how backups are performed, maintained, and the fastest way to recovery in the event a restore from backup is required, and how to create a new SQL Server in the environment following established and approved configuration practices.  If you use a third party tool like Netbackup for backups to a common device this kind of thing is important to document.  In addition to this standardized information, I also included a section with code examples on how to troubleshoot common problems in SQL Server since my primary backup DBA is not a SQL Server DBA but instead an Oracle DBA (one thing I've learned is that we do the same job fundamentally, we just have different ways on performing the tasks).

So what exactly did it cost me to make this kind of documentation?  About 2 days of time for an environment of approximately 30 SQL Severs up front, and the around a 1/2 a day every quarter to review it and make necessary changes to update the documentation to bring it current.  This cost in time is minimal compared to the time it would have taken for me to explain my environment to someone new in the event that I was activated by the Army Reserves like recently happened.  In addition, my management staff could provide the documentation to almost anyone and they would be able to be up to speed on the environment within a few days time.

Published Friday, July 31, 2009 4:14 AM by Jonathan Kehayias



Adam Machanic said:

Great post. Unfortunate that it had to be spurred by such a very real-world example, but I certainly appreciate it all the more for that fact.

July 31, 2009 8:23 AM

Karen Lopez said:

I wish more IT professionals would think about having a run book for everything.  I mean, what if your sysadmin wins the MegaPowerUberLottery and doesn't even bother to take her coat when she leaves for a better life sailing around the world?

I'm also thinking that a good chunk of the run book could be generated from tools.  All that would be needed is some annotation to put all that information in context.

Wonderful post.

July 31, 2009 9:31 AM

Ranga Narasimhan said:

I Appreciate you for taking time to write this post when you are called for military duty and you have million other things to take care of!

good luck!

July 31, 2009 2:38 PM

Jason said:

I'd love to see some examples of what others are using. I'm digging through the tubes trying to find some now.

August 4, 2009 11:59 AM

John said:

One thing I have found that is worth including but often forgotten is details of SSL certificates installed on the server - the provider and expiry date, plus details of the applications that rely on them for encrypted communications and where/how this is configured.


February 6, 2011 8:50 AM
Anonymous comments are disabled

This Blog


Privacy Statement