Improvements to Maintenance and External Projects documentation.

Joshua D. Drake Robert Treat
19 years ago · 8d5f3c8d89
parent ffb62be07a
commit 8d5f3c8d89
2 changed files with 82 additions and 98 deletions
--- a/doc/src/sgml/external-projects.sgml
+++ b/doc/src/sgml/external-projects.sgml
@ -1,29 +1,34 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.10 2006/03/10 19:10:47 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.11 2006/08/01 00:09:06 momjian Exp $ -->

 <appendix id="external-projects">
-  <title>External Projects</title>
+  <title>PgFoundry and External Projects</title>

  <para>
   <productname>PostgreSQL</productname> is a complex software project,
-   and managing it is difficult. We have found that many
+   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. 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.
+   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>
-   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.
+   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,11 +41,10 @@
  <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.
+   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,64 +56,57 @@
     <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.
+       applications. <ulink url="http://odbc.postgresql.org/">Website.</ulink>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
-     <term>Npgsql</term>
+     <term>ODBCng</term>
     <listitem>
      <para>
-       <application>.Net</> interface for more recent
-       <application>Windows</> applications.
+       Another ODBC driver for PostgreSQL. 
+       <ulink url="http://projects.commandprompt.com/public/odbcng/">Website.</ulink>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
-     <term>libpqxx</term>
+     <term>pgjdbc</term>
     <listitem>
      <para>
-       A newer <application>C++</> interface.
+       A <application>JDBC</> interface.
+       <ulink url="http://jdbc.postgresql.org/">Website.</ulink>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
-     <term>libpq++</term>
+     <term>Npgsql</term>
     <listitem>
      <para>
-       An older <application>C++</> interface.
+       <application>.Net</> interface for more recent <application>mono/C#</> applications.
+       <ulink url="http://pgfoundry.org/projects/npgsql/">Website.</ulink>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
-     <term>pgperl</term>
+     <term>libpqxx</term>
     <listitem>
      <para>
-       A <application>Perl</> interface with an <acronym>API</> similar
-       to <application>libpq</>.
+       A newer <application>C++</> interface.
+       <ulink url="http://thaiopensource.org/development/libpqxx/">Website.</ulink>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
-     <term>DBD-Pg</term>
+     <term>DBD::Pg</term>
     <listitem>
      <para>
-       A <application>Perl</> interface that uses the
-       <acronym>DBD</>-standard <application>API</>.
+       A <application>Perl</> DBI driver for PostgreSQL.
+       <ulink url="http://search.cpan.org/dist/DBD-Pg/">Website.</ulink>
      </para>
     </listitem>
    </varlistentry>
@ -119,33 +116,21 @@
     <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>pgtcl</term>
-     <listitem>
-      <para>
-       The original version of the <application>Tcl</> interface.
-      </para>
-     </listitem>
-    </varlistentry>
-
-    <varlistentry>
-     <term>PyGreSQL</term>
+     <term>Pyscopg</term>
     <listitem>
      <para>
-       A <application>Python</> interface library.
+       A <application>Python</> interface library that is DB API 2.0 compliant.
+       <ulink url="http://www.initd.org/">Website.</ulink>
      </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>
@ -175,8 +160,8 @@
  <para>
   There are several administration tools available for
   <productname>PostgreSQL</>. The most popular is
-   <application>pgAdmin</>, and there are several commercially
-   available ones.
+   <application><ulink url="http://www.pgadmin.org/">pgAdmin III</ulink></>, 
+   and there are several commercially available ones as well.
  </para> 

 </sect1>
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/maintenance.sgml,v 1.56 2006/06/18 15:38:35 petere Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/maintenance.sgml,v 1.57 2006/08/01 00:09:06 momjian Exp $ -->

 <chapter id="maintenance">
 <title>Routine Database Maintenance Tasks</title>
@ -7,42 +7,40 @@
  <primary>maintenance</primary>
 </indexterm>

+ <indexterm zone="maintenance">
+  <primary>Routine 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.
+   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>
-   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">.
+   <productname>PostgreSQL</productname> is low-maintenance compared
+   to other database management systems. It is also fairly easy, provided
+   you read the documentation.
  </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">.
+   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 linkend="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>
-   Something else that might need periodic attention is log file management.
+   Another task that may 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>
@ -53,11 +51,11 @@

  <para>
   <productname>PostgreSQL</productname>'s <command>VACUUM</> command
-   must be run on a regular basis for several reasons:
+   <emphasis>must</emphasis> be run on a regular basis for several reasons:

    <orderedlist>
     <listitem>
-      <simpara>To recover disk space occupied by updated or deleted
+      <simpara>To recover or reuse disk space occupied by updated or deleted
      rows.</simpara>
     </listitem>

@ -82,11 +80,12 @@
  </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
+   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,9 +186,9 @@
   </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
+    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