On Tue, Mar 04, 2008 at 12:02:27PM -0800, Shahaf Abileah wrote:
> 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?
You can and should be using COMMENT ON for the important database
objects.
http://www.postgresql.org/docs/current/static/sql-comment.html
> 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.
If your schema is changing substantively (i.e. anything other than
adding/dropping table partitions) with any frequency, that's a sign of
a broken design process which you need to fix.
> 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:
See above re: COMMENT ON :)
> 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.
Actually, it does :)
> Is there an alternative?
Cheers,
David.
--
David Fetter <david@fetter.org> http://fetter.org/
Phone: +1 415 235 3778 AIM: dfetter666 Yahoo!: dfetter
Skype: davidfetter XMPP: david.fetter@gmail.com
Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate