Thread: Documenting a DB schema
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?
Thanks,
--S
Shahaf Abileah | Lead Software Developer
shahaf@redfin.com | tel: 206.859.2869 | fax: 877.733.3469
Redfin Corporation
710 2nd Ave
Suite 600
Seattle, WA 98104
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