Subject: Documenting a DB schema

From: "Shahaf Abileah" <[email-masked]>
Date: Tue, 4 Mar 2008 12:02:27 -0800

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?

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 

[email-masked] | tel: 206.859.2869 | fax: 877.733.3469

Redfin Corporation
710 2nd Ave
Suite 600
Seattle, WA 98104

---

From: Oisin Glynn <[email-masked]>
Date: Tue, 04 Mar 2008 15:45:51 -0500

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?
>
> 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...');
>
> However, Postgres doesn’t support the “comment” keyword. Is there an 
> alternative?
>
> Thanks,
>
> --S
>
> *Shahaf Abileah *|* Lead Software Developer *
>
Its probably best to try one list and see if you get a response rather 
than sending the same message to 3 lists.
Comments are supported

CREATE TABLE follow_me_destination
(
mailbox_number character varying(10), -- Follow me users mailbox number.
destination_number character varying(32), -- Follow me phone number.
dest_id serial NOT NULL
)
WITHOUT OIDS;
ALTER TABLE follow_me_destination OWNER TO postgres;
COMMENT ON TABLE follow_me_destination IS 'Stores follow me numbers for 
system users.';
COMMENT ON COLUMN follow_me_destination.mailbox_number IS 'Follow me 
users mailbox number.';
COMMENT ON COLUMN follow_me_destination.destination_number IS 'Follow me 
phone number.';

---

From: Emi Lu <[email-masked]>
Date: Tue, 04 Mar 2008 15:47:13 -0500

Hi,

> tables and columns mean and what data to expect.  Any recommendations?

I am using Case Studio to document DB structures. I think it is pretty 
good tool.

http://www.casestudio.com/enu/default.aspx

To browse DB objects only, try DbVisualizer:
http://www.minq.se/products/dbvis/

- Ly

---

From: Tomás Di Doménico <[email-masked]>
Date: Tue, 04 Mar 2008 18:54:53 -0200

Check http://www.postgresql.org/docs/8.3/interactive/sql-comment.html

Cheers!

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
> code as possible – that way we stand a chance of keeping it up to date.

---

From: Michael Monnerie <[email-masked]>
Date: Tue, 4 Mar 2008 21:56:51 +0100

> However, Postgres doesn't support the "comment" keyword.  Is there an

This sounds nice at first thought... but: you need to document tables 
also, and relations between tables etc. And especially the complex 
dependencies can't be documented that way ("if you insert this here, 
look into table x and y and compare this with table z, blabla").

And I'd like to know how often such funny documentation can be found 
> create table table_with_comments(a int comment 'this is
I've seen such documentation a lot - just bought a Nokia E65 mobile 
phone, it's handbook has this kind of documentation printed in it... 
worthless.

But, BTW, does anybody have a good tool to show graphically the 
relations between tables, and maybe even draw relations between tables 
and create all necessary commands from this automatically? That would 
be nice, along with documentation features...

mfg zmi
-- 
// Michael Monnerie, Ing.BSc    -----      http://it-management.at
// Tel: 0676/846 914 666                      .network.your.ideas.
// PGP Key:         "curl -s http://zmi.at/zmi.asc | gpg --import"
// Fingerprint: AC19 F9D5 36ED CD8A EF38  500E CE14 91F7 1C12 09B4
// Keyserver: www.keyserver.net                   Key-ID: 1C1209B4

---

From: Alan Hodgson <[email-masked]>
Date: Tue, 4 Mar 2008 13:00:50 -0800

> However, Postgres doesn't support the "comment" keyword.  Is there an

comment on table table_name is 'comment';
comment on column table.column_name is 'comment';

-- 
Alan

---

From: Colin Wetherbee <[email-masked]>
Date: Tue, 04 Mar 2008 16:06:26 -0500

> the table definitions. It looks like MySQL has that kind of capability:

Please do not cross-post.  One list is enough.

PostgreSQL has that functionality, too.

cww=# CREATE TABLE foo (a INTEGER, b INTEGER);
CREATE TABLE
cww=# COMMENT ON TABLE foo IS 'my comment';
COMMENT
cww=# \d+
               List of relations
  Schema | Name | Type  | Owner | Description
--------+------+-------+-------+-------------
  public | foo  | table | cww   | my comment
(1 row)

COMMENT is well-documented.

http://www.postgresql.org/docs/8.3/static/sql-comment.html

Colin

---

From: Steve Crawford <[email-masked]>
Date: Tue, 04 Mar 2008 13:27:15 -0800

Shahaf Abileah wrote:
>
> I'm looking for a systematic way to document the schema for the 
> code as possible -- that way we stand a chance of keeping it up to 
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

---

From: Mary Anderson <[email-masked]>
Date: Tue, 04 Mar 2008 14:13:02 -0800

MicroOlap (or MicrOlap) does a nice job of creating schema diagrams for 
postgres.  I have had a little trouble with re-engineering databases 
that have had a lot of alterations, however.  But their tech support is 
reasonable.

Mary

---

From: "Professor Flávio Brito" <[email-masked]>
Date: Wed, 5 Mar 2008 10:10:27 -0300

Hi

You may try this.

CREATE TYPE tabela_estrutura AS
   (esquema text,
    tabela text,
    campo text,
    tipo text,
    valor text,
    autoincremento boolean);
ALTER TYPE tabela_estrutura OWNER TO postgres;

CREATE OR REPLACE FUNCTION dados_tabela(character varying)
  RETURNS SETOF tabela_estrutura AS
$BODY$
 DECLARE
 r tabela_estrutura%ROWTYPE;
 rec RECORD;
 vTabela alias for $1;
 eSql TEXT;

 BEGIN
 eSql := 'SELECT
       CAST(rel.nspname as TEXT), CAST(rel.relname AS TEXT) ,
CAST(attrs.attname AS TEXT), CAST("Type" AS TEXT),
CAST("Default" AS TEXT), attrs.attnotnull
        FROM
               (SELECT c.oid, n.nspname, c.relname
               FROM pg_catalog.pg_class c
               LEFT JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
               WHERE pg_catalog.pg_table_is_visible(c.oid) ) rel
        JOIN
               (SELECT a.attname, a.attrelid,
               pg_catalog.format_type(a.atttypid, a.atttypmod) as "Type",
                      (SELECT substring(d.adsrc for 128) FROM
pg_catalog.pg_attrdef d
                      WHERE d.adrelid = a.attrelid AND d.adnum = a.attnumAND
a.atthasdef)
               as "Default", a.attnotnull, a.attnum
               FROM pg_catalog.pg_attribute a
               WHERE a.attnum > 0 AND NOT a.attisdropped ) attrs
        ON (attrs.attrelid = rel.oid )
        WHERE relname LIKE ''%' || vTabela || '%''
        ORDER BY attrs.attnum';
FOR r IN EXECUTE eSql
 LOOP
 RETURN NEXT r;
END LOOP;
 IF NOT FOUND THEN
        RAISE EXCEPTION 'Table not found', vTabela;
 END IF;
 RETURN;
 END
 $BODY$
  LANGUAGE 'plpgsql' VOLATILE;
ALTER FUNCTION dados_tabela(character varying) OWNER TO postgres;

2008/3/4, Shahaf Abileah <[email-masked]>:
> 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:
>
>
>

---

From: David Fetter <[email-masked]>
Date: Wed, 5 Mar 2008 07:05:27 -0800

> 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

> code as possible - that way we stand a chance of keeping it up to

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.

> the table definitions.  It looks like MySQL has that kind of capability:

See above re: COMMENT ON :)

> However, Postgres doesn't support the "comment" keyword.

Actually, it does :)

> Is there an alternative?

Cheers,
David.
-- 
David Fetter <[email-masked]> http://fetter.org/
Phone: +1 415 235 3778  AIM: dfetter666  Yahoo!: dfetter
Skype: davidfetter      XMPP: [email-masked]

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