Update documentation about shared memory sizing to reflect current

reality.

doc/src/sgml/runtime.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.349 2005/08/29 21:38:17 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.350 2005/08/30 00:58:47 tgl Exp $
 -->
 
 <chapter Id="runtime">
@@ -1161,7 +1161,7 @@ SET ENABLE_SEQSCAN TO OFF;
         buffers is only a buffer descriptor, or about 64 bytes, per
         increment in <varname>temp_buffers</>.  However if a buffer is
         actually used an additional 8192 bytes will be consumed for it
-        (or in general <symbol>BLCKSZ</symbol> bytes).
+        (or in general, <symbol>BLCKSZ</symbol> bytes).
        </para>
       </listitem>
      </varlistentry>
@@ -1183,6 +1183,14 @@ SET ENABLE_SEQSCAN TO OFF;
         This option can only be set at server start.
        </para>
 
+       <para>
+        If you are not using prepared transactions, this parameter may as
+        well be set to zero.  If you are using them, you will probably
+        want <varname>max_prepared_transactions</varname> to be at least
+        as large as <xref linkend="guc-max-connections">, to avoid unwanted
+        failures at the prepare step.
+       </para>
+
        <para>
         Increasing this parameter may cause <productname>PostgreSQL</>
         to request more <systemitem class="osname">System V</> shared
@@ -1267,6 +1275,32 @@ SET ENABLE_SEQSCAN TO OFF;
      <sect3 id="runtime-config-resource-fsm">
      <title>Free Space Map</title>
 
+     <indexterm>
+      <primary>free space map</primary>
+     </indexterm>
+
+     <para>
+      These parameters control the size of the shared <firstterm>free space
+      map</>, which tracks the locations of unused space in the database.
+      An undersized free space map may cause the database to consume
+      increasing amounts of disk space over time, because free space that
+      is not in the map cannot be re-used; instead <productname>PostgreSQL</>
+      will request more disk space from the operating system when it needs
+      to store new data.
+      The last few lines displayed by a database-wide <command>VACUUM VERBOSE</> 
+      command can help in determining if the current settings are adequate.
+      A <literal>NOTICE</> message is also printed during such an operation
+      if the current settings are too low.
+     </para>
+
+     <para>
+      Increasing these parameters may cause <productname>PostgreSQL</>
+      to request more <systemitem class="osname">System V</> shared
+      memory than your operating system's default configuration
+      allows. See <xref linkend="sysvipc"> for information on how to
+      adjust those parameters, if necessary.
+     </para>
+
      <variablelist>
      <varlistentry id="guc-max-fsm-pages" xreflabel="max_fsm_pages">
       <term><varname>max_fsm_pages</varname> (<type>integer</type>)</term>
@@ -1279,10 +1313,6 @@ SET ENABLE_SEQSCAN TO OFF;
         be tracked in the shared free-space map.  Six bytes of shared memory
         are consumed for each page slot.  This setting must be more than
         16 * <varname>max_fsm_relations</varname>.  The default is 20000.
-        The last few lines of a database-wide <command>VACUUM VERBOSE</> 
-        can help in determining if the the default setting is suitable.  
-        A <literal>NOTICE</> message is also printed during such an operation
-        if the current setting is too low.
         This option can only be set at server start.
        </para>
       </listitem>
@@ -1297,12 +1327,8 @@ SET ENABLE_SEQSCAN TO OFF;
        <para>
         Sets the maximum number of relations (tables and indexes) for which
         free space will be tracked in the shared free-space map.  Roughly
-        fifty bytes of shared memory are consumed for each slot.
+        seventy bytes of shared memory are consumed for each slot.
         The default is 1000.
-        The last few lines of a database-wide <command>VACUUM VERBOSE</>
-        can help in determining if the the default setting is suitable.  
-        A <literal>NOTICE</> message is also printed during such an operation
-        if the current setting is too low.
         This option can only be set at server start.
        </para>
       </listitem>
@@ -1804,9 +1830,18 @@ SET ENABLE_SEQSCAN TO OFF;
        <para>
         Number of disk-page buffers allocated in shared memory for WAL data.
         The default is 8.  The setting need only be large enough to hold
-        the amount of WAL data generated by one typical transaction.
+        the amount of WAL data generated by one typical transaction, since
+        the data is flushed to disk at every transaction commit.
         This option can only be set at server start.
        </para>
+
+       <para>
+        Increasing this parameter may cause <productname>PostgreSQL</>
+        to request more <systemitem class="osname">System V</> shared
+        memory than your operating system's default configuration
+        allows. See <xref linkend="sysvipc"> for information on how to
+        adjust those parameters, if necessary.
+       </para>
       </listitem>
      </varlistentry>
                 
@@ -3952,9 +3987,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
       </indexterm>
       <listitem>
        <para>
-        The shared lock table is sized on the assumption that at most
+        The shared lock table is created with room to describe locks on
         <varname>max_locks_per_transaction</varname> *
-        <varname>max_connections</varname> distinct objects will need to
+        (<xref linkend="guc-max-connections"> +
+        <xref linkend="guc-max-prepared-transactions">) objects;
+        hence, no more than this many distinct objects can
         be locked at any one time. (Thus, this parameter's name may be
         confusing: it is not a hard limit on the number of locks taken
         by any one transaction, but rather a maximum average value.)
@@ -3963,6 +4000,14 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
         have clients that touch many different tables in a single
         transaction. This option can only be set at server start.
        </para>
+
+       <para>
+        Increasing this parameter may cause <productname>PostgreSQL</>
+        to request more <systemitem class="osname">System V</> shared
+        memory than your operating system's default configuration
+        allows. See <xref linkend="sysvipc"> for information on how to
+        adjust those parameters, if necessary.
+       </para>
       </listitem>
      </varlistentry>
 
@@ -4653,9 +4698,10 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
     relevant for <productname>PostgreSQL</>). Almost all modern
     operating systems provide these features, but not all of them have
     them turned on or sufficiently sized by default, especially systems
-    with BSD heritage. (For the <systemitem class="osname">QNX</> and
+    with BSD heritage. (For the <systemitem class="osname">Windows</>,
-    <systemitem class="osname">BeOS</> ports, <productname>PostgreSQL</>
+    <systemitem class="osname">QNX</> and <systemitem class="osname">BeOS</>
-    provides its own replacement implementation of these facilities.)
+    ports, <productname>PostgreSQL</> provides its own replacement
+    implementation of these facilities.)
    </para>
 
    <para>
@@ -4695,8 +4741,7 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
       <row>
        <entry><varname>SHMMAX</></>
        <entry>Maximum size of shared memory segment (bytes)</>
-       <entry>250 kB + 8.2 kB * <xref linkend="guc-shared-buffers"> +
+       <entry>at least several megabytes (see text)</entry>
-       14.2 kB * <xref linkend="guc-max-connections"> up to infinity</entry>
       </row>
 
       <row>
@@ -4764,14 +4809,17 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
     bytes, of a shared memory segment. If you get an error message from
     <function>shmget</> like <errorname>Invalid argument</>, it is
     likely that this limit has been exceeded. The size of the required
-    shared memory segment varies both with the number of requested
+    shared memory segment varies depending on several
-    buffers (<option>-B</> option) and the number of allowed connections
+    <productname>PostgreSQL</> configuration parameters, as shown in
-    (<option>-N</> option), although the former is the most significant.
+    <xref linkend="shared-memory-parameters">.
-    (You can, as a temporary solution, lower these settings to eliminate
+    You can, as a temporary solution, lower some of those settings to
-    the failure.) As a rough approximation, you can estimate the
+    avoid the failure.  As a rough approximation, you can estimate the
-    required segment size as suggested in <xref
+    required segment size as 500 kB plus the variable amounts shown in
-    linkend="sysvipc-parameters">.  Any error message you might get will
+    the table.  (Any error message you might get will include the exact
-    contain the size of the failed allocation request.
+    size of the failed allocation request.)  While it is possible to get
+    <productname>PostgreSQL</> to run with <varname>SHMMAX</> as small as
+    1 MB, you need at least 4 MB for acceptable performance, and desirable
+    settings are in the tens of megabytes.
    </para>
 
    <para>
@@ -4785,7 +4833,7 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
    <para>
     Less likely to cause problems is the minimum size for shared
     memory segments (<varname>SHMMIN</>), which should be at most
-    approximately 256 kB for <productname>PostgreSQL</> (it is
+    approximately 500 kB for <productname>PostgreSQL</> (it is
     usually just 1). The maximum number of segments system-wide
     (<varname>SHMMNI</>) or per-process (<varname>SHMSEG</>) are unlikely
     to cause a problem unless your system has them set to zero.
@@ -4793,8 +4841,8 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
 
    <para>
     <productname>PostgreSQL</> uses one semaphore per allowed connection
-    (<option>-N</> option), in sets of 16.  Each such set will also
+    (<xref linkend="guc-max-connections">), in sets of 16.  Each such set will
-    contain a 17th semaphore which contains a <quote>magic
+    also contain a 17th semaphore which contains a <quote>magic
     number</quote>, to detect collision with semaphore sets used by
     other applications. The maximum number of semaphores in the system
     is set by <varname>SEMMNS</>, which consequently must be at least
@@ -4834,6 +4882,7 @@ $ <userinput>postmaster -o '-S 1024 -s'</userinput>
     for <productname>PostgreSQL</>.
    </para>
 
+
     <variablelist>
 
      <varlistentry>
@@ -5172,6 +5221,59 @@ set semsys:seminfo_semmsl=32
      </varlistentry>
 
     </variablelist>
+
+
+   <table id="shared-memory-parameters">
+    <title>Configuration parameters affecting
+    <productname>PostgreSQL</productname>'s shared memory usage</>
+
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>Name</>
+       <entry>Approximate multiplier (bytes per increment)</>
+      </row>
+     </thead>
+
+     <tbody>
+      <row>
+       <entry><xref linkend="guc-max-connections"></>
+       <entry>400 (but see also <varname>max_locks_per_transaction</>)</entry>
+      </row>
+
+      <row>
+       <entry><xref linkend="guc-max-prepared-transactions"></>
+       <entry>600 (but see also <varname>max_locks_per_transaction</>)</entry>
+      </row>
+
+      <row>
+       <entry><xref linkend="guc-max-locks-per-transaction"></>
+       <entry>220 * (<xref linkend="guc-max-connections"> +
+        <xref linkend="guc-max-prepared-transactions">)</>
+      </row>
+
+      <row>
+       <entry><xref linkend="guc-shared-buffers"></>
+       <entry>8300</>
+      </row>
+
+      <row>
+       <entry><xref linkend="guc-wal-buffers"></>
+       <entry>8200</>
+      </row>
+
+      <row>
+       <entry><xref linkend="guc-max-fsm-relations"></>
+       <entry>70</>
+      </row>
+
+      <row>
+       <entry><xref linkend="guc-max-fsm-pages"></>
+       <entry>6</>
+      </row>
+     </tbody>
+    </tgroup>
+   </table>
   </sect2>
 
 

src/backend/utils/misc/postgresql.conf.sample

@@ -49,11 +49,10 @@
 #listen_addresses = 'localhost'		# what IP interface(s) to listen on; 
 					# defaults to localhost, '*' = any
 #port = 5432
-#max_connections = 100			# note: increasing max_connections costs
+#max_connections = 100
-					# about 500 bytes of shared memory per 
+# note: increasing max_connections costs ~400 bytes of shared memory per 
-					# connection slot, in addition to costs
+# connection slot, plus lock space (see max_locks_per_transaction).  You
-					# from shared_buffers and 
+# might also need to raise shared_buffers to support more connections.
-					# max_locks_per_transaction.
 #superuser_reserved_connections = 2
 #unix_socket_directory = ''
 #unix_socket_group = ''
@@ -91,6 +90,8 @@
 #shared_buffers = 1000			# min 16 or max_connections*2, 8KB each
 #temp_buffers = 1000			# min 100, 8KB each
 #max_prepared_transactions = 5		# can be 0 or more
+# note: increasing max_prepared_transactions costs ~600 bytes of shared memory
+# per transaction slot, plus lock space (see max_locks_per_transaction).
 #work_mem = 1024			# min 64, size in KB
 #maintenance_work_mem = 16384		# min 1024, size in KB
 #max_stack_depth = 2048			# min 100, size in KB
@@ -98,7 +99,7 @@
 # - Free Space Map -
 
 #max_fsm_pages = 20000			# min max_fsm_relations*16, 6 bytes each
-#max_fsm_relations = 1000		# min 100, ~50 bytes each
+#max_fsm_relations = 1000		# min 100, ~70 bytes each
 
 # - Kernel Resource Usage -
 
@@ -396,8 +397,10 @@
 #---------------------------------------------------------------------------
 
 #deadlock_timeout = 1000		# in milliseconds
-#max_locks_per_transaction = 64		# min 10, ~200*max_connections 
+#max_locks_per_transaction = 64		# min 10
-					# bytes each
+# note: each lock table slot uses ~220 bytes of shared memory, and there are
+# max_locks_per_transaction * (max_connections + max_prepared_transactions)
+# lock table slots.
 
 
 #---------------------------------------------------------------------------