Skip site navigation (1) Skip section navigation (2)

Re: [DOCS] Documenting a DB schema

From: David Fetter <david(at)fetter(dot)org>
To: Shahaf Abileah <shahaf(at)redfin(dot)com>
Cc: pgsql-admin(at)postgresql(dot)org, pgsql-docs(at)postgresql(dot)org,pgsql-general(at)postgresql(dot)org, psql-novice(at)postgresql(dot)org,pgsql-sql(at)postgresql(dot)org
Subject: Re: [DOCS] Documenting a DB schema
Date: 2008-03-05 15:05:27
Message-ID: 20080305150527.GK19860@fetter.org (view raw or flat)
Thread:
Lists: pgsql-adminpgsql-docspgsql-generalpgsql-sql
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(at)fetter(dot)org> http://fetter.org/
Phone: +1 415 235 3778  AIM: dfetter666  Yahoo!: dfetter
Skype: davidfetter      XMPP: david(dot)fetter(at)gmail(dot)com

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

In response to

pgsql-docs by date

Next:From: Richard HuxtonDate: 2008-03-05 15:05:30
Subject: Re: FAQ on Embedding Postgres
Previous:From: Bruce MomjianDate: 2008-03-05 15:02:41
Subject: Re: FAQ on Embedding Postgres

pgsql-sql by date

Next:From: Jeff FrostDate: 2008-03-05 17:33:53
Subject: finding columns that have three or fewer distinct characters
Previous:From: Professor Flávio BritoDate: 2008-03-05 13:10:27
Subject: Re: Documenting a DB schema

pgsql-admin by date

Next:From: sathiya psqlDate: 2008-03-05 15:32:59
Subject: optimizating postgresql
Previous:From: Kevin GrittnerDate: 2008-03-05 14:31:46
Subject: Re: Postgres port bindings changed after box restart

pgsql-general by date

Next:From: sathiya psqlDate: 2008-03-05 15:32:11
Subject: indexing - creates problem
Previous:From: Reece HartDate: 2008-03-05 14:29:53
Subject: executing query results withing psql

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group