X-Original-To: pgsql-docs-postgresql.org@localhost.postgresql.org
Received: from localhost (unknown [200.46.204.144])
	by svr1.postgresql.org (Postfix) with ESMTP id 2620C329E2E
	for <pgsql-docs-postgresql.org@localhost.postgresql.org>;
	Sun,  3 Oct 2004 00:15:49 +0100 (BST)
Received: from svr1.postgresql.org ([200.46.204.71])
	by localhost (av.hub.org [200.46.204.144]) (amavisd-new, port 10024)
	with ESMTP id 02159-08
	for <pgsql-docs-postgresql.org@localhost.postgresql.org>;
	Sat,  2 Oct 2004 23:15:42 +0000 (GMT)
Received: from davinci.ethosmedia.com (server226.ethosmedia.com
	[209.128.84.226])
	by svr1.postgresql.org (Postfix) with ESMTP id 92FCC329E17
	for <pgsql-docs@postgresql.org>; Sun,  3 Oct 2004 00:15:44 +0100 (BST)
Received: from [64.81.245.111] (account josh@agliodbs.com HELO
	temoku.sf.agliodbs.com)
	by davinci.ethosmedia.com (CommuniGate Pro SMTP 4.1.8)
	with ESMTP id 6449535 for pgsql-docs@postgresql.org;
	Sat, 02 Oct 2004 16:17:08 -0700
From: Josh Berkus <josh@agliodbs.com>
Reply-To: josh@agliodbs.com
Organization: Aglio Database Solutions
To: pgsql-docs@postgresql.org
Subject: Runtime patch, question for review
Date: Sat, 2 Oct 2004 16:17:26 -0700
User-Agent: KMail/1.6.2
MIME-Version: 1.0
Content-Disposition: inline
Content-Type: Multipart/Mixed;
  boundary="Boundary-00=_GczXBuaEL2XGrJn"
Message-Id: <200410021617.26194.josh@agliodbs.com>
X-Virus-Scanned: by amavisd-new at hub.org
X-Spam-Status: No, hits=0.0 tagged_above=0.0 required=5.0 tests=
X-Spam-Level: 
X-Archive-Number: 200410/7
X-Sequence-Number: 2576

--Boundary-00=_GczXBuaEL2XGrJn
Content-Type: text/plain;
  charset="us-ascii"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

Folks,

Attached is a patch for runtime.sgml.   It provides a long-needed (in my view) 
list of which runtime settings are most important to a first-time PG setup.  

I'm starting to go through the settings documentation to make them clearer to 
the novice.   Here's an example of what I plan to do to each entry:

     <varlistentry id="guc-effective-cache-size" 
xreflabel="effective_cache_size">
      <term><varname>effective_cache_size</varname> (<type>floating 
point</type>)</term>
      <listitem>
	<para>Default: 1000</para>
	<para>Set At: runtime (per connection)</para>
	<para>Unit: disk pages (typically 8192 bytes)</para>
       <para>Description: Sets the planner's assumption about the effective 
size of the
        disk cache (that is, the portion of the kernel's disk cache
        that will be used for <productname>PostgreSQL</productname>
        data files). 
       </para>
	<para>Recommendations: Set this to 3/4 of the available RAM on your
	 server (RAM not dedicated to other applications)</para>
      </listitem>
     </varlistentry>

While most of this data is already available in the text, I feel that breaking 
each dictionary entry out into 5 sections (Default, Set At, Unit/Options, 
Description, and Recommendations) greatly improves the readability of the 
file.

Are there any objections to this before I spend a lot of time on it?   Are the 
better tags I could use than a simple <para>?   One person suggested a 
segmentedlist, but I'm a bit reluctant to nest a segmentedlist inside a 
varlist.

-- 
--Josh

Josh Berkus
Aglio Database Solutions
San Francisco

--Boundary-00=_GczXBuaEL2XGrJn
Content-Type: text/x-diff;
  charset="us-ascii";
  name="runtime.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
	filename="runtime.patch"

Index: runtime.sgml
===================================================================
RCS file: /projects/cvsroot/pgsql-server/doc/src/sgml/runtime.sgml,v
retrieving revision 1.285
diff -c -r1.285 runtime.sgml
*** runtime.sgml	29 Sep 2004 06:27:11 -0000	1.285
--- runtime.sgml	2 Oct 2004 22:57:41 -0000
***************
*** 612,617 ****
--- 612,664 ----
       </variablelist>
     </sect2>
  
+    <sect2 id="runtime-config-common-modifications">
+     <title>Commonly Modified Configuration Options</title>
+     <para>Listed below, in the same order found in the file, are a list of the
+      most commonly modified configuration options by PostgreSQL
+      administrators.   When setting up your server, you may which to start with
+      these, and if you ignore them you will not get optimum performance from
+      your hardware.</para>
+     <itemizedlist>
+      <listitem>
+       <para>Connecting: listen_addresses, port, max_connections</para>
+      </listitem>
+     </itemizedlist>
+     <itemizedlist>
+      <listitem>
+       <para>Memory Usage: shared_buffers, work_mem</para>
+      </listitem>
+     </itemizedlist>
+     <itemizedlist>
+      <listitem>
+       <para>Database Maintenance: max_fsm_pages, vacuum_cost_delay</para>
+      </listitem>
+     </itemizedlist>
+     <itemizedlist>
+      <listitem>
+       <para>I/O Usage: bgwriter_percent, checkpoint_segments</para>
+      </listitem>
+     </itemizedlist>
+     <itemizedlist>
+      <listitem>
+       <para>Point In Time Recovery: archive_command</para>
+      </listitem>
+     </itemizedlist>
+     <itemizedlist>
+      <listitem>
+       <para>Query Planner Settings: effective_cache_size, random_page_cost</para>
+      </listitem>
+     </itemizedlist>
+     <itemizedlist>
+      <listitem>
+       <para>Logging: log_destination, plus supporting settings.</para>
+      </listitem>
+     </itemizedlist>
+     <para>Recommedations on how to set each parameter are in the setting text.</para> 
+ 
+    </sect2>
+ 
+ 
     <sect2 id="runtime-config-connection">
      <title>Connections and Authentication</title>
  

--Boundary-00=_GczXBuaEL2XGrJn--