From 8d5f3c8d89bd108d65bb43fc61a76d8c827bc9d5 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Tue, 1 Aug 2006 00:09:06 +0000
Subject: [PATCH] Improvements to Maintenance and External Projects
documentation.
Joshua D. Drake
Robert Treat
---
doc/src/sgml/external-projects.sgml | 111 ++++++++++++----------------
doc/src/sgml/maintenance.sgml | 69 +++++++++--------
2 files changed, 82 insertions(+), 98 deletions(-)
diff --git a/doc/src/sgml/external-projects.sgml b/doc/src/sgml/external-projects.sgml
index f649de386d1..23d67b44ced 100644
--- 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>
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 784b21bb5c6..1576d72dd47 100644
--- 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
--
GitLab