Received: from localhost (unknown [200.46.204.183])
	by postgresql.org (Postfix) with ESMTP id B76F72E036E;
	Wed,  5 Mar 2008 11:05:45 -0400 (AST)
Received: from postgresql.org ([200.46.204.71])
	by localhost (mx1.hub.org [200.46.204.183]) (amavisd-maia, port 10024)
	with ESMTP id 22370-03; Wed,  5 Mar 2008 11:05:30 -0400 (AST)
X-Greylist: from auto-whitelisted by SQLgrey-1.7.5
X-Greylist: from auto-whitelisted by SQLgrey-1.7.5
X-Greylist: from auto-whitelisted by SQLgrey-1.7.5
X-Greylist: from auto-whitelisted by SQLgrey-1.7.5
Received: from fetter.org (start.fetter.org [66.92.188.65])
	by postgresql.org (Postfix) with ESMTP id DC6412E027E;
	Wed,  5 Mar 2008 11:05:29 -0400 (AST)
Received: by fetter.org (Postfix, from userid 500)
	id 20F3BFBCDAA; Wed,  5 Mar 2008 07:05:27 -0800 (PST)
Date: Wed, 5 Mar 2008 07:05:27 -0800
From: David Fetter <david@fetter.org>
To: Shahaf Abileah <shahaf@redfin.com>
Cc: pgsql-admin@postgresql.org, pgsql-docs@postgresql.org,
	pgsql-general@postgresql.org, psql-novice@postgresql.org,
	pgsql-sql@postgresql.org
Subject: Re: [DOCS] Documenting a DB schema
Message-ID: <20080305150527.GK19860@fetter.org>
References: <082D8A131DF72A4D88C908A1AD3DEB22023B34F2@mail-1.rf.lan>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <082D8A131DF72A4D88C908A1AD3DEB22023B34F2@mail-1.rf.lan>
User-Agent: Mutt/1.5.17 (2007-11-01)
X-Virus-Scanned: Maia Mailguard 1.0.1
X-Archive-Number: 200803/41
X-Sequence-Number: 28524

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