Обсуждение: Documenting a DB schema
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
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
Вложения
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.';
You mean like: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?
COMMENT ON mytable IS 'This is my table. Mine, mine, mine';
You can also comment columns, databases, functions, schemas, domains, etc.
Cheers,
Steve
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
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