Re: Suggestions for Postgres FAQ - Mailing list pgsql-docs

Thanks.  I made almost every change you recommended.  The original is in
HTML, and can be found on the web site.  The FAQ that is displayed there
is actually the original.  The one in the distribution is a text file
that makes it easier for users.

You can see your improved version on the web site right now.  Go to
www.postgresql.org/index.html.  You need the index.html so you don't see
on of the mirrors, which does not get updated until tonight.


> Bruce,
> 
> I'm a satisfied Postgres user.  I thought I would try contributing back
> to the Postgres effort by working on the documentation.
> 
> I have some suggested changes to the FAQ for you, which I've attached as
> a context diff.
> 
> Let me know if this is useful, or if there's something else you'd rather
> I work on.
> 
> Thanks,
> Fred Horch

> *** FAQ    Tue Jun 15 13:09:54 1999
> --- FAQ.new    Tue Jun 15 13:09:10 1999
> ***************
> *** 24,42 ****
>      1.2) What does PostgreSQL run on?
>      1.3) Where can I get PostgreSQL?
>      1.4) What's the copyright on PostgreSQL?
> !    1.5) Support for PostgreSQL
> !    1.6) Latest release of PostgreSQL
>      1.7) Is there a commercial version of PostgreSQL?
>      1.8) What documentation is available for PostgreSQL?
> !    1.9) What version of SQL does PostgreSQL use?
>      1.10) Does PostgreSQL work with databases from earlier versions of
>      PostgreSQL?
>      1.11) Are there ODBC drivers for PostgreSQL?
>      1.12) What tools are available for hooking PostgreSQL to Web pages?
>      1.13) Does PostgreSQL have a graphical user interface? A report
> !    generator? A embedded query language interface?
>      1.14) How can I learn SQL?
>      1.15) What languages are available to communicate with PostgreSQL?
>      
>                       Installation/Configuration questions
>                                         
> --- 24,44 ----
>      1.2) What does PostgreSQL run on?
>      1.3) Where can I get PostgreSQL?
>      1.4) What's the copyright on PostgreSQL?
> !    1.5) Where can I get support for PostgreSQL?
> !    1.6) What is the latest release of PostgreSQL?
>      1.7) Is there a commercial version of PostgreSQL?
>      1.8) What documentation is available for PostgreSQL?
> !    1.9) What version of SQL does PostgreSQL support?
>      1.10) Does PostgreSQL work with databases from earlier versions of
>      PostgreSQL?
>      1.11) Are there ODBC drivers for PostgreSQL?
>      1.12) What tools are available for hooking PostgreSQL to Web pages?
>      1.13) Does PostgreSQL have a graphical user interface? A report
> !    generator? An embedded query language interface?
>      1.14) How can I learn SQL?
>      1.15) What languages are available to communicate with PostgreSQL?
> +    1.16) Is PostgreSQL Y2K compliant?
> +    1.17) How do I join the development team?
>      
>                       Installation/Configuration questions
>                                         
> ***************
> *** 56,67 ****
>      2.8) How do I prevent other hosts from accessing my PostgreSQL
>      database?
>      2.9) I can't access the database as the root user.
> !    2.10) All my servers crash under concurrent table access. Why?
>      2.11) How do I tune the database engine for better performance?
>      2.12) What debugging features are available in PostgreSQL?
>      2.13) When I try to start the postmaster, I get IpcSemaphoreCreate
> !    errors. Why?
> !    2.14) I get 'Sorry, too many clients' when trying to connect. Why?
>      2.15) What non-unix ports are available?
>      
>                              Operational questions
> --- 58,69 ----
>      2.8) How do I prevent other hosts from accessing my PostgreSQL
>      database?
>      2.9) I can't access the database as the root user.
> !    2.10) All my servers crash under concurrent table access.
>      2.11) How do I tune the database engine for better performance?
>      2.12) What debugging features are available in PostgreSQL?
>      2.13) When I try to start the postmaster, I get IpcSemaphoreCreate
> !    errors.
> !    2.14) I get 'Sorry, too many clients' when trying to connect.
>      2.15) What non-unix ports are available?
>      
>                              Operational questions
> ***************
> *** 73,79 ****
>      cursors?
>      3.5) What is an R-tree index and what is it used for?
>      3.6) What is the maximum size for a row, table, database?
> !    3.7) My queries are slow or don't make use of the indexes. Why?
>      3.8) How do I do regular expression searches? case-insensitive regexp
>      searching?
>      3.9) I experienced a server crash during a vacuum. How do I remove the
> --- 75,81 ----
>      cursors?
>      3.5) What is an R-tree index and what is it used for?
>      3.6) What is the maximum size for a row, table, database?
> !    3.7) My queries are slow or don't make use of the indexes.
>      3.8) How do I do regular expression searches? case-insensitive regexp
>      searching?
>      3.9) I experienced a server crash during a vacuum. How do I remove the
> ***************
> *** 200,206 ****
>      CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT,
>      UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
>      
> !   1.5) Support for PostgreSQL
>     
>      There is no official support for PostgreSQL from the University of
>      California, Berkeley. It is maintained through volunteer effort.
> --- 202,208 ----
>      CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT,
>      UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
>      
> !   1.5) Where can I get support for PostgreSQL?
>     
>      There is no official support for PostgreSQL from the University of
>      California, Berkeley. It is maintained through volunteer effort.
> ***************
> *** 247,258 ****
>      There is also an IRC channel on EFNet, channel #PostgreSQL. I use the
>      unix command irc -c '#PostgreSQL' "$USER" irc.phoenix.net
>      
> !    Commerical support for PostgreSQL is available at
>      http://www.pgsql.com/
>      
> !   1.6) Latest release of PostgreSQL
>     
> !    The latest release of PostgreSQL is version 6.5.
>      
>      We plan to have major releases every four months.
>      
> --- 249,260 ----
>      There is also an IRC channel on EFNet, channel #PostgreSQL. I use the
>      unix command irc -c '#PostgreSQL' "$USER" irc.phoenix.net
>      
> !    Commercial support for PostgreSQL is available at
>      http://www.pgsql.com/
>      
> !   1.6) What is the latest release of PostgreSQL?
>     
> !    As of June 1999, the latest release of PostgreSQL is version 6.5.
>      
>      We plan to have major releases every four months.
>      
> ***************
> *** 273,284 ****
>      
>      The web page contains even more documentation.
>      
> !   1.9) What version of SQL does PostgreSQL use?
>     
>      PostgreSQL supports an extended subset of SQL-92.
>      
> -    It is Y2K compliant.
> -    
>     1.10) Does PostgreSQL work with databases from earlier versions of
>     PostgreSQL?
>     
> --- 275,284 ----
>      
>      The web page contains even more documentation.
>      
> !   1.9) What version of SQL does PostgreSQL support?
>     
>      PostgreSQL supports an extended subset of SQL-92.
>      
>     1.10) Does PostgreSQL work with databases from earlier versions of
>     PostgreSQL?
>     
> ***************
> *** 319,325 ****
>      An WWW gateway based on WDB using perl can be downloaded from
>      http://www.eol.ists.ca/~dunlop/wdb-p95
>      
> !   1.13) Does PostgreSQL have a graphical user interface? A report generator? A
>     embedded query language interface?
>     
>      We have a nice graphical user interface called pgaccess, which is
> --- 319,325 ----
>      An WWW gateway based on WDB using perl can be downloaded from
>      http://www.eol.ists.ca/~dunlop/wdb-p95
>      
> !   1.13) Does PostgreSQL have a graphical user interface? A report generator? An
>     embedded query language interface?
>
>      We have a nice graphical user interface called pgaccess, which is
> ***************
> *** 335,341 ****
>      at
>      http://ourworld.compuserve.com/homepages/Graeme_Birchall/DB2_COOK.HTM.
>      
> !    Many of our users like The Practical SQL Handbook, Bowman et al,
>      Addison Wesley.
>      
>     1.15) What languages are available to communicate with PostgreSQL?
> --- 335,341 ----
>      at
>      http://ourworld.compuserve.com/homepages/Graeme_Birchall/DB2_COOK.HTM.
>      
> !    Many of our users like The Practical SQL Handbook, Bowman et al.,
>      Addison Wesley.
>      
>     1.15) What languages are available to communicate with PostgreSQL?
> ***************
> *** 350,355 ****
> --- 350,371 ----
>        * Python(interfaces/python)
>        * TCL(interfaces/libpgtcl)
>        * A crude C/4GL(contrib/pginterface)
> + 
> +   1.16) Is PostgreSQL Y2K compliant?
> + 
> +    Yes, version 6.5 correctly handles dates past the year 2000.
> + 
> +   1.17) How do I join the development team?
> + 
> +    First, download the latest sources and read the PostgreSQL Programmer's Guide.
> +    Second, subscribe to the pgsql-hackers and pgsql-patches mailing lists.
> +    Third, submit high-quality patches to pgsql-patches.
> + 
> +    There are about a dozen people who have "committer" privileges to
> +    the PostgreSQL CVS archive. All of them have gotten that by submitting
> +    so many high-quality patches that it was a pain for the existing
> +    committers to keep up, and we had confidence that patches they
> +    committed were likely to Do The Right Thing.
>        _________________________________________________________________
>      
>   Section 2: Installation Questions
> ***************
> *** 398,404 ****
>      For most systems, with default numbers of buffers and processes, you
>      need a minimum of ~1MB.
>      
> !   2.7) I have changed a source file, but a recompile does not see the change?
>     
>      The Makefiles do not have the proper dependencies for include files.
>      You have to do a make clean and then another make.
> --- 414,420 ----
>      For most systems, with default numbers of buffers and processes, you
>      need a minimum of ~1MB.
>      
> !   2.7) I have changed a source file, but a recompile does not see the change.
>     
>      The Makefiles do not have the proper dependencies for include files.
>      You have to do a make clean and then another make.
> ***************
> *** 417,423 ****
>      because of the ability of any user to dynamically link object modules
>      into the database engine.
>      
> !   2.10) All my servers crash under concurrent table access. Why?
>     
>      This problem can be caused by a kernel that is not configured to
>      support semaphores.
> --- 433,439 ----
>      because of the ability of any user to dynamically link object modules
>      into the database engine.
>      
> !   2.10) All my servers crash under concurrent table access.
>     
>      This problem can be caused by a kernel that is not configured to
>      support semaphores.
> ***************
> *** 497,503 ****
>      in the current directory.
>      
>     2.13) When I try to start the postmaster, I get IpcSemaphoreCreate errors.
> -   Why?
>     
>      If the error message is IpcSemaphoreCreate: semget failed (No space
>      left on device) then your kernel is not configured with enough
> --- 513,518 ----
> ***************
> *** 510,516 ****
>      If the error message is something else, you might not have semaphore
>      support configured in your kernel at all.
>      
> !   2.14) I get 'Sorry, too many clients' when trying to connect. Why?
>     
>      You need to increase the postmaster's limit on how many concurrent
>      backend processes it can start.
> --- 525,531 ----
>      If the error message is something else, you might not have semaphore
>      support configured in your kernel at all.
>      
> !   2.14) I get 'Sorry, too many clients' when trying to connect.
>     
>      You need to increase the postmaster's limit on how many concurrent
>      backend processes it can start.
> ***************
> *** 560,567 ****
>   
>     3.1) Does PostgreSQL support nested subqueries?
>     
> !    Yes, fully supported, but only in the where clause, not in the target
> !    list.
>      
>     3.2) How can I write client applications for PostgreSQL?
>     
> --- 575,581 ----
>   
>     3.1) Does PostgreSQL support nested subqueries?
>     
> !    Yes, but only in the where clause, not in the target list.
>      
>     3.2) How can I write client applications for PostgreSQL?
>     
> ***************
> *** 629,635 ****
>      are tens of gigabytes, and probably some that are hundreds of
>      gigabytes.
>      
> !   3.7) My queries are slow or don't make use of the indexes. Why?
>     
>      PostgreSQL does not automatically maintain statistics. One has to make
>      an explicit vacuum call to update the statistics. After statistics are
> --- 643,649 ----
>      are tens of gigabytes, and probably some that are hundreds of
>      gigabytes.
>      
> !   3.7) My queries are slow or don't make use of the indexes.
>     
>      PostgreSQL does not automatically maintain statistics. One has to make
>      an explicit vacuum call to update the statistics. After statistics are
> ***************
> *** 799,831 ****
>      the first few rows. Consider a query that has an order by. There is no
>      way to return any rows until the entire query is evaluated and sorted.
>      
> !   3.22)How much database disk space is required to store data from a typical
>     flat file?
> !   
> !    Consider a file with 300,000 lines with two integers on each line. The
>      flat file is 2.4MB. The size of the PostgreSQL database file
> !    containing this data can be estimated:
> ! 40 bytes + each row header (approximate)
> !  8 bytes + two int fields @ 4 bytes each
> !  4 bytes + pointer on page to tuple
> ! -------- =
> ! 52 bytes per row
>   
> ! The data page size in PostgreSQL is 8192(8k) bytes, so:
>   
> ! 8192 bytes per page
> ! -------------------  =  157 rows per database page (rounded up)
> !  52 bytes per row
>   
> ! 300000 data rows
> ! -----------------  =   1911 database pages
> ! 157 rows per page
>   
> ! 1911 database pages * 8192 bytes per page  =  15,654,912 or 15.5MB
>   
>   
> ! Indexes do not contain as much overhead, but do contain the data that is
> ! being indexed, so they can be large also.
>   
>     3.23) How do I get a list of tables, or other things I can see in psql?
>     
> --- 813,848 ----
>      the first few rows. Consider a query that has an order by. There is no
>      way to return any rows until the entire query is evaluated and sorted.
>      
> !   3.22) How much database disk space is required to store data from a typical
>     flat file?
> ! 
> !    A Postgres database can require about six and a half times the disk space
> !    required to store the data in a flat file.
> ! 
> !    Consider a file of 300,000 lines with two integers on each line. The
>      flat file is 2.4MB. The size of the PostgreSQL database file
> !    containing this data can be estimated at 15.5 MB:
>   
> !     40 bytes: each row header (approximate)
> !    + 8 bytes: two int fields @ 4 bytes each
> !    + 4 bytes: pointer on page to tuple
> !    ----------------------------------------
> !     52 bytes per row
>   
> !    The data page size in PostgreSQL is 8192 bytes (8 KB), so:
>   
> !    8192 bytes per page
> !    -------------------   =  157 rows per database page (rounded up)
> !      52 bytes per row
>   
> !    300000 data rows
> !    --------------------  =  1911 database pages
> !       157 rows per page
>   
> +    1911 database pages * 8192 bytes per page  =  15,654,912 bytes (15.5MB)
>   
> !    Indexes do not contain as much overhead, but do contain the data that is
> !    being indexed, so they can be large also.
>   
>     3.23) How do I get a list of tables, or other things I can see in psql?
>     
> ***************
> *** 874,886 ****
>      
>     4.3) I've written some nifty new types and functions for PostgreSQL.
>     
> !    Please share them with other PostgreSQL users. Send your extensions to
> !    mailing list, and they will eventually end up in the contrib/
>      subdirectory.
>      
>     4.4) How do I write a C function to return a tuple?
>     
> !    This requires extreme wizardry so extreme that the authors have not
>      ever tried it, though in principle it can be done.
>        _________________________________________________________________
>      
> --- 891,903 ----
>      
>     4.3) I've written some nifty new types and functions for PostgreSQL.
>     
> !    Please share them with other PostgreSQL users. Send your extensions to the
> !    pgsql-hackers mailing list, and they will eventually end up in the contrib/
>      subdirectory.
>      
>     4.4) How do I write a C function to return a tuple?
>     
> !    This requires wizardry so extreme that the authors have not
>      ever tried it, though in principle it can be done.
>        _________________________________________________________________
>      


--  Bruce Momjian                        |  http://www.op.net/~candle maillist@candle.pha.pa.us            |  (610)
853-3000+  If your life is a hard drive,     |  830 Blythe Avenue +  Christ can be your backup.        |  Drexel Hill,
Pennsylvania19026