X-Original-To: pgsql-docs-postgresql.org@postgresql.org
Received: from localhost (wm.hub.org [200.46.204.128])
	by postgresql.org (Postfix) with ESMTP id 633669FB40E;
	Sat, 15 Jul 2006 01:04:34 -0300 (ADT)
Received: from postgresql.org ([200.46.204.71])
	by localhost (mx1.hub.org [200.46.204.128]) (amavisd-new, port 10024)
	with ESMTP id 16408-04; Sat, 15 Jul 2006 04:04:24 +0000 (UTC)
X-Greylist: from auto-whitelisted by SQLgrey-
X-Greylist: from auto-whitelisted by SQLgrey-
Received: from eastrmmtao01.cox.net (eastrmmtao01.cox.net [68.230.240.38])
	by postgresql.org (Postfix) with ESMTP id 902BF9FB6DA;
	Fri, 14 Jul 2006 23:26:04 -0300 (ADT)
Received: from [192.168.0.9] (really [24.250.222.197]) by eastrmmtao01.cox.net
	(InterMail vM.6.01.06.01 201-2131-130-101-20060113) with ESMTP
	id <20060715022602.TPQY12077.eastrmmtao01.cox.net@[192.168.0.9]>;
	Fri, 14 Jul 2006 22:26:02 -0400
From: Robert Treat <xzilla@users.sourceforge.net>
To: "Joshua D. Drake" <jd@commandprompt.com>
Subject: Re: Maintenance and External Projects (try 2)
Date: Fri, 14 Jul 2006 22:26:00 -0400
User-Agent: KMail/1.9.1
Cc: Tom Lane <tgl@sss.pgh.pa.us>, pgsql-docs@postgresql.org,
	PostgreSQL-patches <pgsql-patches@postgresql.org>
References: <44B6EC25.7000708@commandprompt.com>
	<3365.1152902276@sss.pgh.pa.us>
	<44B7EF29.5080302@commandprompt.com>
In-Reply-To: <44B7EF29.5080302@commandprompt.com>
MIME-Version: 1.0
Content-Type: Multipart/Mixed;
  boundary="Boundary-00=_4IFuEAO6N3+eaC2"
Message-Id: <200607142226.00900.xzilla@users.sourceforge.net>
X-Virus-Scanned: Maia Mailguard 1.0.1
X-Archive-Number: 200607/8
X-Sequence-Number: 3598

--Boundary-00=_4IFuEAO6N3+eaC2
Content-Type: text/plain;
  charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

On Friday 14 July 2006 15:23, Joshua D. Drake wrote:
> Tom Lane wrote:
> > "Joshua D. Drake" <jd@commandprompt.com> writes:
> >> Please let me know if there is anything else you would like me to do or
> >> add.
> >
> > A round of copy-editing seems indicated, at least.
>
> Oh, no doubt. I tried to fix as much as I find, including a bunch of
> stuff already there. However, I do not claim, in any way to be an editor.
>

The following patches provide some editorializing for Joshua's patches. 

-- 
Robert Treat
Build A Brighter LAMP :: Linux Apache {middleware} PostgreSQL

--Boundary-00=_4IFuEAO6N3+eaC2
Content-Type: text/x-diff; charset="iso-8859-1";
	name="rht.external-projects.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
	filename="rht.external-projects.patch"

Index: doc/src/sgml/external-projects.sgml
===================================================================
RCS file: /projects/cvsroot/pgsql/doc/src/sgml/external-projects.sgml,v
retrieving revision 1.10
diff -c -r1.10 external-projects.sgml
*** doc/src/sgml/external-projects.sgml	10 Mar 2006 19:10:47 -0000	1.10
--- doc/src/sgml/external-projects.sgml	15 Jul 2006 02:22:02 -0000
***************
*** 1,29 ****
  <!-- $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.10 2006/03/10 19:10:47 momjian Exp $ -->
  
   <appendix id="external-projects">
!   <title>External Projects</title>
  
    <para>
     <productname>PostgreSQL</productname> is a complex software project,
!    and managing it is difficult. We have found that many
     enhancements to <productname>PostgreSQL</productname> can be more
!    efficiently developed separately from the core project. Separate
!    projects can
!    have their own developer teams, email lists, bug tracking,
!    and release schedules. While their independence makes
!    development easier, it makes users' jobs harder. They have to hunt
!    around looking for database enhancements to meet their needs.
!    This section describes some of the more popular externally
!    developed enhancements and guides you on how to find them.
    </para>
  
    <para>
!    Many <productname>PostgreSQL</productname>-related projects are
!    hosted at either 
!    <ulink url="http://gborg.postgresql.org"><productname>GBorg</></ulink>
!    or <ulink url="http://pgfoundry.org"><productname>pgFoundry</></ulink>.
!    There are other <productname>PostgreSQL</productname>-related projects that are hosted
!    elsewhere, but you will have to do an Internet search to find them.
    </para>
  
   <sect1 id="external-interfaces">
--- 1,34 ----
  <!-- $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.10 2006/03/10 19:10:47 momjian Exp $ -->
  
   <appendix id="external-projects">
!   <title>PgFoundry and External Projects</title>
  
    <para>
     <productname>PostgreSQL</productname> is a complex software project,
!    and managing the project is difficult. We have found that many
     enhancements to <productname>PostgreSQL</productname> can be more
!    efficiently developed separately from the core project. 
!   </para>
!   
!   <para>
!    To help our community with the development of their external projects,
!    we have created the <ulink url="http://www.pgfoundry.org/">PgFoundry</ulink>.
!    <ulink url="http://www.pgfoundry.org/">PgFoundry</ulink> is built using the
!    GForge software project and is similar to SourceForge in its feature set. If
!    you have a PostgreSQL related Open Source project that you would like to 
!    develop and need project management resources such as mailing lists, forums,
!    bug tracking, and CVS, please feel free to create a new project.   
    </para>
  
    <para>
!    Secondly, many <productname>PostgreSQL</productname>-related projects are
!    still hosted at <ulink url="http://gborg.postgresql.org"><productname>GBorg</></ulink>. 
!    GBorg is the original external community developer site, and while it is 
!    currently closed to new projects in favor of PgFoundry, it still contains 
!    many active and relevant projects. There are other popular <productname>PostgreSQL</productname> 
!    related projects that are hosted independently as well at other community 
!    sites such as <ulink url="http://www.sf.net">SourceForge</ulink>. You should 
!    google if you don't find the project you are looking for.
    </para>
  
   <sect1 id="external-interfaces">
***************
*** 36,46 ****
    <para>
     <productname>PostgreSQL</productname> includes very few interfaces
     with the base distribution. <application>libpq</> is packaged because
!    it is the primary <application>C</> interface and many other
!    interfaces are built on top of it. <application>ecpg</> is packaged
!    because it is tied to the server-side grammar so is very dependent
!    on the database version. All the other interfaces are independent
!    projects and must be installed separately.
    </para>
  
    <para>
--- 41,50 ----
    <para>
     <productname>PostgreSQL</productname> includes very few interfaces
     with the base distribution. <application>libpq</> is packaged because
!    it is the primary dependecy of most interfaces available to PostgreSQL.
!    We also package <application>ecpg</> because it is tied to the 
!    server-side grammar. All other interfaces, such as PHP, Perl, Python,
!    and Ruby, are external projects.
    </para>
  
    <para>
***************
*** 52,115 ****
       <listitem>
        <para>
         This is the most common interface for <application>Windows</>
!        applications.
!       </para>
!      </listitem>
!     </varlistentry>
! 
!     <varlistentry>
!      <term>pgjdbc</term>
!      <listitem>
!       <para>
!        A <application>JDBC</> interface.
        </para>
       </listitem>
      </varlistentry>
  
      <varlistentry>
!      <term>Npgsql</term>
       <listitem>
        <para>
!        <application>.Net</> interface for more recent
!        <application>Windows</> applications.
        </para>
       </listitem>
      </varlistentry>
  
      <varlistentry>
!      <term>libpqxx</term>
       <listitem>
        <para>
!        A newer <application>C++</> interface.
        </para>
       </listitem>
      </varlistentry>
  
      <varlistentry>
!      <term>libpq++</term>
       <listitem>
        <para>
!        An older <application>C++</> interface.
        </para>
       </listitem>
      </varlistentry>
  
      <varlistentry>
!      <term>pgperl</term>
       <listitem>
        <para>
!        A <application>Perl</> interface with an <acronym>API</> similar
!        to <application>libpq</>.
        </para>
       </listitem>
      </varlistentry>
  
      <varlistentry>
!      <term>DBD-Pg</term>
       <listitem>
        <para>
!        A <application>Perl</> interface that uses the
!        <acronym>DBD</>-standard <application>API</>.
        </para>
       </listitem>
      </varlistentry>
--- 56,112 ----
       <listitem>
        <para>
         This is the most common interface for <application>Windows</>
!        applications. <ulink url="http://odbc.postgresql.org/">Website.</ulink>
        </para>
       </listitem>
      </varlistentry>
  
      <varlistentry>
!      <term>ODBCng</term>
       <listitem>
        <para>
!        Another ODBC driver for PostgreSQL. 
!        <ulink url="http://projects.commandprompt.com/public/odbcng/">Website.</ulink>
        </para>
       </listitem>
      </varlistentry>
  
      <varlistentry>
!      <term>pgjdbc</term>
       <listitem>
        <para>
!        A <application>JDBC</> interface.
!        <ulink url="http://jdbc.postgresql.org/">Website.</ulink>
        </para>
       </listitem>
      </varlistentry>
  
      <varlistentry>
!      <term>Npgsql</term>
       <listitem>
        <para>
!        <application>.Net</> interface for more recent <application>mono/C#</> applications.
!        <ulink url="http://pgfoundry.org/projects/npgsql/">Website.</ulink>
        </para>
       </listitem>
      </varlistentry>
  
      <varlistentry>
!      <term>libpqxx</term>
       <listitem>
        <para>
!        A newer <application>C++</> interface.
!        <ulink url="http://thaiopensource.org/development/libpqxx/">Website.</ulink>
        </para>
       </listitem>
      </varlistentry>
  
      <varlistentry>
!      <term>DBD::Pg</term>
       <listitem>
        <para>
!        A <application>Perl</> DBI driver for PostgreSQL.
!        <ulink url="http://search.cpan.org/dist/DBD-Pg/">Website.</ulink>
        </para>
       </listitem>
      </varlistentry>
***************
*** 119,151 ****
       <listitem>
        <para>
         A newer version of the <application>Tcl</> interface.
        </para>
       </listitem>
      </varlistentry>
  
      <varlistentry>
!      <term>pgtcl</term>
!      <listitem>
!       <para>
!        The original version of the <application>Tcl</> interface.
!       </para>
!      </listitem>
!     </varlistentry>
! 
!     <varlistentry>
!      <term>PyGreSQL</term>
       <listitem>
        <para>
!        A <application>Python</> interface library.
        </para>
       </listitem>
      </varlistentry>
- 
     </variablelist>
- 
-    All of these can be found at
-    <ulink url="http://gborg.postgresql.org"><productname>GBorg</></ulink>
-    or <ulink url="http://pgfoundry.org"><productname>pgFoundry</></ulink>.
     </para>
  
   </sect1>
--- 116,136 ----
       <listitem>
        <para>
         A newer version of the <application>Tcl</> interface.
+        <ulink url="http://gborg.postgresql.org/project/pgtclng/projdisplay.php">Website.</ulink>
        </para>
       </listitem>
      </varlistentry>
  
      <varlistentry>
!      <term>Pyscopg</term>
       <listitem>
        <para>
!        A <application>Python</> interface library that is DB API 2.0 compliant.
!        <ulink url="http://www.initd.org/">Website.</ulink>
        </para>
       </listitem>
      </varlistentry>
     </variablelist>
     </para>
  
   </sect1>
***************
*** 175,182 ****
    <para>
     There are several administration tools available for
     <productname>PostgreSQL</>. The most popular is
!    <application>pgAdmin</>, and there are several commercially
!    available ones.
    </para> 
  
   </sect1>
--- 160,167 ----
    <para>
     There are several administration tools available for
     <productname>PostgreSQL</>. The most popular is
!    <application><ulink url="http://www.pgadmin.org/">pgAdmin III</ulink></>, 
!    and there are several commercially available ones as well.
    </para> 
  
   </sect1>

--Boundary-00=_4IFuEAO6N3+eaC2
Content-Type: text/x-diff; charset="iso-8859-1"; name="rht.maintenance.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
	filename="rht.maintenance.patch"

Index: doc/src/sgml/maintenance.sgml
===================================================================
RCS file: /projects/cvsroot/pgsql/doc/src/sgml/maintenance.sgml,v
retrieving revision 1.56
diff -c -r1.56 maintenance.sgml
*** doc/src/sgml/maintenance.sgml	18 Jun 2006 15:38:35 -0000	1.56
--- doc/src/sgml/maintenance.sgml	15 Jul 2006 02:21:25 -0000
***************
*** 7,48 ****
    <primary>maintenance</primary>
   </indexterm>
  
    <para>
!    There are a few routine maintenance chores that must be performed on
!    a regular basis to keep a <productname>PostgreSQL</productname>
!    server running smoothly.  The tasks discussed here are repetitive
!    in nature and can easily be automated using standard Unix tools such
!    as <application>cron</application> scripts.  But it is the database
!    administrator's responsibility to set up appropriate scripts, and to
!    check that they execute successfully.
    </para>
! 
    <para>
!    One obvious maintenance task is creation of backup copies of the data on a
!    regular schedule.  Without a recent backup, you have no chance of recovery
!    after a catastrophe (disk failure, fire, mistakenly dropping a critical
!    table, etc.).  The backup and recovery mechanisms available in
!    <productname>PostgreSQL</productname> are discussed at length in
!    <xref linkend="backup">.
    </para>
  
    <para>
!    The other main category of maintenance task is periodic <quote>vacuuming</>
!    of the database.  This activity is discussed in
!    <xref linkend="routine-vacuuming">.
    </para>
  
    <para>
!    Something else that might need periodic attention is log file management.
     This is discussed in <xref linkend="logfile-maintenance">.
    </para>
  
!   <para>
!    <productname>PostgreSQL</productname> is low-maintenance compared
!    to some other database management systems.  Nonetheless,
!    appropriate attention to these tasks will go far towards ensuring a
!    pleasant and productive experience with the system.
!   </para>
  
   <sect1 id="routine-vacuuming">
    <title>Routine Vacuuming</title>
--- 7,46 ----
    <primary>maintenance</primary>
   </indexterm>
  
+  <indexterm zone="maintenance">
+   <primary>Routine maintenance</primary>
+  </indexterm>
+ 
    <para>
!    PostgreSQL, like any database software, requires that certain tasks
!    be performed regularly to achieve optimum performance. The tasks 
!    discussed here are <emphasis>required</emphasis>, but they
!    are repetitive in nature and can easily be automated using standard 
!    Unix tools such as <application>cron</application> scripts.  
    </para>
!   
    <para>
!    <productname>PostgreSQL</productname> is low-maintenance compared
!    to other database management systems. It is also fairly easy, provided
!    you read the documentation.
    </para>
  
    <para>
!    There are three tasks that <emphasis>must</emphasis> be performed on 
!    a periodic basis. The first is backups. If you do not have a current backup
!    and your system experiences a catastrophic failure, you will lose your data.
!    You can read further about backups procedures in <xref linked="backup">. 
!    The second is vacuum which is discussed in <xref linkend="routine-vacuuming">. 
!    The third is to update the planner statistics using the analyze command as 
!    discussed in <xref linkend="vacuum-for-statistics">.
    </para>
  
    <para>
!    Another task that may need periodic attention is log file management.
     This is discussed in <xref linkend="logfile-maintenance">.
    </para>
  
!   
  
   <sect1 id="routine-vacuuming">
    <title>Routine Vacuuming</title>
***************
*** 53,63 ****
  
    <para>
     <productname>PostgreSQL</productname>'s <command>VACUUM</> command
!    must be run on a regular basis for several reasons:
  
      <orderedlist>
       <listitem>
!       <simpara>To recover disk space occupied by updated or deleted
        rows.</simpara>
       </listitem>
  
--- 51,61 ----
  
    <para>
     <productname>PostgreSQL</productname>'s <command>VACUUM</> command
!    <emphasis>must</emphasis> be run on a regular basis for several reasons:
  
      <orderedlist>
       <listitem>
!       <simpara>To recover or reuse disk space occupied by updated or deleted
        rows.</simpara>
       </listitem>
  
***************
*** 82,92 ****
    </para>
  
    <para>
!    The standard form of <command>VACUUM</> can run in parallel with 
!    normal database operations (SELECTs, INSERTs, UPDATEs, DELETEs, but not 
!    changes to table definitions).
!    Beginning in <productname>PostgreSQL</productname> 8.0, there are
!    configuration parameters that can be adjusted to further reduce the
     performance impact of background vacuuming.  See
     <xref linkend="runtime-config-resource-vacuum-cost">.
    </para>
--- 80,91 ----
    </para>
  
    <para>
!    The standard form of <command>VACUUM</> does not intefere with production
!    database operations. Items such as SELECTS, INSERTS, UPDATES and DELETES
!    will continue to function as normal, though you will not be able to modify the
!    definition (Such as ALTER TABLE ADD COLUMN) of a table while it is being vacuumed.
!    The release of <productname>PostgreSQL</productname> 8.0, introduced new
!    configuration parameters to further reduce the potentially negative 
     performance impact of background vacuuming.  See
     <xref linkend="runtime-config-resource-vacuum-cost">.
    </para>
***************
*** 187,195 ****
     </para>
  
     <para>
!     If you have a table whose contents are deleted on a periodic
!     basis, consider doing it with <command>TRUNCATE</command> rather
!     than using <command>DELETE</command> followed by
      <command>VACUUM</command>. <command>TRUNCATE</command> removes the
      entire content of the table immediately, without requiring a
      subsequent <command>VACUUM</command> or <command>VACUUM
--- 186,194 ----
     </para>
  
     <para>
!     If you have a table whose entire contents are deleted on a periodic
!     basis, consider doing it with the <command>TRUNCATE</command> rather
!     than using the <command>DELETE</command> followed by
      <command>VACUUM</command>. <command>TRUNCATE</command> removes the
      entire content of the table immediately, without requiring a
      subsequent <command>VACUUM</command> or <command>VACUUM

--Boundary-00=_4IFuEAO6N3+eaC2--