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
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>
---------------------------(end of broadcast)---------------------------
TIP 1: subscribe and unsubscribe commands go to [EMAIL PROTECTED]
