public inbox for [email protected]
help / color / mirror / Atom feedDocumenting a DB schema
11+ messages / 11 participants
[nested] [flat]
* Documenting a DB schema
@ 2008-03-04 20:02 Shahaf Abileah <[email protected]>
2008-03-04 20:45 ` Re: [GENERAL] Documenting a DB schema Oisin Glynn <[email protected]>
2008-03-04 20:47 ` Re: Documenting a DB schema Emi Lu <[email protected]>
2008-03-04 20:54 ` Re: Documenting a DB schema Tomás Di Doménico <[email protected]>
2008-03-04 20:56 ` Re: Documenting a DB schema Michael Monnerie <[email protected]>
2008-03-04 21:00 ` Re: Documenting a DB schema Alan Hodgson <[email protected]>
2008-03-04 21:06 ` Re: Documenting a DB schema Colin Wetherbee <[email protected]>
2008-03-04 21:27 ` Re: [SQL] Documenting a DB schema Steve Crawford <[email protected]>
2008-03-05 13:10 ` Re: Documenting a DB schema =?ISO-8859-1?Q?Professor_Fl=E1vio_Brito?= <[email protected]>
2008-03-05 15:05 ` Re: [DOCS] Documenting a DB schema David Fetter <[email protected]>
0 siblings, 9 replies; 11+ messages in thread
From: Shahaf Abileah @ 2008-03-04 20:02 UTC (permalink / raw)
To: [email protected]; pgsql-docs; [email protected]; [email protected]; [email protected]
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 protected] | tel: 206.859.2869 | fax: 877.733.3469
Redfin Corporation
710 2nd Ave
Suite 600
Seattle, WA 98104
^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: [GENERAL] Documenting a DB schema
2008-03-04 20:02 Documenting a DB schema Shahaf Abileah <[email protected]>
@ 2008-03-04 20:45 ` Oisin Glynn <[email protected]>
8 siblings, 0 replies; 11+ messages in thread
From: Oisin Glynn @ 2008-03-04 20:45 UTC (permalink / raw)
To: Shahaf Abileah <[email protected]>; +Cc: [email protected]; [email protected]
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 *
>
> [email protected] | 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.';
^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Documenting a DB schema
2008-03-04 20:02 Documenting a DB schema Shahaf Abileah <[email protected]>
@ 2008-03-04 20:47 ` Emi Lu <[email protected]>
8 siblings, 0 replies; 11+ messages in thread
From: Emi Lu @ 2008-03-04 20:47 UTC (permalink / raw)
To: Shahaf Abileah <[email protected]>; +Cc: [email protected]
Hi,
> 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?
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
^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Documenting a DB schema
2008-03-04 20:02 Documenting a DB schema Shahaf Abileah <[email protected]>
@ 2008-03-04 20:54 ` Tomás Di Doménico <[email protected]>
8 siblings, 0 replies; 11+ messages in thread
From: Tomás Di Doménico @ 2008-03-04 20:54 UTC (permalink / raw)
To: Shahaf Abileah <[email protected]>; [email protected]
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 *
>
> [email protected] | tel: 206.859.2869 | fax: 877.733.3469
>
> Redfin Corporation
> 710 2nd Ave
> Suite 600
> Seattle, WA 98104
>
>
>
^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Documenting a DB schema
2008-03-04 20:02 Documenting a DB schema Shahaf Abileah <[email protected]>
@ 2008-03-04 20:56 ` Michael Monnerie <[email protected]>
2008-03-04 22:13 ` Re: Documenting a DB schema Mary Anderson <[email protected]>
8 siblings, 1 reply; 11+ messages in thread
From: Michael Monnerie @ 2008-03-04 20:56 UTC (permalink / raw)
To: [email protected]
On Dienstag, 4. März 2008 Shahaf Abileah wrote:
> 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?
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
when it's used, take your example:
> create table table_with_comments(a int comment 'this is
> column a...');
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
Attachments:
[application/pgp-signature] signature.asc (194B, 2-signature.asc)
download
^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Documenting a DB schema
2008-03-04 20:02 Documenting a DB schema Shahaf Abileah <[email protected]>
2008-03-04 20:56 ` Re: Documenting a DB schema Michael Monnerie <[email protected]>
@ 2008-03-04 22:13 ` Mary Anderson <[email protected]>
0 siblings, 0 replies; 11+ messages in thread
From: Mary Anderson @ 2008-03-04 22:13 UTC (permalink / raw)
To: Michael Monnerie <[email protected]>; +Cc: [email protected]
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
Michael Monnerie wrote:
> On Dienstag, 4. März 2008 Shahaf Abileah wrote:
>> 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?
>
> 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
> when it's used, take your example:
>> create table table_with_comments(a int comment 'this is
>> column a...');
> 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
^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Documenting a DB schema
2008-03-04 20:02 Documenting a DB schema Shahaf Abileah <[email protected]>
@ 2008-03-04 21:00 ` Alan Hodgson <[email protected]>
8 siblings, 0 replies; 11+ messages in thread
From: Alan Hodgson @ 2008-03-04 21:00 UTC (permalink / raw)
To: [email protected]
On Tuesday 04 March 2008, "Shahaf Abileah" <[email protected]> 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
^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Documenting a DB schema
2008-03-04 20:02 Documenting a DB schema Shahaf Abileah <[email protected]>
@ 2008-03-04 21:06 ` Colin Wetherbee <[email protected]>
8 siblings, 0 replies; 11+ messages in thread
From: Colin Wetherbee @ 2008-03-04 21:06 UTC (permalink / raw)
To: Shahaf Abileah <[email protected]>; +Cc: [email protected]
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
^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: [SQL] Documenting a DB schema
2008-03-04 20:02 Documenting a DB schema Shahaf Abileah <[email protected]>
@ 2008-03-04 21:27 ` Steve Crawford <[email protected]>
8 siblings, 0 replies; 11+ messages in thread
From: Steve Crawford @ 2008-03-04 21:27 UTC (permalink / raw)
To: Shahaf Abileah <[email protected]>; +Cc: [email protected]; pgsql-docs; [email protected]; [email protected]; [email protected]
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?
>
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
^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: Documenting a DB schema
2008-03-04 20:02 Documenting a DB schema Shahaf Abileah <[email protected]>
@ 2008-03-05 13:10 ` =?ISO-8859-1?Q?Professor_Fl=E1vio_Brito?= <[email protected]>
8 siblings, 0 replies; 11+ messages in thread
From: =?ISO-8859-1?Q?Professor_Fl=E1vio_Brito?= @ 2008-03-05 13:10 UTC (permalink / raw)
To: ; +Cc: [email protected]
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 protected]>:
>
> 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 *
>
> [email protected] | tel: 206.859.2869 | fax: 877.733.3469
>
> Redfin Corporation
> 710 2nd Ave
> Suite 600
> Seattle, WA 98104
>
>
>
^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: [DOCS] Documenting a DB schema
2008-03-04 20:02 Documenting a DB schema Shahaf Abileah <[email protected]>
@ 2008-03-05 15:05 ` David Fetter <[email protected]>
8 siblings, 0 replies; 11+ messages in thread
From: David Fetter @ 2008-03-05 15:05 UTC (permalink / raw)
To: Shahaf Abileah <[email protected]>; +Cc: [email protected]; pgsql-docs; [email protected]; [email protected]; [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
^ permalink raw reply [nested|flat] 11+ messages in thread
end of thread, other threads:[~2008-03-05 15:05 UTC | newest]
Thread overview: 11+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2008-03-04 20:02 Documenting a DB schema Shahaf Abileah <[email protected]>
2008-03-04 20:45 ` Oisin Glynn <[email protected]>
2008-03-04 20:47 ` Emi Lu <[email protected]>
2008-03-04 20:54 ` Tomás Di Doménico <[email protected]>
2008-03-04 20:56 ` Michael Monnerie <[email protected]>
2008-03-04 22:13 ` Mary Anderson <[email protected]>
2008-03-04 21:00 ` Alan Hodgson <[email protected]>
2008-03-04 21:06 ` Colin Wetherbee <[email protected]>
2008-03-04 21:27 ` Steve Crawford <[email protected]>
2008-03-05 13:10 ` =?ISO-8859-1?Q?Professor_Fl=E1vio_Brito?= <[email protected]>
2008-03-05 15:05 ` David Fetter <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox