Re: [GENERAL] When to use COMMENT vs --
On Wed, Dec 7, 2016 at 9:57 AM, Rich Shepardwrote: > I have used '-- ' to enter comments about tables or columns and am curious > about the value of storing comments in tables using the COMMENT key word. > When is the latter more appropriate than the former? Main advantage of COMMENT is that the comments are transferred to the database such that the comments will be made available to client tools (like psql) and external programs. For example, if you are generating database diagrams out of the database automatically (which is a good idea) with a good tool (I recommend SchemaSpy) the comments will become visible. Code style comments OTOH will decorate the file. This is good if you maintain your code as proper code, checking it into git and such, which is also a very good idea. Personally I tend to avoid COMMENT on aesthetics; I just dislike the COMMENT section to *after* the object being created in code. If I had a hypothetical "COMMENT ON NEXT OBJECT 'This is ...';" I would probably use COMMENT a lot more :-). merlin -- Sent via pgsql-general mailing list (pgsql-general@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-general
Re: [GENERAL] When to use COMMENT vs --
On Thu, 8 Dec 2016, Charles Clavadetscher wrote: IMHO the fact mentioned by Chris Travers that comments on objects included in the database can be used by tools to generate the documentation is probably the most important (besides their being persisted). Charles, Chris' contribution was the only one to answer my question. As a matter of fact we have integrated this feature to extract comments to generate the DB documentation in our internal MediaWiki based wiki. I'm not sure this is applicable to me. One project is for my business use, the other for clients who will see only the entire application. Thanks for explaining, Rich -- Sent via pgsql-general mailing list (pgsql-general@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-general
Re: [GENERAL] When to use COMMENT vs --
Hi Rich > -Original Message- > From: pgsql-general-ow...@postgresql.org > [mailto:pgsql-general-ow...@postgresql.org] On Behalf Of Chris Travers > Sent: Mittwoch, 7. Dezember 2016 17:12 > To: Postgres General <pgsql-general@postgresql.org> > Subject: Re: [GENERAL] When to use COMMENT vs -- > > On Dec 7, 2016 5:07 PM, "Karsten Hilbert" <karsten.hilb...@gmx.net > <mailto:karsten.hilb...@gmx.net> > wrote: > > > > On Wed, Dec 07, 2016 at 07:57:54AM -0800, Rich Shepard wrote: > > > > > I have used '-- ' to enter comments about tables or columns and am > > > curious about the value of storing comments in tables using the COMMENT > > > key word. > > > When is the latter more appropriate than the former? > > > > "--" only means "comment" to SQL code (such as in scripts). > > PostgreSQL itself simply ignores it. > > > > OTOH, using "comment on ... is ..." tells PostgreSQL to _store_ a > > comment on a database object for later retrieval. > > > > This also means that tools like pg_autodoc can include it as part of the > generated documentation. All of the relevant differences have been mentioned by previous posters. IMHO the fact mentioned by Chris Travers that comments on objects included in the database can be used by tools to generate the documentation is probably the most important (besides their being persisted). As a matter of fact we have integrated this feature to extract comments to generate the DB documentation in our internal MediaWiki based wiki. If you are interested in more details on that, including additional reasons why it is a good idea to use "comments on" instead of comments in the source code, you may have a look at this presentation: http://www.schmiedewerkstatt.ch/documents/04-publications/integrating_postgresql_documentation_in_3rd_party_applications_handout_pdfa.pdf Bye Charles > > Karsten > > -- > > GPG key ID E4071346 @ eu.pool.sks-keyservers.net > > <http://eu.pool.sks-keyservers.net> > > E167 67FD A291 2BEA 73BD 4537 78B9 A9F9 E407 1346 > > > > > > -- > > Sent via pgsql-general mailing list (pgsql-general@postgresql.org > > <mailto:pgsql-general@postgresql.org> ) To make changes to your > > subscription: > > http://www.postgresql.org/mailpref/pgsql-general > -- Sent via pgsql-general mailing list (pgsql-general@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-general
Re: [GENERAL] When to use COMMENT vs --
On Dec 7, 2016 5:07 PM, "Karsten Hilbert"wrote: > > On Wed, Dec 07, 2016 at 07:57:54AM -0800, Rich Shepard wrote: > > > I have used '-- ' to enter comments about tables or columns and am curious > > about the value of storing comments in tables using the COMMENT key word. > > When is the latter more appropriate than the former? > > "--" only means "comment" to SQL code (such as in scripts). > PostgreSQL itself simply ignores it. > > OTOH, using "comment on ... is ..." tells PostgreSQL to > _store_ a comment on a database object for later retrieval. > This also means that tools like pg_autodoc can include it as part of the generated documentation. > Karsten > -- > GPG key ID E4071346 @ eu.pool.sks-keyservers.net > E167 67FD A291 2BEA 73BD 4537 78B9 A9F9 E407 1346 > > > -- > Sent via pgsql-general mailing list (pgsql-general@postgresql.org) > To make changes to your subscription: > http://www.postgresql.org/mailpref/pgsql-general
Re: [GENERAL] When to use COMMENT vs --
On Wed, Dec 7, 2016 at 9:57 AM, Rich Shepardwrote: > I have used '-- ' to enter comments about tables or columns and am > curious > about the value of storing comments in tables using the COMMENT key word. > When is the latter more appropriate than the former? > > TIA, > > Rich -- is a comment which is like a language comment: it has _no_ effect on the program being compiled. Likewise -- is simply ignored. The value in a COMMENT is actually stored in the data base. For example: tsh009=# comment on schema racf is 'Snapshot of z/OS RACF database via IRRDBU00 output'; COMMENT tsh009=# \dn+ List of schemas Name | Owner | Access privileges |Description +--+--+ dasd | tsh009 | | junk | tsh009 | | public | postgres | postgres=UC/postgres+| standard public schema | | =UC/postgres | racf | tsh009 | | Snapshot of z/OS RACF database via IRRDBU00 output tape | tsh009 | | tmc| tsh009 | | (6 rows) -- Heisenberg may have been here. Unicode: http://xkcd.com/1726/ Maranatha! <>< John McKown
Re: [GENERAL] When to use COMMENT vs --
On Wed, Dec 07, 2016 at 07:57:54AM -0800, Rich Shepard wrote: > I have used '-- ' to enter comments about tables or columns and am curious > about the value of storing comments in tables using the COMMENT key word. > When is the latter more appropriate than the former? "--" only means "comment" to SQL code (such as in scripts). PostgreSQL itself simply ignores it. OTOH, using "comment on ... is ..." tells PostgreSQL to _store_ a comment on a database object for later retrieval. Karsten -- GPG key ID E4071346 @ eu.pool.sks-keyservers.net E167 67FD A291 2BEA 73BD 4537 78B9 A9F9 E407 1346 -- Sent via pgsql-general mailing list (pgsql-general@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-general
Re: [GENERAL] When to use COMMENT vs --
2016-12-07 16:57 GMT+01:00 Rich Shepard: > I have used '-- ' to enter comments about tables or columns and am > curious > about the value of storing comments in tables using the COMMENT key word. > When is the latter more appropriate than the former? > Description entered with COMMENT statements is persistently saved in database system catalogue - see table pg_description. You can get the comment for any database object. Comments like '--' or '/* ... */ are comments in source code, and they are just ignored in processing. Regards Pavel > > TIA, > > Rich > > > -- > Sent via pgsql-general mailing list (pgsql-general@postgresql.org) > To make changes to your subscription: > http://www.postgresql.org/mailpref/pgsql-general >
[GENERAL] When to use COMMENT vs --
I have used '-- ' to enter comments about tables or columns and am curious about the value of storing comments in tables using the COMMENT key word. When is the latter more appropriate than the former? TIA, Rich -- Sent via pgsql-general mailing list (pgsql-general@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-general