Re: Minor FAQ correction suggestions

Very nice.  I applied the entire patch;  it was all good.  I made a few
updates after applying your patch; patch attached.

---------------------------------------------------------------------------

Ian Barwick wrote:
>
> I'm reworking the German version of the FAQ (which is
> hopelessly outdated), in the course of which I've come across
> a few errors in the original (English) version,
> mainly minor things like spelling mistakes and broken links.
> Patch with suggested corrections attached (German version will
> follow ASAP).
>
> General alterations:
>
> Some links corrected; links to the domain "postgresql.org" now uniformly
> written as "PostgreSQL.org". Minor tidying up of formatting.
>
> Some specific notes / questions on the following sections:
>
> 1.4) What non-Unix ports are available?
>
> -> win31.mak should be win32.mak
>
> Added:
>   "A native port to some Microsoft platforms is currently being worked
>    upon."
> -> IIRC this is the case. Please correct if not.
>
> 1.8) What documentation is available?
> The link http://www.PostgreSQL.org/books/ is broken,
> http://www.ca.PostgreSQL.org/books/ works. (It would be more
> logical to fix the link rather than the FAQ I think, though).
>
> 3.9) What are the pg_sorttempNNN.NN files in my database directory?
>
> -> presume this should read "What are the pg_tempNNN.NN files..." ??
>
>  4.4) How do you remove a column from a table?
> -> ALTER TABLE DROP COLUMN supported as of 7.3 :-)
>
> 4.15.2) How do I get the value of a SERIAL insert?
>
> -> Perl is a very versatile language, but this:
>
>     new_id = output of "SELECT nextval('person_id_seq')"
>     INSERT INTO person (id, name) VALUES (new_id, 'Blaise Pascal');
>
> is most definitely not Perl ;-). I have made up a pseudo-language for the
> example.
>
> 4.16) What is an OID? What is a TID?
> ->  backend/access/transam.h should be include/access/transam.h
>
> 4.17) What is the meaning of some of the terms used in PostgreSQL?
>
> -> The link http://www.comptechnews.com/~reaster/dbdesign.html is broken
> (the domain doesn't seem to exist). Suggest:
> http://hea-www.harvard.edu/MST/simul/software/docs/pkgs/pgsql/glossary/glossary.html
> as replacement.
>
> 4.25) How do I return multiple rows or columns from a function?
>
> -> Linked to current rather than developer documentation
>
>
> Regards
>
> Ian Barwick
> barwick@gmx.net

[ Attachment, skipping... ]

>
> ---------------------------(end of broadcast)---------------------------
> TIP 5: Have you checked our extensive FAQ?
>
> http://www.postgresql.org/users-lounge/docs/faq.html

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073
Index: doc/src/FAQ/FAQ.html
===================================================================
RCS file: /cvsroot/pgsql-server/doc/src/FAQ/FAQ.html,v
retrieving revision 1.159
diff -c -c -r1.159 FAQ.html
*** doc/src/FAQ/FAQ.html    14 Oct 2002 02:50:28 -0000    1.159
--- doc/src/FAQ/FAQ.html    14 Oct 2002 03:13:27 -0000
***************
*** 78,85 ****
       <A href="#3.7">3.7</A>) What debugging features are available?<BR>
       <A href="#3.8">3.8</A>) Why do I get <I>"Sorry, too many
      clients"</I> when trying to connect?<BR>
!      <A href="#3.9">3.9</A>) What are the <I>pg_sorttempNNN.NN</I>
!     files in my database directory?<BR>
       <A href="#3.10">3.10</A>) Why do I need to do a dump and restore
      to upgrade PostgreSQL releases?<BR>

--- 78,85 ----
       <A href="#3.7">3.7</A>) What debugging features are available?<BR>
       <A href="#3.8">3.8</A>) Why do I get <I>"Sorry, too many
      clients"</I> when trying to connect?<BR>
!      <A href="#3.9">3.9</A>) What is in the  <I>pgsql_tmp</I>
!     directory?<BR>
       <A href="#3.10">3.10</A>) Why do I need to do a dump and restore
      to upgrade PostgreSQL releases?<BR>

***************
*** 250,259 ****
      <P>The database server can run on Windows NT and Win2k using
      Cygwin, the Cygnus Unix/NT porting library. See
      <I>pgsql/doc/FAQ_MSWIN</I> in the distribution or the MS Windows FAQ
!     at <A href="http://www.PostgreSQL.org/docs/faq-mswin.html">http://www.PostgreSQL.org/docs/faq-mswin.html</A>.</P>

!     <p>A native port to some Microsoft platforms is currently being worked
!     upon.</p>

      <H4><A name="1.5">1.5</A>) Where can I get PostgreSQL?</H4>

--- 250,260 ----
      <P>The database server can run on Windows NT and Win2k using
      Cygwin, the Cygnus Unix/NT porting library. See
      <I>pgsql/doc/FAQ_MSWIN</I> in the distribution or the MS Windows FAQ
!     at <A href="http://www.PostgreSQL.org/docs/faq-mswin.html">
!     http://www.PostgreSQL.org/docs/faq-mswin.html</A>.</P>

!     <p>A native port to MS Win NT/2000/XP is currently being worked
!     on.</p>

      <H4><A name="1.5">1.5</A>) Where can I get PostgreSQL?</H4>

***************
*** 484,490 ****
      PostgreSQL?</H4>

      <P>PostgreSQL has had a first-class infrastructure since we started
!     in 1994. This is all thanks to Marc Fournier, who has created
      and managed this infrastructure over the years.</P>

      <P>Quality infrastructure is very important to an open-source
--- 485,491 ----
      PostgreSQL?</H4>

      <P>PostgreSQL has had a first-class infrastructure since we started
!     in 1996. This is all thanks to Marc Fournier, who has created
      and managed this infrastructure over the years.</P>

      <P>Quality infrastructure is very important to an open-source
***************
*** 545,553 ****
      interface? A report generator? An embedded query language
      interface?</H4>

!     <P>We have a nice graphical user interface called PgAccess, which is
!     shipped as part of the distribution. PgAccess also has a report
!     generator. The Web page is <A href="http://www.pgaccess.org/">http://www.pgaccess.org/</A>.</P>

      <P>We also include <I>ecpg</I>, which is an embedded SQL query
      language interface for C.</P>
--- 546,554 ----
      interface? A report generator? An embedded query language
      interface?</H4>

!     <P>We have a nice graphical user interface called PgAccess which can
!     also be used as a report generator. The Web page is
!     <A href="http://www.pgaccess.org/">http://www.pgaccess.org/</A>.</P>

      <P>We also include <I>ecpg</I>, which is an embedded SQL query
      language interface for C.</P>
***************
*** 565,571 ****

        <LI>Java (jdbc)</LI>

!       <LI>Perl (DBD::Pg)</LI>

        <LI>ODBC (odbc)</LI>

--- 566,572 ----

        <LI>Java (jdbc)</LI>

!       <LI>Perl (DBD::Pg and perl5)</LI>

        <LI>ODBC (odbc)</LI>

***************
*** 578,584 ****
        <LI>PHP ('pg_' functions, Pear::DB)</LI>
      </UL>
      <P>Additional interfaces are available at
!     <a href="http://www.PostgreSQL.org/interfaces.html">http://www.PostgreSQL.org/interfaces.html</A>.
      </P>
      <HR>

--- 579,587 ----
        <LI>PHP ('pg_' functions, Pear::DB)</LI>
      </UL>
      <P>Additional interfaces are available at
!     <a href="http://www.PostgreSQL.org/interfaces.html">http://www.PostgreSQL.org/interfaces.html</A>
!     and
!     <a href="http://gborg.PostgreSQL.org">http://gborg.PostgreSQL.org</A>.
      </P>
      <HR>

***************
*** 765,772 ****
      the MaxBackendId constant in
      <I>include/storage/sinvaladt.h</I>.</P>

!     <H4><A name="3.9">3.9</A>) What are the <I>pg_tempNNN.NN</I>
!     files in my database directory?</H4>

      <P>They are temporary files generated by the query executor. For
      example, if a sort needs to be done to satisfy an <SMALL>ORDER
--- 768,775 ----
      the MaxBackendId constant in
      <I>include/storage/sinvaladt.h</I>.</P>

!     <H4><A name="3.9">3.9</A>) What are the <I>pgsql_tmp</I>
!     directory?</H4>

      <P>They are temporary files generated by the query executor. For
      example, if a sort needs to be done to satisfy an <SMALL>ORDER
***************
*** 774,783 ****
      <I>-S</I> parameter allows, then temporary files are created to
      hold the extra data.</P>

!     <P>The temporary files should be deleted automatically, but might
!     not if a backend crashes during a sort. If you have no backends
!     running at the time, it is safe to delete the pg_tempNNN.NN
!     files.</P>

      <H4><A name="3.10">3.10</A>) Why do I need to do a dump and restore
      to upgrade between major PostgreSQL releases?</H4>
--- 777,785 ----
      <I>-S</I> parameter allows, then temporary files are created to
      hold the extra data.</P>

!     <P>The temporary files are usually deleted automatically, but might
!     remain if a backend crashes during a sort. A stop and restart of the
!     <I>postmaster</I> will remove files from those directories.</P>

      <H4><A name="3.10">3.10</A>) Why do I need to do a dump and restore
      to upgrade between major PostgreSQL releases?</H4>
***************
*** 790,799 ****
      data in a generic format that can then be loaded in using the new internal
      format.</P>

!     <p>In releases where the on-disk format does not change, the
!     <i>pg_upgrade</i> script can be used to upgrade without a dump/restore.
!     The release notes mention whether <i>pg_upgrade</i> is available for the
!     release.</p>

      <HR>

--- 792,801 ----
      data in a generic format that can then be loaded in using the new internal
      format.</P>

!     <P>In releases where the on-disk format does not change, the
!     <I>pg_upgrade</I> script can be used to upgrade without a dump/restore.
!     The release notes mention whether <I>pg_upgrade</I> is available for the
!     release.</P>

      <HR>

***************
*** 831,838 ****
      <H4><A name="4.4">4.4</A>) How do you remove a column from a
      table?</H4>

!     <P>Prior to version 7.3, <SMALL>ALTER TABLE DROP COLUMN</SMALL> is not supported.
!     You can do this instead:</P>
  <PRE>
      BEGIN;
      LOCK TABLE old_table;
--- 833,841 ----
      <H4><A name="4.4">4.4</A>) How do you remove a column from a
      table?</H4>

!     <P>This functionality was added in release 7.3 with
!     <SMALL>ALTER TABLE DROP COLUMN</SMALL>.  In earlier versions,
!     you can do this:</P>
  <PRE>
      BEGIN;
      LOCK TABLE old_table;
***************
*** 1023,1035 ****
  <PRE>
      SELECT *
      FROM tab
!     WHERE LOWER(col) = 'abc';
  </PRE>

      This will not use an standard index. However, if you create a
      functional index, it will be used:
  <PRE>
!     CREATE INDEX tabindex ON tab (LOWER(col));
  </PRE>

      <H4><A name="4.13">4.13</A>) In a query, how do I detect if a field
--- 1026,1038 ----
  <PRE>
      SELECT *
      FROM tab
!     WHERE lower(col) = 'abc';
  </PRE>

      This will not use an standard index. However, if you create a
      functional index, it will be used:
  <PRE>
!     CREATE INDEX tabindex ON tab (lower(col));
  </PRE>

      <H4><A name="4.13">4.13</A>) In a query, how do I detect if a field
***************
*** 1118,1124 ****
      and your <SMALL>SERIAL</SMALL> column, respectively.

      <P>Alternatively, you could retrieve the assigned
!     <SMALL>SERIAL</SMALL> value with the <I>currval</I>() function
      <I>after</I> it was inserted by default, e.g.,</P>
  <PRE>
      execute("INSERT INTO person (name) VALUES ('Blaise Pascal')");
--- 1121,1127 ----
      and your <SMALL>SERIAL</SMALL> column, respectively.

      <P>Alternatively, you could retrieve the assigned
!     <SMALL>SERIAL</SMALL> value with the <I>currval()</I> function
      <I>after</I> it was inserted by default, e.g.,</P>
  <PRE>
      execute("INSERT INTO person (name) VALUES ('Blaise Pascal')");
***************
*** 1135,1141 ****
      <H4><A name="4.15.3">4.15.3</A>) Don't <I>currval()</I> and
      <I>nextval()</I> lead to a race condition with other users?</H4>

!     <P>No. <i>currval</i>() returns the current value assigned by your
      backend, not by all users.</P>

      <H4><A name="4.15.4">4.15.4</A>) Why aren't my sequence numbers
--- 1138,1144 ----
      <H4><A name="4.15.3">4.15.3</A>) Don't <I>currval()</I> and
      <I>nextval()</I> lead to a race condition with other users?</H4>

!     <P>No. <I>currval()</I> returns the current value assigned by your
      backend, not by all users.</P>

      <H4><A name="4.15.4">4.15.4</A>) Why aren't my sequence numbers