Received: from localhost (unknown [200.46.204.184]) by postgresql.org (Postfix) with ESMTP id 015C12E0199; Tue, 4 Mar 2008 17:27:28 -0400 (AST) Received: from postgresql.org ([200.46.204.71]) by localhost (mx1.hub.org [200.46.204.184]) (amavisd-maia, port 10024) with ESMTP id 96794-09; Tue, 4 Mar 2008 17:27:14 -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 polaris.pinpointresearch.com (66-7-238-130.static-ip.telepacific.net [66.7.238.130]) by postgresql.org (Postfix) with ESMTP id C6E452E0088; Tue, 4 Mar 2008 17:27:18 -0400 (AST) Received: from [192.168.1.179] (betelgeuse.pinpointresearch.com [192.168.1.179]) by polaris.pinpointresearch.com (Postfix) with ESMTP id 5ABA7E00EC8A; Tue, 4 Mar 2008 13:27:16 -0800 (PST) Message-ID: <47CDBEB3.3010106@pinpointresearch.com> Date: Tue, 04 Mar 2008 13:27:15 -0800 From: Steve Crawford User-Agent: Thunderbird 2.0.0.12 (X11/20080227) MIME-Version: 1.0 To: Shahaf Abileah CC: pgsql-admin@postgresql.org, pgsql-docs@postgresql.org, pgsql-general@postgresql.org, psql-novice@postgresql.org, pgsql-sql@postgresql.org Subject: Re: [SQL] Documenting a DB schema References: <082D8A131DF72A4D88C908A1AD3DEB22023B34F2@mail-1.rf.lan> In-Reply-To: <082D8A131DF72A4D88C908A1AD3DEB22023B34F2@mail-1.rf.lan> Content-Type: multipart/alternative; boundary="------------020004090401080306070400" X-Virus-Scanned: Maia Mailguard 1.0.1 X-Archive-Number: 200803/20 X-Sequence-Number: 28503 This is a multi-part message in MIME format. --------------020004090401080306070400 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit 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 --------------020004090401080306070400 Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit 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

--------------020004090401080306070400--