Re: [SQL] Documenting a DB schema

Steve Crawford <scrawford@xxxxxxxxxxxxxxxxxxxx> · Tue, 04 Mar 2008 13:27:15 -0800

Shahaf Abileah wrote:

  I’m looking for a
systematic way to document the
schema for the database behind our website (www.redfin.com),
so that the developers
using this database have a better idea what all the tables and columns
mean and
what data to expect.  Any recommendations?

  It would be great if the
documentation could be kept as
close to the code as possible – that way we stand a chance of keeping
it
up to date.  So, in the same way that Java docs go right there on top
of
the class or method definitions, it would be great if I could attach my
comments to the table definitions. It looks like MySQL has that kind of
capability:

create table table_with_comments(a int comment 'this is column a...');

  (see http://dev.mysql.com/doc/refman/5.0/en/create-table.html)

  However, Postgres doesn’t
support the
“comment” keyword.  Is there an alternative?

You mean like:

COMMENT ON mytable IS 'This is my table. Mine, mine, mine';

You can also comment columns, databases, functions, schemas, domains,
etc.

Cheers,

Steve