public inbox for [email protected]  

help / color / mirror / Atom feed

From: David Fetter <[email protected]>
To: Shahaf Abileah <[email protected]>
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Subject: Re: [DOCS] Documenting a DB schema
Date: Wed, 5 Mar 2008 07:05:27 -0800
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>

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 <[email protected]> http://fetter.org/
Phone: +1 415 235 3778  AIM: dfetter666  Yahoo!: dfetter
Skype: davidfetter      XMPP: [email protected]

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate

view thread (11+ messages)

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected], [email protected], [email protected], [email protected]
  Subject: Re: [DOCS] Documenting a DB schema
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox