Обсуждение: Documenting a DB schema

Поиск
Список
Период
Сортировка

Documenting a DB schema

От
"Shahaf Abileah"
Дата:

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?

 

Thanks,

 

--S

 

Shahaf Abileah | Lead Software Developer

shahaf@redfin.com | tel: 206.859.2869 | fax: 877.733.3469

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

 

Re: Documenting a DB schema

От
Oisin Glynn
Дата:
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?
>
> 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 *
>
> shahaf@redfin.com | tel: 206.859.2869 | fax: 877.733.3469
>
> Redfin Corporation
> 710 2nd Ave
> Suite 600
> Seattle, WA 98104
>
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.';

Re: Documenting a DB schema

От
Alan Hodgson
Дата:
On Tuesday 04 March 2008, "Shahaf Abileah" <shahaf@redfin.com> wrote:
>
> However, Postgres doesn't support the "comment" keyword.  Is there an
> alternative?

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


--
Alan

Re: Documenting a DB schema

От
Colin Wetherbee
Дата:
Shahaf Abileah wrote:
> 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:

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

Re: Documenting a DB schema

От
Tomás Di Doménico
Дата:
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
> 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 *
>
> shahaf@redfin.com | tel: 206.859.2869 | fax: 877.733.3469
>
> Redfin Corporation
> 710 2nd Ave
> Suite 600
> Seattle, WA 98104
>
>
>

Re: [SQL] Documenting a DB schema

От
Steve Crawford
Дата:
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

Re: [DOCS] Documenting a DB schema

От
David Fetter
Дата:
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