Documenting a DB schema

I'm looking for a systematic way to document the schema for the database
behind our website (www.redfin.com <http://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?

Thanks,

--S

Shahaf Abileah | Lead Software Developer

shahaf(at)redfin(dot)com | tel: 206.859.2869 | fax: 877.733.3469

Redfin Corporation
710 2nd Ave
Suite 600
Seattle, WA 98104