Rename SortMem and VacuumMem to work_mem and maintenance_work_mem.

Make btree index creation and initial validation of foreign-key constraints
use maintenance_work_mem rather than work_mem as their memory limit.
Add some code to guc.c to allow these variables to be referenced by their
old names in SHOW and SET commands, for backwards compatibility.

7 files changed, 70 insertions, 67 deletions

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 864fb37f982..c235cf9e4f5 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.34 2004/01/19 20:12:30 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.35 2004/02/03 17:34:02 tgl Exp $
 -->
 <chapter id="backup">
  <title>Backup and Restore</title>
@@ -156,8 +156,8 @@ pg_dump -h <replaceable>host1</> <replaceable>dbname</> | psql -h <replaceable>h
    <tip>
     <para>
     Restore performance can be improved by increasing the
-    configuration parameter <varname>sort_mem</varname> (see <xref
-    linkend="runtime-config-resource-memory">).
+    configuration parameter <varname>maintenance_work_mem</varname>
+    (see <xref linkend="runtime-config-resource-memory">).
     </para>
    </tip>
   </sect2>
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 368d82e3cbf..6cfe75aeae0 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.193 2004/01/19 21:20:06 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.194 2004/02/03 17:34:02 tgl Exp $ -->
 
 <chapter id="installation">
  <title><![%standalone-include[<productname>PostgreSQL</>]]>
@@ -1399,7 +1399,7 @@ kill `cat /usr/local/pgsql/data/postmaster.pid`
       not designed for optimum performance. To achieve optimum
       performance, several server parameters must be adjusted, the two
       most common being <varname>shared_buffers</varname> and
-      <varname> sort_mem</varname> mentioned in the documentation.
+      <varname>work_mem</varname>.
       Other parameters mentioned in the documentation also affect
       performance.
      </para>
diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml
index 923612c290c..c7d947eaf7a 100644
--- a/doc/src/sgml/perform.sgml
+++ b/doc/src/sgml/perform.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.40 2004/01/11 05:46:58 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.41 2004/02/03 17:34:02 tgl Exp $
 -->
 
  <chapter id="performance-tips">
@@ -684,16 +684,18 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
    </para>
   </sect2>
 
-  <sect2 id="populate-sort-mem">
-   <title>Increase <varname>sort_mem</varname></title>
+  <sect2 id="populate-work-mem">
+   <title>Increase <varname>maintenance_work_mem</varname></title>
 
    <para>
-    Temporarily increasing the <varname>sort_mem</varname>
+    Temporarily increasing the <varname>maintenance_work_mem</varname>
     configuration variable when restoring large amounts of data can
     lead to improved performance. This is because when a B-tree index
     is created from scratch, the existing content of the table needs
-    to be sorted. Allowing the merge sort to use more buffer pages
-    means that fewer merge passes will be required.
+    to be sorted. Allowing the merge sort to use more memory
+    means that fewer merge passes will be required.  A larger setting for
+    <varname>maintenance_work_mem</varname> may also speed up validation
+    of foreign-key constraints.
    </para>
   </sect2>
 
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 0e7f7ad5d0a..7cce45b75e0 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.34 2004/01/24 22:05:08 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.35 2004/02/03 17:34:02 tgl Exp $
 -->
 
 <chapter id="plpgsql"> 
@@ -1354,7 +1354,7 @@ SELECT * FROM some_func();
        allow users to define set-returning functions
        that do not have this limitation.  Currently, the point at
        which data begins being written to disk is controlled by the
-       <varname>sort_mem</> configuration variable.  Administrators
+       <varname>work_mem</> configuration variable.  Administrators
        who have sufficient memory to store larger result sets in
        memory should consider increasing this parameter.
       </para>
diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml
index 3ae6003120b..cfb16a78686 100644
--- a/doc/src/sgml/ref/postgres-ref.sgml
+++ b/doc/src/sgml/ref/postgres-ref.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.42 2003/11/29 19:51:39 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.43 2004/02/03 17:34:02 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -41,7 +41,7 @@ PostgreSQL documentation
     <arg>-s</arg>
     <arg>-t<group choice="plain"><arg>pa</arg><arg>pl</arg><arg>ex</arg></group></arg>
    </group>
-   <arg>-S <replaceable>sort-mem</replaceable></arg>
+   <arg>-S <replaceable>work-mem</replaceable></arg>
    <arg>-W <replaceable>seconds</replaceable></arg>
    <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
    <arg choice="plain"><replaceable>database</replaceable></arg>
@@ -64,7 +64,7 @@ PostgreSQL documentation
     <arg>-s</arg>
     <arg>-t<group choice="plain"><arg>pa</arg><arg>pl</arg><arg>ex</arg></group></arg>
    </group>
-   <arg>-S <replaceable>sort-mem</replaceable></arg>
+   <arg>-S <replaceable>work-mem</replaceable></arg>
    <arg>-v <replaceable>protocol</replaceable></arg>
    <arg>-W <replaceable>seconds</replaceable></arg>
    <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
@@ -197,16 +197,13 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
-      <term><option>-S</option> <replaceable class="parameter">sort-mem</replaceable></term>
+      <term><option>-S</option> <replaceable class="parameter">work-mem</replaceable></term>
       <listitem>
        <para>
 	Specifies the amount of memory to be used by internal sorts and hashes
-	before resorting to temporary disk files.  The value is specified in
-	kilobytes, and defaults to 1024.  Note that for a complex query,
-	several sorts and/or hashes might be running in parallel, and each one
-	will be allowed to use as much as
-	<replaceable class="parameter">sort-mem</replaceable> kilobytes
-	before it starts to put data into temporary files.
+	before resorting to temporary disk files.  See the description of the
+	<varname>work_mem</> configuration parameter in <xref
+	linkend="runtime-config-resource-memory">.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml
index 6623b247de7..d829a7e2d11 100644
--- a/doc/src/sgml/ref/postmaster.sgml
+++ b/doc/src/sgml/ref/postmaster.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.44 2003/12/14 00:15:03 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.45 2004/02/03 17:34:02 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -541,10 +541,10 @@ PostgreSQL documentation
   <para>
    Named run-time parameters can be set in either of these styles:
 <screen>
-<prompt>$</prompt> <userinput>postmaster -c sort_mem=1234</userinput>
-<prompt>$</prompt> <userinput>postmaster --sort-mem=1234</userinput>
+<prompt>$</prompt> <userinput>postmaster -c work_mem=1234</userinput>
+<prompt>$</prompt> <userinput>postmaster --work-mem=1234</userinput>
 </screen>
-   Either form overrides whatever setting might exist for <varname>sort_mem</>
+   Either form overrides whatever setting might exist for <varname>work_mem</>
    in <filename>postgresql.conf</>.  Notice that underscores in parameter
    names can be written as either underscore or dash on the command line.
   </para>
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index a38e6c01598..71d7f0621c8 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.235 2004/01/27 16:51:43 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.236 2004/02/03 17:34:02 tgl Exp $
 -->
 
 <Chapter Id="runtime">
@@ -850,37 +850,41 @@ SET ENABLE_SEQSCAN TO OFF;
      </varlistentry>
 
      <varlistentry>
-      <term><varname>sort_mem</varname> (<type>integer</type>)</term>
+      <term><varname>work_mem</varname> (<type>integer</type>)</term>
       <listitem>
        <para>
-        Specifies the amount of memory to be used by internal sort operations and
-        hash tables before switching to temporary disk files. The value is
+        Specifies the amount of memory to be used by internal sort operations
+        and hash tables before switching to temporary disk files. The value is
         specified in kilobytes, and defaults to 1024 kilobytes (1 MB).
         Note that for a complex query, several sort or hash operations might be
         running in parallel; each one will be allowed to use as much memory
         as this value specifies before it starts to put data into temporary
-        files. Also, several running sessions could be doing
-        sort operations simultaneously.  So the total memory used could be many
-        times the value of <varname>sort_mem</varname>. Sort operations are used
-        by <literal>ORDER BY</>, merge joins, and <command>CREATE INDEX</>.
+        files. Also, several running sessions could be doing such operations
+        concurrently.  So the total memory used could be many
+        times the value of <varname>work_mem</varname>; it is necessary to
+        keep this fact in mind when choosing the value. Sort operations are
+        used for <literal>ORDER BY</>, <literal>DISTINCT</>, and
+        merge joins.
         Hash tables are used in hash joins, hash-based aggregation, and
-        hash-based processing of <literal>IN</> subqueries.  Because 
-        <command>CREATE INDEX</> is used when restoring a database,
-        increasing <varname>sort_mem</varname> before doing a large
-        restore operation can improve performance.
+        hash-based processing of <literal>IN</> subqueries.
        </para>
       </listitem>
      </varlistentry>
      
      <varlistentry>
-      <term><varname>vacuum_mem</varname> (<type>integer</type>)</term>
+      <term><varname>maintenance_work_mem</varname> (<type>integer</type>)</term>
       <listitem>
        <para>
-        Specifies the maximum amount of memory to be used by
-        <command>VACUUM</command> to keep track of to-be-reclaimed
-        rows. The value is specified in kilobytes, and defaults to
-        8192 kB. Larger settings may improve the speed of
-        vacuuming large tables that have many deleted rows.
+        Specifies the maximum amount of memory to be used in maintenance
+        operations, such as <command>VACUUM</command>, <command>CREATE
+        INDEX</>, and <command>ALTER TABLE ADD FOREIGN KEY</>.
+        The value is specified in kilobytes, and defaults to 16384 kilobytes
+        (16 MB).  Since only one of these operations can be executed at 
+        a time by a database session, and an installation normally doesn't
+        have very many of them happening concurrently, it's safe to set this
+        value significantly larger than <varname>work_mem</varname>.  Larger
+        settings may improve performance for vacuuming and for restoring
+        database dumps.
        </para>
       </listitem>
      </varlistentry>
@@ -1412,25 +1416,25 @@ SET ENABLE_SEQSCAN TO OFF;
        <para>
         Various tuning parameters for the genetic query optimization
         algorithm.  The recommended one to modify is
-	<varname>geqo_effort</varname>, which can range from 1 to 10 with
-	a default of 5.  Larger values increase the time spent in planning
-	but make it more likely that a good plan will be found.
-	<varname>geqo_effort</varname> doesn't actually do anything directly,
-	it is just used to compute the default values for the other
-	parameters.  If you prefer, you can set the other parameters by hand
-	instead.
-	The pool size is the number of individuals in the genetic population.
-	It must be at least two, and useful values are typically 100 to 1000.
-	If it is set to zero (the default setting) then a suitable default
-	is chosen based on <varname>geqo_effort</varname> and the number of
-	tables in the query.
-	Generations specifies the number of iterations of the algorithm.
-	It must be at least one, and useful values are in the same range
-	as the pool size.
-	If it is set to zero (the default setting) then a suitable default
-	is chosen based on the pool size.
-	The run time of the algorithm is roughly proportional to the sum of
-	pool size and generations.
+        <varname>geqo_effort</varname>, which can range from 1 to 10 with
+        a default of 5.  Larger values increase the time spent in planning
+        but make it more likely that a good plan will be found.
+        <varname>geqo_effort</varname> doesn't actually do anything directly,
+        it is just used to compute the default values for the other
+        parameters.  If you prefer, you can set the other parameters by hand
+        instead.
+        The pool size is the number of individuals in the genetic population.
+        It must be at least two, and useful values are typically 100 to 1000.
+        If it is set to zero (the default setting) then a suitable default
+        is chosen based on <varname>geqo_effort</varname> and the number of
+        tables in the query.
+        Generations specifies the number of iterations of the algorithm.
+        It must be at least one, and useful values are in the same range
+        as the pool size.
+        If it is set to zero (the default setting) then a suitable default
+        is chosen based on the pool size.
+        The run time of the algorithm is roughly proportional to the sum of
+        pool size and generations.
         The selection bias is the selective pressure within the
         population. Values can be from 1.50 to 2.00; the latter is the
         default.
@@ -2840,7 +2844,7 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
        <row>
         <entry><option>-S <replaceable>x</replaceable></option><footnoteref linkend="fn.runtime-config-short">
         </entry>
-        <entry><literal>sort_mem = <replaceable>x</replaceable></></entry>
+        <entry><literal>work_mem = <replaceable>x</replaceable></></entry>
        </row>
 
        <row>
@@ -3230,7 +3234,7 @@ kernel.shmmax = 134217728
        <para>
         In OS X 10.2 and earlier, edit the file
         <filename>/System/Library/StartupItems/SystemTuning/SystemTuning</>
-	and change the values in the following commands:
+        and change the values in the following commands:
 <programlisting>
 sysctl -w kern.sysv.shmmax
 sysctl -w kern.sysv.shmmin
@@ -3239,7 +3243,7 @@ sysctl -w kern.sysv.shmseg
 sysctl -w kern.sysv.shmall
 </programlisting>
         In OS X 10.3, these commands have been moved to <filename>/etc/rc</>
-	and must be edited there.
+        and must be edited there.
        </para>
       </listitem>
      </varlistentry>