We all know what a right PITA it is keeping database documentation up to date. You’ll get a column added to the schema, and make a mental note to update the docs with the intricacies of how it works, then you’ll get distracted by something, never get around to it, then six months later you’ll be trying to remember the details.

Fortunately, the newer versions of Oracle have a rather marvellous commenting feature for tables and columns, so you can document it at the same time as you build it.

To put a comment on a table:

COMMENT ON TABLE xyz IS ‘This is a table for recording xyz usage’

Or on a column

COMMENT ON COLUMN xyz.frequency IS ‘Frequency of xyz usage’

Now, this might be of limited use if you couldn’t get the information out easily. Fortunately, you can. Apart from turning on the comments options in schema browsers such as TOAD, you can get a list of table names with their comments like this:

SELECT t.table_name, t.comments
FROM all_tab_comments t
WHERE t.owner = ‘tableowner’
AND t.comments IS NOT NULL
ORDER BY t.table_name

…and the following will generate a nice list of tables, columns, column types and their comments:

SELECT c.table_name, c.column_name, ac.data_type, ac.data_length, ac.nullable, c.comments
FROM all_col_comments c, all_tab_columns ac
WHERE c.owner = ‘tableowner’ and c.column_name = ac.column_name and c.table_name = ac.table_name
ORDER BY c.table_name, ac.column_id

Mind you, the data length field comes out a bit funny for CLOBs and Numbers. Still, with a little imagination you can write up a quick program to format this output nicely in HTML or WikiText or whatever, for your database documentation.