Update FAQ's for release.

doc/FAQ

-
 Frequently Asked Questions (FAQ) for PostgreSQL
 
 Last updated: Sun Feb 1 16:13:28 EST 1998
 
 Current maintainer: Bruce Momjian (maillist@candle.pha.pa.us)
 
-   The most recent version of this document can be viewed at the
-   postgreSQL Web site, http://postgreSQL.org.
+The most recent version of this document can be viewed at the postgreSQL Web
+site, http://postgreSQL.org.
 
 Linux-specific questions are answered in
-   http://postgreSQL.org/docs/FAQ-linux.shtml.
+http://postgreSQL.org/docs/faq-linux.shtml.
 
 Irix-specific questions are answered in
-   http://postgreSQL.org/docs/FAQ-irix.shtml.
-     _________________________________________________________________
+http://postgreSQL.org/docs/faq-irix.shtml.
+
+  ------------------------------------------------------------------------
 
 Questions answered:
 
@@ -28,29 +28,24 @@ Questions answered:
 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
-   postgres?
+1.10) Does PostgreSQL work with databases from earlier versions of postgres?
 1.11) Are there ODBC drivers for PostgreSQL?
 1.12) What tools are available for hooking postgres to Web pages?
-   1.13) Does PostgreSQL have a graphical user interface? A report
-   generator? A embedded query language interface?
+1.13) Does PostgreSQL have a graphical user interface? A report generator? A
+embedded query language interface?
 1.14) What is a good book to learn SQL?
 
 2) Installation/Configuration questions
 
 2.1) initdb doesn't run
-   2.2) when I start up the postmaster, I get "FindBackend: could not
-   find a backend to execute..." "postmaster: could not find backend to
-   execute..."
-   2.3) The system seems to be confused about commas, decimal points, and
-   date formats.
-   2.4) How do I install PostgreSQL somewhere other than
-   /usr/local/pgsql?
-   2.5) When I run postmaster, I get a Bad System Call core dumped
-   message.
+2.2) when I start up the postmaster, I get "FindBackend: could not find a
+backend to execute..." "postmaster: could not find backend to execute..."
+2.3) The system seems to be confused about commas, decimal points, and date
+formats.
+2.4) How do I install PostgreSQL somewhere other than /usr/local/pgsql?
+2.5) When I run postmaster, I get a Bad System Call core dumped message.
 2.6) When I try to start the postmaster, I get IpcMemoryCreate errors.
-   2.7) I have changed a source file, but a recompile does not see the
-   change?
+2.7) I have changed a source file, but a recompile does not see the change?
 2.8) How do I prevent other hosts from accessing my PostgreSQL
 2.9) I can't access the database as the 'root' user.
 2.10) All my servers crash under concurrent table access. Why?
@@ -65,16 +60,14 @@ Questions answered:
 3.3) I can't seem to write into the middle of large objects reliably.
 3.4) How can I write client applications to PostgreSQL?
 3.5) How do I set up a pg_group?
-   3.6) What is the exact difference between binary cursors and normal
-   cursors?
+3.6) What is the exact difference between binary cursors and normal cursors?
 3.7) What is a R-tree index and what is it used for?
 3.8) What is the maximum size for a tuple?
-   3.9) I defined indices but my queries don't seem to make use of them.
-   Why?
+3.9) I defined indices but my queries don't seem to make use of them. Why?
 3.10) How do I do regular expression searches? case-insensitive regexp
 searching?
-   3.11) I experienced a server crash during a vacuum. How do I remove
-   the lock file?
+3.11) I experienced a server crash during a vacuum. How do I remove the lock
+file?
 3.12) What is the difference between the various character types?
 3.13) In a query, how do I detect if a field is NULL?
 3.14) How do I see how the query optimizer is evaluating my query?
@@ -90,55 +83,55 @@ Questions answered:
 3.23) How do you remove a column from a table?
 3.24) How do SELECT only the first few rows of a query?
 3.25) Why can't I create a column named "time"?
-   3.26) How much database disk space is required to store data from a
-   typical flat file?
+3.26) How much database disk space is required to store data from a typical
+flat file?
 
 4) Questions about extending PostgreSQL
 
-   4.1) I wrote a user-defined function and when I run it in psql, it
-   dumps core.
-   4.2) I get messages of the type NOTICE:PortalHeapMemoryFree:
-   0x402251d0
+4.1) I wrote a user-defined function and when I run it in psql, it dumps
+core.
+4.2) I get messages of the type NOTICE:PortalHeapMemoryFree: 0x402251d0
 4.3) I've written some nifty new types and functions for PostgreSQL.
 4.4) How do I write a C function to return a tuple?
 
 5) Bugs
 
 5.1) How do I make a bug report?
-     _________________________________________________________________
+
+  ------------------------------------------------------------------------
 
 Section 1: General Questions
 
 1.1) What is PostgreSQL?
 
-   PostgreSQL is an enhancement of the POSTGRES database management
-   system, a next-generation DBMS research prototype. While PostgreSQL
-   retains the powerful data model and rich data types of POSTGRES, it
-   replaces the PostQuel query language with an extended subset of SQL.
-   PostgreSQL is free and the complete source is available.
-   
-   PostgreSQL development is being performed by a team of Internet
-   developers who all subscribe to the PostgreSQL development mailing
-   list. The current coordinator is Marc G. Fournier
-   (scrappy@postgreSQL.org). (See below on how to join). This team is now
-   responsible for all current and future development of PostgreSQL.
-   
-   The authors of PostgreSQL 1.01 were Andrew Yu and Jolly Chen. Many
-   others have contributed to the porting, testing, debugging and
-   enhancement of the code. The original Postgres code, from which
-   PostgreSQL is derived, was the effort of many graduate students,
-   undergraduate students, and staff programmers working under the
-   direction of Professor Michael Stonebraker at the University of
-   California, Berkeley.
+PostgreSQL is an enhancement of the POSTGRES database management system, a
+next-generation DBMS research prototype. While PostgreSQL retains the
+powerful data model and rich data types of POSTGRES, it replaces the
+PostQuel query language with an extended subset of SQL. PostgreSQL is free
+and the complete source is available.
+
+PostgreSQL development is being performed by a team of Internet developers
+who all subscribe to the PostgreSQL development mailing list. The current
+coordinator is Marc G. Fournier (scrappy@postgreSQL.org). (See below on how
+to join). This team is now responsible for all current and future
+development of PostgreSQL.
+
+The authors of PostgreSQL 1.01 were Andrew Yu and Jolly Chen. Many others
+have contributed to the porting, testing, debugging and enhancement of the
+code. The original Postgres code, from which PostgreSQL is derived, was the
+effort of many graduate students, undergraduate students, and staff
+programmers working under the direction of Professor Michael Stonebraker at
+the University of California, Berkeley.
 
 The original name of the software at Berkeley was Postgres. When SQL
-   functionality was added in 1995, its name was changed to Postgres95.
-   The name was changed at the end of 1996 to PostgreSQL.
+functionality was added in 1995, its name was changed to Postgres95. The
+name was changed at the end of 1996 to PostgreSQL.
 
 1.2) What does PostgreSQL run on?
 
 The authors have compiled and tested PostgreSQL on the following
 platforms(some of these compiles require gcc 2.7.0):
+
    * aix - IBM on AIX 3.2.5 or 4.x
    * alpha - DEC Alpha AXP on Digital Unix 2.0, 3.2, 4.0
    * BSD44_derived - OSs derived from 4.4-lite BSD (NetBSD, FreeBSD)
@@ -147,8 +140,8 @@ Section 1: General Questions
    * hpux - HP PA-RISC on HP-UX 9.0, 10
    * i386_solaris - i386 Solaris
    * irix5 - SGI MIPS on IRIX 5.3
-     * linux - Intel x86 on Linux 2.0 and Linux ELF SPARC on Linux ELF
-       PPC on Linux Elf (For non-ELF Linux, see LINUX_ELF below).
+   * linux - Intel x86 on Linux 2.0 and Linux ELF SPARC on Linux ELF PPC on
+     Linux Elf (For non-ELF Linux, see LINUX_ELF below).
    * sco - SCO 3.2v5
    * sparc_solaris - SUN SPARC on Solaris 2.4, 2.5, 2.5.1
    * sunos4 - SUN SPARC on SunOS 4.1.3
@@ -156,14 +149,17 @@ Section 1: General Questions
    * ultrix4 - DEC MIPS on Ultrix 4.4
 
 The following platforms have known problems/bugs:
+
    * nextstep - Motorola MC68K or Intel x86 on NeXTSTEP 3.2
 
 1.3) Where can I get PostgreSQL?
 
 The primary anonymous ftp site for PostgreSQL is:
+
    * ftp://ftp.postgreSQL.org/pub
 
 A mirror site exists at:
+
    * ftp://postgres95.vnet.net/pub/postgres95
    * ftp://ftp.luga.or.at/pub/postgres95
    * ftp://cal011111.student.utwente.nl/pub/postgres95
@@ -179,98 +175,93 @@ Section 1: General Questions
 Copyright (c) 1994-6 Regents of the University of California
 
 Permission to use, copy, modify, and distribute this software and its
-   documentation for any purpose, without fee, and without a written
-   agreement is hereby granted, provided that the above copyright notice
-   and this paragraph and the following two paragraphs appear in all
-   copies.
+documentation for any purpose, without fee, and without a written agreement
+is hereby granted, provided that the above copyright notice and this
+paragraph and the following two paragraphs appear in all copies.
 
-   IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
-   FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES,
-   INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND
-   ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN
-   ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
+DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING
+LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION,
+EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.
 
 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
-   INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-   MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
-   PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
-   CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT,
-   UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN
+"AS IS" BASIS, AND THE UNIVERSITY OF 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 original
-   maintainers or from University of California, Berkeley. It is
-   maintained through volunteer effort only.
-   
-   The main mailing list is: questions@postgreSQL.org. It is available
-   for discussion o f matters pertaining to PostgreSQL, including but not
-   limited to bug reports and fixes. For info on how to subscribe, send a
-   mail with the lines in the body (not the subject line)
+There is no official support for PostgreSQL from the original maintainers or
+from University of California, Berkeley. It is maintained through volunteer
+effort only.
 
+The main mailing list is: questions@postgreSQL.org. It is available for
+discussion o f matters pertaining to PostgreSQL, including but not limited
+to bug reports and fixes. For info on how to subscribe, send a mail with the
+lines in the body (not the subject line)
 
         subscribe
         end
 
 to questions-request@postgreSQL.org.
 
-   There is also a digest list available. To subscribe to this list, send
-   email to: questions-digest-request@postgreSQL.org with a BODY of:
-
+There is also a digest list available. To subscribe to this list, send email
+to: questions-digest-request@postgreSQL.org with a BODY of:
 
         subscribe
         end
 
-   Digests are sent out to members of this list whenever the main list
-   has received around 30k of messages.
+Digests are sent out to members of this list whenever the main list has
+received around 30k of messages.
 
-   There is a bugs mailing list available. To subscribe to this list,
-   send email to bugs-request@postgreSQL.org with a BODY of:
-   
-   There is also a developers discussion mailing list available. To
-   subscribe to this list, send email to hackers-request@postgreSQL.org
-   with a BODY of:
+There is a bugs mailing list available. To subscribe to this list, send
+email to bugs-request@postgreSQL.org with a BODY of:
 
+There is also a developers discussion mailing list available. To subscribe
+to this list, send email to hackers-request@postgreSQL.org with a BODY of:
 
         subscribe
         end
 
-   Additional information about PostgreSQL can be found via the
-   PostgreSQL WWW home page at:
+Additional information about PostgreSQL can be found via the PostgreSQL WWW
+home page at:
 
      http://postgreSQL.org
 
 1.6) Latest release of PostgreSQL
 
-   The latest release of PostgreSQL is version 6.2.1, which was released
-   on October 17th, 1997. We are testing 6.3 beta. For information about
-   what is new in 6.3, see our TODO list on our WWW page.
+The latest release of PostgreSQL is version 6.2.1, which was released on
+October 17th, 1997. We are testing 6.3 beta. For information about what is
+new in 6.3, see our TODO list on our WWW page.
 
 We plan to have major releases every three months.
 
 1.7) Is there a commercial version of PostgreSQL?
 
 Illustra Information Technology (a wholly owned subsidiary of Informix
-   Software, Inc.) sells an object-relational DBMS called Illustra that
-   was originally based on postgres. Illustra has cosmetic similarities
-   to PostgreSQL but has more features, is more robust, performs better,
-   and offers real documentation and support. On the flip side, it costs
-   money. For more information, contact sales@illustra.com
+Software, Inc.) sells an object-relational DBMS called Illustra that was
+originally based on postgres. Illustra has cosmetic similarities to
+PostgreSQL but has more features, is more robust, performs better, and
+offers real documentation and support. On the flip side, it costs money. For
+more information, contact sales@illustra.com
 
 1.8) What documentation is available for PostgreSQL?
 
-   A user manual, manual pages, and some small test examples are included
-   in the distribution. The sql and built-in manual pages are
-   particularly important.
+A user manual, manual pages, and some small test examples are included in
+the distribution. The sql and built-in manual pages are particularly
+important.
 
-   The www page contains pointers to an implementation guide and five
-   papers written about postgres design concepts and features.
+The www page contains pointers to an implementation guide and five papers
+written about postgres design concepts and features.
 
 1.9) What version of SQL does PostgreSQL use?
 
 PostgreSQL supports a subset of SQL-92. It has most of the important
-   constructs but lacks some of the functionality. The most visible
-   differences are:
+constructs but lacks some of the functionality. The most visible differences
+are:
+
    * no support for nested subqueries
    * no HAVING clause under a GROUP BY
 
@@ -286,47 +277,50 @@ Section 1: General Questions
 
 Upgrading to 6.2.1 from pre-6.2 requires a dump and restore.
 
-   Upgrading to 6.2.1 from 6.2 does not require a dump, but see the
-   appropriate /migration file in the distribution.
+Upgrading to 6.2.1 from 6.2 does not require a dump, but see the appropriate
+/migration file in the distribution.
 
-   Those ugrading from versions earlier than 1.09 must upgrade to 1.09
-   first without a dump/reload, then dump the data from 1.09, and then
-   load it into 6.2.1 or 6.3 beta.
+Those ugrading from versions earlier than 1.09 must upgrade to 1.09 first
+without a dump/reload, then dump the data from 1.09, and then load it into
+6.2.1 or 6.3 beta.
 
 1.11) Are there ODBC drivers for PostgreSQL?
 
 There are two ODBC drivers available, PostODBC and OpenLink ODBC.
 
-   For all people being interested in PostODBC, there are now two mailing
-   lists devoted to the discussion of PostODBC. The mailing lists are:
+For all people being interested in PostODBC, there are now two mailing lists
+devoted to the discussion of PostODBC. The mailing lists are:
+
    * postodbc-users@listserv.direct. net
    * postodbc-developers@listse rv.direct.net
 
 these lists are ordinary majordomo mailing lists. You can subscribe by
 sending a mail to:
+
    * majordomo@listserv.direct.net
 
 OpenLink ODBC is very popular. You can get it from
-   http://www.openlinksw.com/postgres.html. It works with our standard
-   ODBC client software so you'll have Postgres ODBC available on every
-   client platform we support (Win, Mac, Unix, VMS).
+http://www.openlinksw.com/postgres.html. It works with our standard ODBC
+client software so you'll have Postgres ODBC available on every client
+platform we support (Win, Mac, Unix, VMS).
 
 We will probably be selling this product to people who need
-   commercial-quality support, but a freeware version will always be
-   available. Questions to postgres95@openlink.co.uk.
+commercial-quality support, but a freeware version will always be available.
+Questions to postgres95@openlink.co.uk.
 
 1.12) What tools are available for hooking postgres to Web pages?
 
 A nice introduction to Database-backed Web pages can be seen at:
 http://www.webtools.com
 
-   For web integration, PHP is an excellent interface. The URL for that
-   is http://php.iquest.net
+For web integration, PHP is an excellent interface. The URL for that is
+http://php.iquest.net
 
-   PHP is great for simple stuff, but for more complex stuff, some still
-   use the perl interface and CGI.pm.
+PHP is great for simple stuff, but for more complex stuff, some still use
+the perl interface and CGI.pm.
 
 An WWW gatway 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
@@ -334,14 +328,15 @@ Section 1: General Questions
 
 No. No. No. Not in the official distribution at least. Some users have
 reported some success at using 'pgbrowse' and 'onyx' as frontends to
-   PostgreSQL. Several contributions are working on tk based frontend
-   tools. Ask on the mailing list.
+PostgreSQL. Several contributions are working on tk based frontend tools.
+Ask on the mailing list.
 
 1.14) What is a good book to learn SQL?
 
-   Many of our users like The Practical SQL Handbook, Bowman et al,
-   Addison Wesley.
-     _________________________________________________________________
+Many of our users like The Practical SQL Handbook, Bowman et al, Addison
+Wesley.
+
+  ------------------------------------------------------------------------
 
 Section 2: Installation Questions
 
@@ -350,45 +345,44 @@ Section 2: Installation Questions
    * check to see that you have the proper paths set
    * check that the 'postgres' user owns all the right files
    * ensure that there are files in $PGDATA/files, and that they are
-       non-empty. If they aren't, then "gmake install" failed for some
-       reason
+     non-empty. If they aren't, then "gmake install" failed for some reason
 
 2.2) when I start up the postmaster, I get "FindBackend: could not find a
 backend to execute..." "postmaster: could not find backend to execute..."
 
-   You probably do not have the right path set up. The 'postgres'
-   executable needs to be in your path.
+You probably do not have the right path set up. The 'postgres' executable
+needs to be in your path.
 
 2.3) The system seems to be confused about commas, decimal points, and date
 formats.
 
-   Check your locale configuration. PostgreSQL uses the locale settings
-   of the user that ran the postmaster process. Set those accordingly for
-   your operating environment.
+Check your locale configuration. PostgreSQL uses the locale settings of the
+user that ran the postmaster process. Set those accordingly for your
+operating environment.
 
 2.4) How do I install PostgreSQL somewhere other than /usr/local/pgsql?
 
-   You need to edit Makefile.global and change POSTGRESDIR accordingly,
-   or create a Makefile.custom and define POSTGRESDIR there.
+You need to edit Makefile.global and change POSTGRESDIR accordingly, or
+create a Makefile.custom and define POSTGRESDIR there.
 
 2.5) When I run postmaster, I get a Bad System Call core dumped message.
 
-   It could be a variety of problems, but first check to see that you
-   have system V extensions installed on your kernel. PostgreSQL requires
-   kernel support for shared memory.
+It could be a variety of problems, but first check to see that you have
+system V extensions installed on your kernel. PostgreSQL requires kernel
+support for shared memory.
 
 2.6) When I try to start the postmaster, I get IpcMemoryCreate errors.
 
-   You either do not have shared memory configured properly in kernel or
-   you need to enlarge the shared memory available in the kernel. The
-   exact amount you need depends on your architecture and how many
-   buffers you configure postmaster to run with. For most systems, with
-   default buffer sizes, you need a minimum of ~760K.
+You either do not have shared memory configured properly in kernel or you
+need to enlarge the shared memory available in the kernel. The exact amount
+you need depends on your architecture and how many buffers you configure
+postmaster to run with. For most systems, with default buffer sizes, you
+need a minimum of ~760K.
 
 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'.
+The Makefiles do not have the proper dependencies for include files. You
+have to do a 'make clean' and then another 'make'.
 
 2.8) How do I prevent other hosts from accessing my PostgreSQL backend?
 
@@ -397,83 +391,80 @@ Section 2: Installation Questions
 
 2.9) I can't access the database as the 'root' user.
 
-   You should not create database users with user id 0(root). They will
-   be unable to access the database. This is a security precaution
-   because of the ability of any user to dynamically link object modules
-   into the database engine.
+You should not create database users with user id 0(root). They will be
+unable to access the database. This is a security precaution 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.
+This problem can be caused by a kernel that is not configured to support
+semaphores.
 
 2.11) How do I tune the database engine for better performance?
 
-   There are two things that can be done. You can use Openlink's option
-   to disable fsync() by starting the postmaster with a '-o -F' option.
-   This will prevent fsync()'s from flushing to disk after every
-   transaction.
+There are two things that can be done. You can use Openlink's option to
+disable fsync() by starting the postmaster with a '-o -F' option. This will
+prevent fsync()'s from flushing to disk after every transaction.
 
-   You can also use the postmaster -B option to increase the number of
-   shared memory buffers shared among the backend processes. If you make
-   this parameter too high, the process will not start or crash
-   unexpectedly. Each buffer is 8K and the defualt is 64 buffers.
+You can also use the postmaster -B option to increase the number of shared
+memory buffers shared among the backend processes. If you make this
+parameter too high, the process will not start or crash unexpectedly. Each
+buffer is 8K and the defualt is 64 buffers.
 
-   You can also use the postgres -S option to increase the maximum amount
-   of memory used by each backend process for temporary sorts. Each
-   buffer is 1K and the defualt is 512 buffers.
+You can also use the postgres -S option to increase the maximum amount of
+memory used by each backend process for temporary sorts. Each buffer is 1K
+and the defualt is 512 buffers.
 
 2.12) What debugging features are available in PostgreSQL?
 
-   PostgreSQL has several features that report status information that
-   can be valuable for debugging purposes.
-   
-   First, by running configure with the -enable-cassert option, many
-   assert()'s monitor the progress of the backend and halt the program
-   when something unexpected occurs.
+PostgreSQL has several features that report status information that can be
+valuable for debugging purposes.
 
-   Both postmaster and postgres have several debug options available.
-   First, whenever you start the postmaster, make sure you send the
-   standard output and error to a log file, like:
+First, by running configure with the -enable-cassert option, many assert()'s
+monitor the progress of the backend and halt the program when something
+unexpected occurs.
 
+Both postmaster and postgres have several debug options available. First,
+whenever you start the postmaster, make sure you send the standard output
+and error to a log file, like:
 
         cd /usr/local/pgsql
         ./bin/postmaster >server.log 2>&1 &
 
-   This will put a server.log file in the top-level PostgreSQL directory.
-   This file can contain useful information about problems or errors
-   encountered by the server. Postmaster has a -d option that allows even
-   more detailed information to be reported. The -d option takes a number
-   1-3 that specifies the debug level. Be warned that a debug level of 3
-   generates large log files.
-   
-   You can actuall run the postgres backend from the command line, and
-   type your SQL statement directly. This is recommended ONLY for
-   debugging purposes. Note that a newline terminates the query, not a
-   semicolon. If you have compiled with debugging symbols, you can use a
-   debugger to see what is happening. Because the backend was not started
-   from the postmaster, it is not running in an identical environment and
-   locking/backend interaction problems may not be duplicated. Some
-   operating system can attach to a running backend directly to diagnose
-   problems.
-   
-   The postgres program has a -s, -A, -t options that can be very usefull
-   for debugging and performance measurements.
+This will put a server.log file in the top-level PostgreSQL directory. This
+file can contain useful information about problems or errors encountered by
+the server. Postmaster has a -d option that allows even more detailed
+information to be reported. The -d option takes a number 1-3 that specifies
+the debug level. Be warned that a debug level of 3 generates large log
+files.
+
+You can actuall run the postgres backend from the command line, and type
+your SQL statement directly. This is recommended ONLY for debugging
+purposes. Note that a newline terminates the query, not a semicolon. If you
+have compiled with debugging symbols, you can use a debugger to see what is
+happening. Because the backend was not started from the postmaster, it is
+not running in an identical environment and locking/backend interaction
+problems may not be duplicated. Some operating system can attach to a
+running backend directly to diagnose problems.
+
+The postgres program has a -s, -A, -t options that can be very usefull for
+debugging and performance measurements.
 
 You can also compile with profiling to see what functions are taking
 execution time. The backend profile files will be deposited in the
-   pgsql/data/base/dbname directory. The client profile file will be put
-   in the current directory.
+pgsql/data/base/dbname directory. The client profile file will be put in the
+current directory.
 
 The EXPLAIN command (see this FAQ) allows you to see how PostgreSQL is
 interpreting your query.
 
 2.13) How do I enable more than 32 concurrent backends?
 
-   Edit include/storage/sinvaladt.h, and change the value of
-   MaxBackendId. In the future, we plan to make this a configurable
-   prameter.
-     _________________________________________________________________
+Edit include/storage/sinvaladt.h, and change the value of MaxBackendId. In
+the future, we plan to make this a configurable prameter.
+
+  ------------------------------------------------------------------------
 
 Section 3: PostgreSQL Features
 
@@ -484,30 +475,29 @@ Section 3: PostgreSQL Features
 
 3.2) I've having a lot of problems using rules.
 
-   Currently, the rule system in PostgreSQL is mostly broken. It works
-   enough to support the view mechanism, but that's about it. Use
-   PostgreSQL rules at your own peril.
+Currently, the rule system in PostgreSQL is mostly broken. It works enough
+to support the view mechanism, but that's about it. Use PostgreSQL rules at
+your own peril.
 
 3.3) I can't seem to write into the middle of large objects reliably.
 
-   The Inversion large object system in PostgreSQL is also mostly broken.
-   It works well enough for storing large wads of data and reading them
-   back out, but the implementation has some underlying problems. Use
-   PostgreSQL large objects at your own peril.
+The Inversion large object system in PostgreSQL is also mostly broken. It
+works well enough for storing large wads of data and reading them back out,
+but the implementation has some underlying problems. Use PostgreSQL large
+objects at your own peril.
 
 3.4) How can I write client applications to PostgreSQL?
 
-   PostgreSQL supports a C-callable library interface called libpq as
-   well as many others. See the /src/interfaces directory.
+PostgreSQL supports a C-callable library interface called libpq as well as
+many others. See the /src/interfaces directory.
 
-   Others have contributed a perl interface and a WWW gateway to
-   PostgreSQL. See the PostgreSQL home pages for more details.
+Others have contributed a perl interface and a WWW gateway to PostgreSQL.
+See the PostgreSQL home pages for more details.
 
 3.5) How do I set up a pg_group?
 
-   Currently, there is no easy interface to set up user groups. You have
-   to explicitly insert/update the pg_group table. For example:
-
+Currently, there is no easy interface to set up user groups. You have to
+explicitly insert/update the pg_group table. For example:
 
         jolly=> insert into pg_group (groname, grosysid, grolist)
         jolly=>     values ('posthackers', '1234', '{5443, 8261}');
@@ -517,12 +507,13 @@ Section 3: PostgreSQL Features
         jolly=>
 
 The fields in pg_group are:
+
    * groname: the group name. This a char16 and should be purely
      alphanumeric. Do not include underscores or other punctuation.
-     * grosysid: the group id. This is an int4. This should be unique for
-       each group.
-     * grolist: the list of pg_user id's that belong in the group. This
-       is an int4[].
+   * grosysid: the group id. This is an int4. This should be unique for each
+     group.
+   * grolist: the list of pg_user id's that belong in the group. This is an
+     int4[].
 
 3.6) What is the exact difference between binary cursors and normal cursors?
 
@@ -530,53 +521,50 @@ Section 3: PostgreSQL Features
 
 3.7) What is a R-tree index and what is it used for?
 
-   An r-tree index is used for indexing spatial data. A hash index can't
-   handle range searches. A B-tree index only handles range searches in a
-   single dimension. R-tree's can handle multi-dimensional data. For
-   example, if a R-tree index can be built on an attribute of type
-   'point', the system can more efficient answer queries like select all
-   points within a bounding rectangle.
+An r-tree index is used for indexing spatial data. A hash index can't handle
+range searches. A B-tree index only handles range searches in a single
+dimension. R-tree's can handle multi-dimensional data. For example, if a
+R-tree index can be built on an attribute of type 'point', the system can
+more efficient answer queries like select all points within a bounding
+rectangle.
 
 The canonical paper that describes the original R-Tree design is:
 
-   Guttman, A. "R-Trees: A Dynamic Index Structure for Spatial
-   Searching." Proc of the 1984 ACM SIGMOD Int'l Conf on Mgmt of Data,
-   45-57.
+Guttman, A. "R-Trees: A Dynamic Index Structure for Spatial Searching." Proc
+of the 1984 ACM SIGMOD Int'l Conf on Mgmt of Data, 45-57.
 
-   You can also find this paper in Stonebraker's "Readings in Database
-   Systems"
+You can also find this paper in Stonebraker's "Readings in Database Systems"
 
-   Builtin R-Trees can handle polygons and boxes. In theory, R-trees can
-   be extended to handle higher number of dimensions. In practice,
-   extending R-trees require a bit of work and we don't currently have
-   any documentation on how to do it.
+Builtin R-Trees can handle polygons and boxes. In theory, R-trees can be
+extended to handle higher number of dimensions. In practice, extending
+R-trees require a bit of work and we don't currently have any documentation
+on how to do it.
 
 3.8) What is the maximum size for a tuple?
 
-   Tuples are limited to 8K bytes. Taking into account system attributes
-   and other overhead, one should stay well shy of 8,000 bytes to be on
-   the safe side. To use attributes larger than 8K, try using the large
-   objects interface.
+Tuples are limited to 8K bytes. Taking into account system attributes and
+other overhead, one should stay well shy of 8,000 bytes to be on the safe
+side. To use attributes larger than 8K, try using the large objects
+interface.
 
-   Tuples do not cross 8k boundaries so a 5k tuple will require 8k of
-   storage.
+Tuples do not cross 8k boundaries so a 5k tuple will require 8k of storage.
 
 3.9) I defined indices but my queries don't seem to make use of them. Why?
 
-   PostgreSQL does not automatically maintain statistics. One has to make
-   an explicit 'vacuum' call to update the statistics. After statistics
-   are updated, the optimizer has a better shot at using indices. Note
-   that the optimizer is limited and does not use indices in some
-   circumstances (such as OR clauses). For column-specific optimization
-   statistics, use 'vacuum analyze'.
+PostgreSQL does not automatically maintain statistics. One has to make an
+explicit 'vacuum' call to update the statistics. After statistics are
+updated, the optimizer has a better shot at using indices. Note that the
+optimizer is limited and does not use indices in some circumstances (such as
+OR clauses). For column-specific optimization statistics, use 'vacuum
+analyze'.
 
-   If the system still does not see the index, it is probably because you
-   have created an index on a field with the improper *_ops type. For
-   example, you have created a CHAR(4) field, but have specified a
-   char_ops index type_class.
+If the system still does not see the index, it is probably because you have
+created an index on a field with the improper *_ops type. For example, you
+have created a CHAR(4) field, but have specified a char_ops index
+type_class.
 
-   See the create_index manual page for information on what type classes
-   are available. It must match the field type.
+See the create_index manual page for information on what type classes are
+available. It must match the field type.
 
 Postgres does not warn the user when the improper index is created.
 
@@ -606,14 +594,14 @@ VARCHAR(#)      varchar         size specifies maximum length, no padding
 TEXT            text            length limited only by maximum tuple length
 BYTEA           bytea           variable-length array of bytes
 
-   Remember, you need to use the internal name when creating indexes on
-   these fields or when doing other internal operations.
+You need to use the internal name when doing internal operations.
 
-   The last four types above are "varlena" types (i.e. the first four
-   bytes are the length, followed by the data). CHAR(#) allocates the
-   maximum number of bytes no matter how much data is stored in the
-   field. TEXT, VARCHAR(#), and BYTEA all have variable length on the
-   disk.
+The last four types above are "varlena" types (i.e. the first four bytes are
+the length, followed by the data). CHAR(#) allocates the maximum number of
+bytes no matter how much data is stored in the field. TEXT, VARCHAR(#), and
+BYTEA all have variable length on the disk, and because of this, there is a
+small performance penalty for using them. Specifically, the penalty is for
+access to any columns after the first column of this type.
 
 3.13) In a query, how do I detect if a field is NULL?
 
@@ -625,10 +613,10 @@ BYTEA           bytea           variable-length array of bytes
 
 3.15) How do I create a serial field?
 
-   Postgres does not allow the user to specifiy a user column as type
-   SERIAL. Instead, you can use each row's oid field as a unique value.
-   However, if you need to dump and reload the database, you need to use
-   pgdump's -o option or COPY's WITH OIDS option to preserver the oids.
+Postgres does not allow the user to specifiy a user column as type SERIAL.
+Instead, you can use each row's oid field as a unique value. However, if you
+need to dump and reload the database, you need to use pgdump's -o option or
+COPY's WITH OIDS option to preserver the oids.
 
 We also have a SEQUENCE function that is similar to SERIAL. See the
 create_sequence manual page.
@@ -646,59 +634,56 @@ BYTEA           bytea           variable-length array of bytes
         create table my_stuff (my_key int4, value text);
         insert into my_stuff values (new_oid(), 'hello');
 
-   However, keep in mind there is a race condition here where one server
-   could do the update, then another one do an update, and they both
-   could select the same new id. This statement should be performed
-   within a transaction.
+However, keep in mind there is a race condition here where one server could
+do the update, then another one do an update, and they both could select the
+same new id. This statement should be performed within a transaction.
 
 Yet another way is to use general trigger function autoinc() from
 contrib/spi/autoinc.c.
 
 3.16) What are the pg_psort.XXX files in my database directory?
 
-   They are temporary sort files generated by the query executor. For
-   example, if a sort needs to be done to satisfy an ORDER BY, some temp
-   files are generated as a result of the sort.
+They are temporary sort files generated by the query executor. For example,
+if a sort needs to be done to satisfy an ORDER BY, some temp files are
+generated as a result of the sort.
 
-   If you have no transactions or sorts running at the time, it is safe
-   to delete the pg_psort.XXX files.
+If you have no transactions or sorts running at the time, it is safe to
+delete the pg_psort.XXX files.
 
 3.17) Why can't I connect to my database from another machine?
 
 The default configuration allows only connections from tcp/ip host
-   localhost. You need to add a host entry to the file pgsql/data/pg_hba.
-   See the hba_conf manual page.
+localhost. You need to add a host entry to the file pgsql/data/pg_hba. See
+the hba_conf manual page.
 
 3.18) How do I find out what indexes or operations are defined in the
 database?
 
-   Run the file pgsql/src/tutorial/syscat.source. It illustrates many of
-   the 'select's needed to get information out of the database system
-   tables.
+Run the file pgsql/src/tutorial/syscat.source. It illustrates many of the
+'select's needed to get information out of the database system tables.
 
 3.19) What is the time-warp feature and how does it relate to vacuum?
 
-   PostgreSQL handles data changes differently than most database
-   systems. When a row is changed in a table, the original row is marked
-   with the time it was changed, and a new row is created with the
-   current data. By default, only current rows are used in a table. If
-   you specify a date/time after the table name in a FROM clause, you can
-   access the data that was current at that time, i.e.
-
+PostgreSQL handles data changes differently than most database systems. When
+a row is changed in a table, the original row is marked with the time it was
+changed, and a new row is created with the current data. By default, only
+current rows are used in a table. If you specify a date/time after the table
+name in a FROM clause, you can access the data that was current at that
+time, i.e.
 
         SELECT *
         FROM employees ['July 24, 1996 09:00:00']
 
-   displays employee rows in the table at the specified time. You can
-   specify intervals like [date,date], [date,], [,date], or [,]. This
-   last option accesses all rows that ever existed.
+displays employee rows in the table at the specified time. You can specify
+intervals like [date,date], [date,], [,date], or [,]. This last option
+accesses all rows that ever existed.
 
-   INSERTed rows get a timestamp too, so rows that were not in the table
-   at the desired time will not appear.
+INSERTed rows get a timestamp too, so rows that were not in the table at the
+desired time will not appear.
 
-   Vacuum removes rows that are no longer current. This time-warp feature
-   is used by the engine for rollback and crash recovery. Expiration
-   times can be set with purge.
+Vacuum removes rows that are no longer current. This time-warp feature is
+used by the engine for rollback and crash recovery. Expiration times can be
+set with purge.
 
 In 6.0, once a table is vacuumed, the creation time of a row may be
 incorrect, causing time-traval to fail.
@@ -707,28 +692,29 @@ BYTEA           bytea           variable-length array of bytes
 
 3.20) What is an oid? What is a tid?
 
-   Oids are Postgres's answer to unique row ids or serial columns. Every
-   row that is created in Postgres gets a unique oid. All oids generated
-   by initdb are less than 16384 (from backend/access/transam.h). All
-   post-initdb (user-created) oids are equal or greater that this. All
-   these oids are unique not only within a table, or database, but unique
-   within the entire postgres installation.
+Oids are Postgres's answer to unique row ids or serial columns. Every row
+that is created in Postgres gets a unique oid. All oids generated by initdb
+are less than 16384 (from backend/access/transam.h). All post-initdb
+(user-created) oids are equal or greater that this. All these oids are
+unique not only within a table, or database, but unique within the entire
+postgres installation.
 
-   Postgres uses oids in its internal system tables to link rows in
-   separate tables. These oids can be used to identify specific user rows
-   and used in joins. It is recommended you use column type oid to store
-   oid values. See the sql(l) manual page to see the other internal
-   columns. You can create an index on the oid field for faster access.
+Postgres uses oids in its internal system tables to link rows in separate
+tables. These oids can be used to identify specific user rows and used in
+joins. It is recommended you use column type oid to store oid values. See
+the sql(l) manual page to see the other internal columns. You can create an
+index on the oid field for faster access.
 
-   Tids are used to indentify specific physical rows with block and
-   offset values. Tids change after rows are modified or reloaded. They
-   are used by index entries to point to physical rows. They can not be
-   accessed through sql.
+Tids are used to indentify specific physical rows with block and offset
+values. Tids change after rows are modified or reloaded. They are used by
+index entries to point to physical rows. They can not be accessed through
+sql.
 
 3.21) What is the meaning of some of the terms used in Postgres?
 
-   Some of the source code and older documentation use terms that have
-   more common usage. Here are some:
+Some of the source code and older documentation use terms that have more
+common usage. Here are some:
+
    * row, record, tuple
    * attribute, field, column
    * table, class
@@ -743,10 +729,9 @@ BYTEA           bytea           variable-length array of bytes
 
 3.22) What is Genetic Query Optimization?
 
-   The GEQO module in PostgreSQL is intended to solve the query
-   optimization problem of joining many tables by means of a Genetic
-   Algorithm (GA). It allows the handling of large join queries through
-   non-exhaustive search.
+The GEQO module in PostgreSQL is intended to solve the query optimization
+problem of joining many tables by means of a Genetic Algorithm (GA). It
+allows the handling of large join queries through non-exhaustive search.
 
 For further information see README.GEQO <utesch@aut.tu-freiberg.de>.
 
@@ -764,24 +749,23 @@ BYTEA           bytea           variable-length array of bytes
 
 See the fetch manual page.
 
-   This only prevents all row results from being transfered to the
-   client. The entire query must be evaluated, even if you only want just
-   first few rows. Consider a query that has and ORDER BY. There is no
-   way to return any rows until the entire query is evaluated and sorted.
+This only prevents all row results from being transfered to the client. The
+entire query must be evaluated, even if you only want just first few rows.
+Consider a query that has and ORDER BY. There is no way to return any rows
+until the entire query is evaluated and sorted.
 
 3.25) Why can't I create a column named "time"?
 
-   6.2.1 has added some new restricted keywords as we make PostgreSQL
-   more ANSI-92 compilant. The next release will have this restriction
-   removed. There is a patch on ftp.postgresql.org that will allow this
-   feature now.
+6.2.1 has added some new restricted keywords as we make PostgreSQL more
+ANSI-92 compilant. The next release will have this restriction removed.
+There is a patch on ftp.postgresql.org that will allow this feature now.
 
 3.26)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:
+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
@@ -803,7 +787,8 @@ The data page size in PostgreSQL is 8192(8k) bytes, so:
 
 Indexes do not contain as much overhead, but do contain the data that
 is being indexed, so they can be large also.
-     _________________________________________________________________
+
+  ------------------------------------------------------------------------
 
 Section 4: Extending PostgreSQL
 
@@ -811,30 +796,30 @@ Section 4: Extending PostgreSQL
 core.
 
 The problem could be a number of things. Try testing your user-defined
-   function in a stand alone test program first. Also, make sure you are
-   not sending elog NOTICES when the front-end is expecting data, such as
-   during a type_in() or type_out() functions
+function in a stand alone test program first. Also, make sure you are not
+sending elog NOTICES when the front-end is expecting data, such as during a
+type_in() or type_out() functions
 
 4.2) I get messages of the type NOTICE:PortalHeapMemoryFree: 0x402251d0 not
 in alloc set!
 
 You are pfree'ing something that was not palloc'ed. When writing
-   user-defined functions, do not include the file "libpq-fe.h". Doing so
-   will cause your palloc to be a malloc instead of a free. Then, when
-   the backend pfrees the storage, you get the notice message.
+user-defined functions, do not include the file "libpq-fe.h". Doing so will
+cause your palloc to be a malloc instead of a free. Then, when the backend
+pfrees the storage, you get the notice message.
 
 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.
+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. The short answer is
-   ... you can't. This capability is forthcoming in the future.
-     _________________________________________________________________
+This requires extreme wizardry, so extreme that the authors have not ever
+tried it, though in principle it can be done. The short answer is ... you
+can't. This capability is forthcoming in the future.
+
+  ------------------------------------------------------------------------
 
 Section 5: Bugs
 
@@ -842,10 +827,11 @@ Section 5: Bugs
 
 Check the current FAQ at http://postgreSQL.org
 
-   Also check out our ftp site ftp://ftp.postgreSQL.org/pub to see if
-   there is a more recent PostgreSQL version.
+Also check out our ftp site ftp://ftp.postgreSQL.org/pub to see if there is
+a more recent PostgreSQL version.
 
 You can also fill out the "bug-template" file and send it to:
+
    * bugs@postgreSQL.org
 
 This is the address of the developers mailing list.

doc/FAQ_Linux

@@ -4,7 +4,7 @@ Frequently Asked Questions (FAQ) for PostgreSQL >= V6.1
 Linux Specific
 TO BE READ IN CONJUNCTION WITH THE NORMAL FAQ
 =======================================================
-last updated:           Thu Dec 15 12:05:00 GMT 1997
+last updated:           Wed Feb 18 13:00:00 GMT 1997
 
 current maintainer:     Andrew C.R. Martin (martin@biochem.ucl.ac.uk)
 original author:        Andrew C.R. Martin (martin@biochem.ucl.ac.uk)
@@ -12,10 +12,8 @@ original author:        Andrew C.R. Martin (martin@biochem.ucl.ac.uk)
 
 Changes in this version (* = modified, + = new, - = removed):
 
-*1.3)   [REDHAT] Why do I get problems with missing libdl and dlfcn.h?
-*1.4)   [SLACKWARE 3.1] Why do I get problems with missing libdl and dlfcn.h?
-+1.19)  Why does make exit or crash?
-
++1.20)  How can I optimise for 486 or pentium processors
++3.10)  Why do I get funny rounding results in some date/time arithmetic...
 
 This file is divided approximately as follows:
 1.*)    Installing PostgreSQL
@@ -55,6 +53,7 @@ Questions answered:
 1.17)   When compiling postgres, gcc reports signal 11 and aborts.
 1.18)   Can I install 6.1.1 under MkLinux?
 1.19)   Why does make exit or crash?
+1.20)   How can I optimise for 486 or pentium processors
 2.1)    The linker fails to find libX11 when compiling pgtclsh
 3.1)    I get an error reporting _fUnKy_POSTPORT_sTuFf_ undefined when 
         running scripts like createuser
@@ -77,6 +76,10 @@ Questions answered:
 3.8)    When PostgreSQL is running when the system is shutdown, Linux
         always fsck's the disk when rebooted.
 3.9)    Why does Query 32 in the regression tests take so long?
+3.10)   Why do I get funny rounding results in some date/time arithmetic,
+        such as
+           select '4 hours'::timespan;
+        returning '3 hours 59 minutes 60 seconds'?
 
 ----------------------------------------------------------------------
 Section 1:      Compiling PostgreSQL
@@ -298,7 +301,7 @@ Section 1:      Compiling PostgreSQL
 
         Some versions of SuSE provide only ncurses, so you may need
         to force use of ncurses rather than curses by changing 
-        -lcurses to -lncurses.
+        -lcurses to -lncurses. (Reported true for SuSE 5.1)
 
 
 1.9)    Why do I get problems with ld.so?
@@ -430,6 +433,19 @@ Section 1:      Compiling PostgreSQL
         In short, try upgrading gmake to the latest version you can 
         find before reporting this as a problem
 
+1.20)   How can I optimise for 486 or pentium processors
+
+        The default compiler flags perform no optimisation for 486
+        or Pentium processors. To add such optimisation, edit
+        Makefile.custom and add:
+
+           CFLAGS+= -m486
+
+        or (for the new compilers that most people are not yet running)
+
+           CFLAGS+= -mpentium
+        or
+           CFLAGS+= -mpentiumpro
 
 ----------------------------------------------------------------------
 Section 2:      Compiling accessory programs
@@ -617,6 +633,15 @@ exit 0
         then type:
                 sh ./perquery < bench.out > & bench.out.perquery
 
+
+
+3.10)   Why do I get funny rounding results in some date/time arithmetic,
+        such as
+           select '4 hours'::timespan;
+        returning '3 hours 59 minutes 60 seconds'?
+
+        You are running the new glibc2 libraries and have a version earlier than
+        2.0.7. It is a math rounding problem in the library. Upgrade your library.
 ----------------------------------------------------------------------------
 Dr. Andrew C.R. Martin                             University College London
 EMAIL: (Work) martin@biochem.ucl.ac.uk    (Home) andrew@stagleys.demon.co.uk

src/tools/FAQ_DEV

+Developer's Frequently Asked Questions (FAQ) for PostgreSQL
+
+Last updated: Wed Feb 11 20:23:01 EST 1998
+
+Current maintainer: Bruce Momjian (maillist@candle.pha.pa.us)
+
+The most recent version of this document can be viewed at the postgreSQL Web
+site, http://postgreSQL.org.
+
+  ------------------------------------------------------------------------
+
+Questions answered:
+
+1) What tools are available for developers?
+2) What books are good for developers?
+3) Why do we use palloc() and pfree() to allocate memory?
+4) Why do we use Node and List to make data structures?
+5) How do I add a feature or fix a bug?
+6) How do I download/update the current source tree?
+7) How do I test my changes?
+
+  ------------------------------------------------------------------------
+
+1) What tools are available for developers?
+
+Aside from the User documentation mentioned in the regular FAQ, there are
+several development tools available. First, all the files in the /tools
+directory are designed for developers.
+
+        RELEASE_CHANGES         changes we have to make for each release
+        SQL_keywords            standard SQL'92 keywords
+        backend                 web flowchart of the backend directories
+        ccsym                   find standard defines made by your compiler
+        entab                   converts tabs to spaces, used by pgindent
+        find_static             finds functions that could be made static
+        find_typedef            get a list of typedefs in the source code
+        make_ctags              make vi 'tags' file in each directory
+        make_diff               make *.orig and diffs of source
+        make_etags              make emacs 'etags' files
+        make_keywords.README    make comparison of our keywords and SQL'92
+        make_mkid               make mkid ID files
+        mkldexport              create AIX exports file
+        pgindent                indents C source files
+
+Let me note some of these. If you point your browser at the tools/backend
+directory, you will see all the backend components in a flow chart. You can
+click on any one to see a description. If you then click on the directory
+name, you will be taken to the source directory, to browse the actual source
+code behind it. We also have several README files in some source directories
+to describe the function of the module. The browser will display these when
+you enter the directory also. The tools/backend directory is also contained
+on our web page under the title Backend Flowchart.
+
+Second, you really should have an editor that can handle tags, so you can
+tag a function call to see the function definition, and then tag inside that
+function to see an even lower-level function, and then back out twice to
+return to the original function. Most editors support this via tags or etags
+files.
+
+Third, you need to get mkid from ftp.postgresql.org. By running
+tools/make_mkid, an archive of source symbols can be created that can be
+rapidly queried like grep or edited.
+
+make_diff has tools to create patch diff files that can be applied to the
+distribution.
+
+pgindent will format source files to match our standard format, which has
+four-space tabs, and an indenting format specified by flags to the your
+operating system's utility indent.
+
+2) What books are good for developers?
+
+I have two good books, An Introduction to Database Systems, by C.J. Date,
+Addison, Wesley and A Guide to the SQL Standard, by C.J. Date, et. al,
+Addison, Wesley.
+
+3) Why do we use palloc() and pfree() to allocate memory?
+
+palloc() and pfree() are used in place of malloc() and free() because we
+automatically free all memory allocated when a transaction completes. This
+makes it easier to make sure we free memory that gets allocated in one
+place, but only freed much later. There are several contexts that memory can
+be allocated in, and this controls when the allocated memory is
+automatically freed by the backend.
+
+4) Why do we use Node and List to make data structures?
+
+We do this because this allows a consistent way to pass data inside the
+backend in a flexible way. Every node has a NodeTag which specifies what
+type of data is inside the Node. Lists are lists of Nodes. lfirst(),
+lnext(), and foreach() are used to get, skip, and traverse through Lists.
+
+5) How do I add a feature or fix a bug?
+
+The source code is over 250,000 lines. Many problems/features are isolated
+to one specific area of the code. Others require knowledge of much of the
+source. If you are confused about where to start, ask the hackers list, and
+they will be glad to assess the complexity and give pointers on where to
+start.
+
+Another thing to keep in mind is that many fixes and features can be added
+with surprisingly little code. I often start by adding code, then looking at
+other areas in the code where similar things are done, and by the time I am
+finished, the patch is quite small and compact.
+
+When adding code, keep in mind that it should use the existing facilities in
+the source, for performance reasons and for simplicity. Often a review of
+existing code doing similar things is helpful.
+
+6) How do I download/update the current source tree?
+
+There are several ways to obtain the source tree. Occasional developers can
+just get the most recent source tree snapshot from ftp.postgresql.org. For
+regular developers, you can get CVSup, which is available from
+ftp.postgresql.org too. CVSup allows you to download the source tree, then
+occasionally update your copy of the source tree with any new changes. Using
+CVSup, you don't have to download the entire source each time, only the
+changed files. CVSup does not allow developers to update the source tree.
+
+To update the source tree, there are two ways. You can generate a patch
+against your current source tree, perhaps using the make_diff tools
+mentioned above, and send them to the patches list. They will be reviewed,
+and applied in a timely manner. If the patch is major, and we are in beta
+testing, the developers may wait for the final release before applying your
+patches.
+
+For hard-core developers, Marc(scrappy@postgresql.org) will give you a Unix
+shell account on postgresql.org, and you can ftp your files into your
+account, patch, and cvs install the changes directly into the source tree.
+
+6) How do I test my changes?
+
+First, use psql to make sure it is working as you expect. Then run
+src/test/regress and get the output of src/test/regress/checkresults with
+and without your changes, to see that your patch does not change the
+regression test in unexpected ways. This practice has saved me many times.
+The regression tests test the code in ways I would never do, and has caught
+many bugs in my patches. By finding the problems now, you save yourself a
+lot of debugging later when things are broken, and you can't figure out when
+it happened.