Thread: blatantly a bug in the documentation
I hope this is the right place to report a bug/issue in the official documentation... In http://www.postgresql.org/docs/current/interactive/plpgsql-control-structures.html there is an example for a function, cs_refresh_mviews(), chapter 38.6.4. Within this function there are a "PERFORM cs_log('Refreshing materialized views...');", but such a function cs_log() are not in the core distibution. I think, this is a problem for users which read the doc and try to reproduce the example or write own code based on the example. Regards, and many thanks for PostgreSQL to the developer, Andreas -- Andreas Kretschmer Kontakt: Heynitz: 035242/47150, D1: 0160/7141639 (mehr: -> Header) GnuPG-ID: 0x3FFF606C, privat 0x7F4584DA http://wwwkeys.de.pgp.net
On Mon, Nov 24, 2008 at 6:02 AM, A. Kretschmer <andreas.kretschmer@schollglas.com> wrote: > I hope this is the right place to report a bug/issue in the official > documentation... > > In > http://www.postgresql.org/docs/current/interactive/plpgsql-control-structures.html > there is an example for a function, cs_refresh_mviews(), chapter 38.6.4. > Within this function there are a "PERFORM cs_log('Refreshing > materialized views...');", but such a function cs_log() are not in the > core distibution. The example in the docs is pseudo-code. None of the tables referenced exist either...the purpose of the example was to demonstrate the syntax of for loops. merlin
am Mon, dem 24.11.2008, um 7:24:47 -0500 mailte Merlin Moncure folgendes: > On Mon, Nov 24, 2008 at 6:02 AM, A. Kretschmer > <andreas.kretschmer@schollglas.com> wrote: > > I hope this is the right place to report a bug/issue in the official > > documentation... > > > > In > > http://www.postgresql.org/docs/current/interactive/plpgsql-control-structures.html > > there is an example for a function, cs_refresh_mviews(), chapter 38.6.4. > > Within this function there are a "PERFORM cs_log('Refreshing > > materialized views...');", but such a function cs_log() are not in the > > core distibution. > > The example in the docs is pseudo-code. None of the tables referenced > exist either...the purpose of the example was to demonstrate the > syntax of for loops. Okay, it is an argument. On the other side, it was a question today in the irc-channel (#postgresql) today, someone asked, why his funktion don't work. I think, such examples should not contain such code. It is not apparent that this function are not available. Again, thx to all people behind PostgreSQL, it is a great thing and it has a really informatively documentation. My post was only a hint to make it better. Andreas -- Andreas Kretschmer Kontakt: Heynitz: 035242/47150, D1: 0160/7141639 (mehr: -> Header) GnuPG-ID: 0x3FFF606C, privat 0x7F4584DA http://wwwkeys.de.pgp.net
A. Kretschmer wrote: > Okay, it is an argument. On the other side, it was a question today in > the irc-channel (#postgresql) today, someone asked, why his funktion > don't work. I think, such examples should not contain such code. It is > not apparent that this function are not available. Perhaps the whole chapter could be improved if all the examples referred to a set of tables and functions previously defined in the introduction of the chapter. It would be good if the user could cut'n paste the code and try it out directly, instead of having to reverse engineer the tables/columns used for each example (and they're quite inconsistent). Also, some examples give the complete code including CREATE FUNCTION and others don't. Feel like submitting a patch? -- Alvaro Herrera http://www.CommandPrompt.com/ The PostgreSQL Company - Command Prompt, Inc.
On Mon, Nov 24, 2008 at 1:38 PM, Alvaro Herrera <alvherre@commandprompt.com> wrote: > A. Kretschmer wrote: > >> Okay, it is an argument. On the other side, it was a question today in >> the irc-channel (#postgresql) today, someone asked, why his funktion >> don't work. I think, such examples should not contain such code. It is >> not apparent that this function are not available. > > Perhaps the whole chapter could be improved if all the examples referred > to a set of tables and functions previously defined in the introduction > of the chapter. It would be good if the user could cut'n paste the code > and try it out directly, instead of having to reverse engineer the > tables/columns used for each example (and they're quite inconsistent). > Also, some examples give the complete code including CREATE FUNCTION and > others don't. It might also be useful to create such a database at initdb time so newbies have something interesting to look at right away. -- Dave Page EnterpriseDB UK: http://www.enterprisedb.com
Dave Page wrote: > On Mon, Nov 24, 2008 at 1:38 PM, Alvaro Herrera > <alvherre@commandprompt.com> wrote: > >> A. Kretschmer wrote: >> >> >>> Okay, it is an argument. On the other side, it was a question today in >>> the irc-channel (#postgresql) today, someone asked, why his funktion >>> don't work. I think, such examples should not contain such code. It is >>> not apparent that this function are not available. >>> >> Perhaps the whole chapter could be improved if all the examples referred >> to a set of tables and functions previously defined in the introduction >> of the chapter. It would be good if the user could cut'n paste the code >> and try it out directly, instead of having to reverse engineer the >> tables/columns used for each example (and they're quite inconsistent). >> Also, some examples give the complete code including CREATE FUNCTION and >> others don't. >> > > It might also be useful to create such a database at initdb time so > newbies have something interesting to look at right away. > No, there is no need to clutter every installation in the world with such a database. You could make it an addon module, or a pgfoundry project. cheers andrew
am Mon, dem 24.11.2008, um 13:47:54 +0000 mailte Dave Page folgendes: > On Mon, Nov 24, 2008 at 1:38 PM, Alvaro Herrera > <alvherre@commandprompt.com> wrote: > > A. Kretschmer wrote: > > > >> Okay, it is an argument. On the other side, it was a question today in > >> the irc-channel (#postgresql) today, someone asked, why his funktion > >> don't work. I think, such examples should not contain such code. It is > >> not apparent that this function are not available. > > > > Perhaps the whole chapter could be improved if all the examples referred > > to a set of tables and functions previously defined in the introduction > > of the chapter. It would be good if the user could cut'n paste the code > > and try it out directly, instead of having to reverse engineer the > > tables/columns used for each example (and they're quite inconsistent). > > Also, some examples give the complete code including CREATE FUNCTION and > > others don't. > > It might also be useful to create such a database at initdb time so > newbies have something interesting to look at right away. Nice idea. Andreas -- Andreas Kretschmer Kontakt: Heynitz: 035242/47150, D1: 0160/7141639 (mehr: -> Header) GnuPG-ID: 0x3FFF606C, privat 0x7F4584DA http://wwwkeys.de.pgp.net
On Mon, Nov 24, 2008 at 1:53 PM, Andrew Dunstan <andrew@dunslane.net> wrote: > >> It might also be useful to create such a database at initdb time so >> newbies have something interesting to look at right away. >> > > No, there is no need to clutter every installation in the world with such a > database. You could make it an addon module, or a pgfoundry project. > That would defeat the point. Not that I have any great feelings either way, but fwiw, Microsoft and Oracle both create a sample database iirc. -- Dave Page EnterpriseDB UK: http://www.enterprisedb.com
Dave Page wrote: > On Mon, Nov 24, 2008 at 1:53 PM, Andrew Dunstan <andrew@dunslane.net> wrote: >>> It might also be useful to create such a database at initdb time so >>> newbies have something interesting to look at right away. >>> >> No, there is no need to clutter every installation in the world with such a >> database. You could make it an addon module, or a pgfoundry project. >> > > That would defeat the point. Not that I have any great feelings either > way, but fwiw, Microsoft and Oracle both create a sample database > iirc. Last I checked, MS did it optionally only, no? //Magnus
Andrew Dunstan <andrew@dunslane.net> writes:
> Dave Page wrote:
>> It might also be useful to create such a database at initdb time so
>> newbies have something interesting to look at right away.
> No, there is no need to clutter every installation in the world with
> such a database. You could make it an addon module, or a pgfoundry project.
The whole thing strikes me as extreme overkill, not to mention a
misunderstanding of what an example is supposed to be for. If we're
going to insist that every example in the docs work when
copied-and-pasted into an empty database, then simple and to-the-point
examples will be history. Instead of one-liners we'll have clutter.
regards, tom lane
On Mon, Nov 24, 2008 at 2:02 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > Andrew Dunstan <andrew@dunslane.net> writes: >> Dave Page wrote: >>> It might also be useful to create such a database at initdb time so >>> newbies have something interesting to look at right away. > >> No, there is no need to clutter every installation in the world with >> such a database. You could make it an addon module, or a pgfoundry project. > > The whole thing strikes me as extreme overkill, not to mention a > misunderstanding of what an example is supposed to be for. If we're > going to insist that every example in the docs work when > copied-and-pasted into an empty database, then simple and to-the-point > examples will be history. Instead of one-liners we'll have clutter. That's the point of having a sample database ready to play with. The docs needn't have clutter, but the user can try out any of the examples without needing to setup anything first. It's a simple usability tweak that can help ease the learning curve for new users. -- Dave Page EnterpriseDB UK: http://www.enterprisedb.com
On Mon, Nov 24, 2008 at 2:01 PM, Magnus Hagander <magnus@hagander.net> wrote: > Dave Page wrote: >> That would defeat the point. Not that I have any great feelings either >> way, but fwiw, Microsoft and Oracle both create a sample database >> iirc. > > Last I checked, MS did it optionally only, no? Yes, but it defaults on iirc. We can emulate that behaviour in an installer (and do in Postgres Plus for example), but that doesn't help users of other distributions. -- Dave Page EnterpriseDB UK: http://www.enterprisedb.com
"Dave Page" <dpage@pgadmin.org> writes:
> On Mon, Nov 24, 2008 at 1:53 PM, Andrew Dunstan <andrew@dunslane.net> wrote:
>> No, there is no need to clutter every installation in the world with such a
>> database. You could make it an addon module, or a pgfoundry project.
> That would defeat the point.
By that logic, we should install the sample stuff in template1, to
ensure that the examples would "just work" wherever $newbie tries
to execute them :-(
regards, tom lane
On Mon, Nov 24, 2008 at 2:14 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > "Dave Page" <dpage@pgadmin.org> writes: >> On Mon, Nov 24, 2008 at 1:53 PM, Andrew Dunstan <andrew@dunslane.net> wrote: >>> No, there is no need to clutter every installation in the world with such a >>> database. You could make it an addon module, or a pgfoundry project. > >> That would defeat the point. > > By that logic, we should install the sample stuff in template1, to > ensure that the examples would "just work" wherever $newbie tries > to execute them :-( *sigh*. Or one of us could visit their office and show them what to do, but I think we know the difference between making something usable out of the box and going overboard. -- Dave Page EnterpriseDB UK: http://www.enterprisedb.com
am Mon, dem 24.11.2008, um 9:02:37 -0500 mailte Tom Lane folgendes: > Andrew Dunstan <andrew@dunslane.net> writes: > > Dave Page wrote: > >> It might also be useful to create such a database at initdb time so > >> newbies have something interesting to look at right away. > > > No, there is no need to clutter every installation in the world with > > such a database. You could make it an addon module, or a pgfoundry project. > > The whole thing strikes me as extreme overkill, not to mention a > misunderstanding of what an example is supposed to be for. If we're > going to insist that every example in the docs work when > copied-and-pasted into an empty database, then simple and to-the-point > examples will be history. Instead of one-liners we'll have clutter. For a beginner, a "relation 'foo' does not exist" is a clean message, but a "function foo() does not exist" from an example in the doc are a real problem. And, in this example in my first post, the call to the nonexistent function are neither necessary nor 'to-the-point' to explain a for-loop. The starting point for my post was a real question on IRC today. Someone was really confused because he tried to use this nonexistent funktion to log something into a log-file. I think, this example can rewritten, either without this funktion-call or with raise notice ... Regards, Andreas -- Andreas Kretschmer Kontakt: Heynitz: 035242/47150, D1: 0160/7141639 (mehr: -> Header) GnuPG-ID: 0x3FFF606C, privat 0x7F4584DA http://wwwkeys.de.pgp.net
On Mon, Nov 24, 2008 at 9:02 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > Andrew Dunstan <andrew@dunslane.net> writes: >> Dave Page wrote: >>> It might also be useful to create such a database at initdb time so >>> newbies have something interesting to look at right away. > >> No, there is no need to clutter every installation in the world with >> such a database. You could make it an addon module, or a pgfoundry project. > > The whole thing strikes me as extreme overkill, not to mention a > misunderstanding of what an example is supposed to be for. If we're > going to insist that every example in the docs work when > copied-and-pasted into an empty database, then simple and to-the-point > examples will be history. Instead of one-liners we'll have clutter. Clutter is the problem. The cs_log functions in the example do not serve any purpose that is helpful to describe a for loop. They serve no real purpose...why not 'raise notice' or just remove them? It should be clear to distinguish from real and non-real elements. merlin
> Clutter is the problem. The cs_log functions in the example do not > serve any purpose that is helpful to describe a for loop. They serve > no real purpose...why not 'raise notice' or just remove them? It > should be clear to distinguish from real and non-real elements. +1 for RAISE NOTICE. ...Robert
On Monday 24 November 2008 16:07:49 Dave Page wrote: > That's the point of having a sample database ready to play with. The > docs needn't have clutter, but the user can try out any of the > examples without needing to setup anything first. It's a simple > usability tweak that can help ease the learning curve for new users. I find that the regression test database usually works for that.
On Monday 24 November 2008 09:10:29 Dave Page wrote: > On Mon, Nov 24, 2008 at 2:01 PM, Magnus Hagander <magnus@hagander.net> wrote: > > Dave Page wrote: > >> That would defeat the point. Not that I have any great feelings either > >> way, but fwiw, Microsoft and Oracle both create a sample database > >> iirc. > > > > Last I checked, MS did it optionally only, no? > > Yes, but it defaults on iirc. We can emulate that behaviour in an > installer (and do in Postgres Plus for example), but that doesn't help > users of other distributions. > We actually have such a database on pgfoundry already (http://pgfoundry.org/frs/download.php/1719/pagila-0.10.1.zip), which i think devrim may have packaged into an rpm; it wouldn't hurt to add it to the win32 installer, but would you feel better if it were a contrib module or something? -- Robert Treat Conjecture: http://www.xzilla.net Consulting: http://www.omniti.com
On Tue, Nov 25, 2008 at 1:42 AM, Robert Treat <xzilla@users.sourceforge.net> wrote: > > We actually have such a database on pgfoundry already > (http://pgfoundry.org/frs/download.php/1719/pagila-0.10.1.zip), which i think > devrim may have packaged into an rpm; it wouldn't hurt to add it to the win32 > installer, but would you feel better if it were a contrib module or > something? I'm in favour of including it by default (at initdb), so it's there for new users to play with on any fresh install - however, there is only a point to that if all the documentation examples are based on that database to allow copy-paste-play. -- Dave Page EnterpriseDB UK: http://www.enterprisedb.com
Dave Page wrote: >On Tue, Nov 25, 2008 at 1:42 AM, Robert Treat ><xzilla@users.sourceforge.net> wrote: >> We actually have such a database on pgfoundry already >> (http://pgfoundry.org/frs/download.php/1719/pagila-0.10.1.zip), which i think >> devrim may have packaged into an rpm; it wouldn't hurt to add it to the win32 >> installer, but would you feel better if it were a contrib module or >> something? >I'm in favour of including it by default (at initdb), so it's there >for new users to play with on any fresh install - however, there is +1 It's reasonably easy to create a sample database during the initdb phase automatically. It's rather easy for an experienced DBA to "dropdb sampledb" to get rid of it, and it would be orders of magnitude more difficult for a novice to create the sample database from contrib or anywhere else. Besides the "waste" of space for the sample database should be negligible for almost any real production environment. >only a point to that if all the documentation examples are based on >that database to allow copy-paste-play. True. Though this is a chicken and egg problem, by simply creating the sample DB first, it creates the opportunity to gradually convert all examples in the manual to use the sample DB (and patch the sample DB in the process to be populated with the proper tables/functions to actually be useful in the required examples). -- Sincerely, Stephen R. van den Berg. "Give a man a fire and he's warm for a day,but set fire to him and he's warm for the rest of his life."
On Tue, Nov 25, 2008 at 7:31 PM, Dave Page <dpage@pgadmin.org> wrote: > I'm in favour of including it by default (at initdb), so it's there > for new users to play with on any fresh install ... Could we perhaps punt on the issue of whether to install the "sampledb" by default. It could be controlled by a flag to initdb, say $ initdb --sample data Whereas if you omit the flag, then initdb just does a vanilla install.Then we can leave it up to the distributions whetherthey want to install it by default, or give the user options in their package management systems to control this. In Apt it could be a debconf question, in Portage it could be a USE flag, etc. I think it's a pretty safe bet that the "newbies" we're talking about in this thread are going to be installing postgres via a package management system. If they are installing from source, they are already reading the documentation and will have to learn about running initdb on the command line anyway. Cheers, BJ
"Dave Page" <dpage@pgadmin.org> writes:
> I'm in favour of including it by default (at initdb), so it's there
> for new users to play with on any fresh install - however, there is
> only a point to that if all the documentation examples are based on
> that database to allow copy-paste-play.
You would also have to assume that all the examples are non-destructive,
and that no one ever extends an example in a destructive way. This
seems like a non-starter. Better to provide the sample database in a
form in which it can be easily dropped/reloaded. I'm envisioning that
there's a source file in $sharedir and we tell people
createdb examplepsql -f $sharedir/example.sql example
regards, tom lane
On Tue, Nov 25, 2008 at 1:23 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > "Dave Page" <dpage@pgadmin.org> writes: >> I'm in favour of including it by default (at initdb), so it's there >> for new users to play with on any fresh install - however, there is >> only a point to that if all the documentation examples are based on >> that database to allow copy-paste-play. > > You would also have to assume that all the examples are non-destructive, > and that no one ever extends an example in a destructive way. That's a good point. > This > seems like a non-starter. Better to provide the sample database in a > form in which it can be easily dropped/reloaded. I'm envisioning that > there's a source file in $sharedir and we tell people > > createdb example > psql -f $sharedir/example.sql example I was assuming that it would be in such a form anyway - similar to system_views.sql for example. I'd be happy with that setup - it's far better than referring people to pgFoundry, and should be simple for anyone to use. -- Dave Page EnterpriseDB UK: http://www.enterprisedb.com
On Tue, Nov 25, 2008 at 8:23 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote: > "Dave Page" <dpage@pgadmin.org> writes: >> I'm in favour of including it by default (at initdb), so it's there >> for new users to play with on any fresh install - however, there is >> only a point to that if all the documentation examples are based on >> that database to allow copy-paste-play. > > You would also have to assume that all the examples are non-destructive, > and that no one ever extends an example in a destructive way. This > seems like a non-starter. Better to provide the sample database in a > form in which it can be easily dropped/reloaded. I'm envisioning that > there's a source file in $sharedir and we tell people > > createdb example > psql -f $sharedir/example.sql example There's good precedent for that...SQL Server for example does something similar: http://msdn.microsoft.com/en-us/library/aa276825(SQL.80).aspx It's a good learning tool and would really raise the value of the documentation. merlin
Tom Lane wrote: > Better to provide the sample database in a > form in which it can be easily dropped/reloaded. I'm envisioning that > there's a source file in $sharedir and we tell people > > createdb example > psql -f $sharedir/example.sql example > > > This is a much better idea than doing it at initdb time, IMNSHO. cheers andrew
Stephen R. van den Berg wrote: > ... it would be orders of magnitude more difficult for > a novice to create the sample database from contrib or anywhere else. It seems to me that *this* is the more serious problem that we should fix instead. If, from the psql command prompt I could type: psql=# install module sampledb; Downloading sampledb from pgfoundry... Installing sampledb.... Connecting to sampledb.... sampledb=# it'd remove the need for pre-installing a rarely-needed ad-on, as well as being useful for other projects. For exmaple: psql=# install module US_Census_Tiger_Maps; Installing dependencyPostgis... Installing module US_Census_Tiger_Maps.... to install a GIS system with all the road networks.
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Hi, Le 25 nov. 08 à 20:29, Ron Mayer a écrit : > psql=# install module sampledb; > Downloading sampledb from pgfoundry... > Installing sampledb.... > Connecting to sampledb.... > sampledb=# This could be part of an installer for PostgreSQL extensions. See following email for a proposal on how to deal with extension packaging: http://archives.postgresql.org/pgsql-hackers/2008-07/msg01098.php The proposal purposefully let fetching and building steps out of the database manager itself, and makes it so that building is to be cared about by distributors. So it would be something like: create sampledb pg_pkg fetch pgsampledb and either pg_pkg install pgsampledb sampledb psql sampledb or psql sampledb sampledb=# install package pgsampledb; > it'd remove the need for pre-installing a rarely-needed ad-on, > as well as being useful for other projects. For exmaple: > psql=# install module US_Census_Tiger_Maps; > Installing dependency Postgis... > Installing module US_Census_Tiger_Maps.... > to install a GIS system with all the road networks. The dependancy system is yet to be though about, but definitely in the scope of the extension manager. While at it, calling all those things extensions rather than package would probably help not confusing people with Oracle compatibility etc. Last time I checked I didn't find mention of "package" into the standard, but still. So PosgtreSQL could have an extension manager at SQL level (create or replace extension, install extension, or maybe load extension (which would LOAD the modules associated), etc) with a system command line tool to fetch & build, etc (pg_ext ?) that source level users and packagers (distributors) would use? What do you dear readers think about the "extension" vocabulary? Regards, - -- dim -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (Darwin) iEYEARECAAYFAkksZooACgkQlBXRlnbh1bmyvgCaAobd8kWhtkO+DxmDjbnqAWCz 5pQAoMauBWbyuvYxg6bDndYpb9CYiYZc =Reeq -----END PGP SIGNATURE-----
Dimitri Fontaine <dfontaine@hi-media.com> writes:
> What do you dear readers think about the "extension" vocabulary?
+1 ... we should stay away from "package" unless we are going to
implement an Oracle-compatible facility. Which I don't particularly
wish to do, but we should leave it open for the future.
regards, tom lane
On Tue, 2008-11-25 at 08:23 -0500, Tom Lane wrote: > "Dave Page" <dpage@pgadmin.org> writes: > > I'm in favour of including it by default (at initdb), so it's there > > for new users to play with on any fresh install - however, there is > > only a point to that if all the documentation examples are based on > > that database to allow copy-paste-play. > > You would also have to assume that all the examples are non-destructive, > and that no one ever extends an example in a destructive way. This > seems like a non-starter. Better to provide the sample database in a > form in which it can be easily dropped/reloaded. I'm envisioning that > there's a source file in $sharedir and we tell people > > createdb example > psql -f $sharedir/example.sql example Sounds good. Please could we do this in a way that allows the example database to be localised. It will help beginners understand things better if we have table and column names in the local language. One more thing to translate maybe, but lets leave the door open for localisation. -- Simon Riggs www.2ndQuadrant.comPostgreSQL Training, Services and Support