Re: A good way to keep documentation for databases as DBA

From: Tim X <timx_at_nospam.dev.null>
Date: Fri, 18 Jun 2010 08:34:13 +1000
Message-ID: <87wrtx1e6y.fsf_at_rapttech.com.au>



Mark D Powell <Mark.Powell2_at_hp.com> writes:

> On Jun 6, 2:41 pm, Big George <jbet..._at_gmail.com> wrote:
>> Hello,
>>
>> I'm following my own practices to document my job on databases, but
>> also I'm wondering if they are correct or how other DBAs manage their
>> own documentation for a day-to-day job.
>>
>> We have about 5 instances or databases to check. Each instance has a
>> number of schemas or users, tablespaces and datafiles, blobs, indexes
>> etc.
>>
>> On my Windows XP, I distribute my documentation in folders and Excel
>> files.
>>
>> I keep my scripts or queries as small text files. If I have 10 text
>> files, each text file has one script or a documented command. These
>> text files are storaged in folders. For example, one root folder is
>> named "Scripts and Commands" that contains general scripts and useful
>> commands for an Oracle DBA . This folder is divided by sub-folders.
>> For example sub-folder "Tablespace_Management" contains scripts and
>> commands for managing tablespaces.
>>
>> Other root folder is named "Instance_1", which is the name of our
>> instance 1. It contains scripts for recreating schemas, users,
>> tablespaces, etc of that instance. It also contains specific queries
>> for end-user information.
>> This folder contains sub-folder "Backup_Management" which has docs
>> about the backup process.
>>
>> Also, I keep an important Excel file with many sheets. One sheet lists
>> server's IP, instances, schemas, passwords and some comments. Another
>> sheet lists instances, schemas and tablespaces. Another sheet lists
>> database servers and performance features like model, memory,
>> processors, hard disks, etc.
>>
>> I update manually this Excel file every three days by querying my
>> databases or after any big change that I made to a database.
>>
>> Of course I also use EM db console and Toad.
>>
>> Is there any advice or suggestion that you could provide?
>>
>> Thanks a lot !
>
> How you organize your scripts and reference documentation should be
> done in a manner that makes sense to you and your teammates.
>
> Mine are organized in my UNIX home directory under a directory named
> ora then in subdirectories by functional grouping. I have a
> subdirectory for scritps related to tables, indexes on the table,
> columns in an index, FK to a table, and so one. I have another
> directory for information related to database data files, tablespaces,
> redo logs, and undo segments.
>
> I back my scritps up by copying my scritps from my development server
> to my production server so I have access to my scripts on each server
> I need to work on. If you are placing your information folders on the
> same server as your database you should give some though to their
> availability in the event of a media problem on the server.
>

Essentialy, I have a defined directory hierarchy and the whole tree is managed inside version control. I was using SVN, but I'm now using GIT.

Apart from tracking changes to scripts and documentation, this also has the nice advantage that all my stuff is maintained on our revision control system, which is backed up nightly. It also has the advantage that if I'm setting u a new system, or owrking on a different server, I can just do a checkout and all my files are there with the latest version. I also have control over who can access the repository, so I can grant/revoke access to others on the team. So, I get

  1. automatic backup of everything
  2. Easy access from any server
  3. Ability to share the data
  4. An audit trail for changes

The last two are very useful. If I'm away or off sick, important info/scripts are not locked away on my deskto where others can't get to them. Also, when I return, provided team members have checked in changes (and they are required to), I can see what has been changed and check nothing bad has occured. Using the revision control system also makes it possible to have a level of peer review, which think is important as it helps catch mistakes earlier and ensures we have less in the way of separate silos of key knowledge only known by one person etc.

Highly recommend using a revision control system. Doesn't really matter which one. I like GIT, but some find it conceptually challenging. Mercurial (Hg) is very similar, but apparently a bit more user friendly. Bazaar (bzr) is also pretty good. Even subversion is better than nothing!

Tim

-- 
tcross (at) rapttech dot com dot au
Received on Thu Jun 17 2010 - 17:34:13 CDT

Original text of this message