mirrors
/
postgres
mirror of https://github.com/postgres/postgres
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

More minor updates and copy-editing.

This commit is contained in:
Tom Lane 2004-12-28 19:08:58 +00:00
parent 31cc047d94
commit 7737d01ece
4 changed files with 113 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

128
doc/src/sgml/backup.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.53 2004/12/13 18:05:07 petere Exp $
$PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.54 2004/12/28 19:08:58 tgl Exp $
-->
<chapter id="backup">
<title>Backup and Restore</title>
@ -7,7 +7,7 @@ $PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.53 2004/12/13 18:05:07 petere Ex
<indexterm zone="backup"><primary>backup</></>
<para>
As everything that contains valuable data, <productname>PostgreSQL</>
As with everything that contains valuable data, <productname>PostgreSQL</>
databases should be backed up regularly. While the procedure is
essentially simple, it is important to have a basic understanding of
the underlying techniques and assumptions.
@ -46,9 +46,9 @@ pg_dump <replaceable class="parameter">dbname</replaceable> &gt; <replaceable cl
client application (albeit a particularly clever one). This means
that you can do this backup procedure from any remote host that has
access to the database. But remember that <application>pg_dump</>
does not operate with special permissions. In particular, you must
does not operate with special permissions. In particular, it must
have read access to all tables that you want to back up, so in
practice you almost always have to be a database superuser.
practice you almost always have to run it as a database superuser.
</para>
<para>
@ -111,26 +111,25 @@ psql <replaceable class="parameter">dbname</replaceable> &lt; <replaceable class
command, you must create it yourself from <literal>template0</> before executing
<application>psql</> (e.g., with <literal>createdb -T template0
<replaceable class="parameter">dbname</></literal>).
<application>psql</> supports similar options to <application>pg_dump</>
<application>psql</> supports options similar to <application>pg_dump</>
for controlling the database server location and the user name. See
its reference page for more information.
<xref linkend="app-psql">'s reference page for more information.
</para>
<para>
If the objects in the original database were owned by different
users, then the dump will instruct <application>psql</> to connect
as each affected user in turn and then create the relevant
objects. This way the original ownership is preserved. This also
means, however, that all these users must already exist, and
furthermore that you must be allowed to connect as each of them.
It might therefore be necessary to temporarily relax the client
authentication settings.
Not only must the target database already exist before starting to
run the restore, but so must all the users who own objects in the
dumped database or were granted permissions on the objects. If they
do not, then the restore will fail to recreate the objects with the
original ownership and/or permissions. (Sometimes this is what you want,
but usually it is not.)
</para>
<para>
Once restored, it is wise to run <xref linkend="sql-analyze"
endterm="sql-analyze-title"> on each database so the optimizer has
useful statistics. You can also run <command>vacuumdb -a -z</> to
useful statistics. An easy way to do this is to run
<command>vacuumdb -a -z</> to
<command>VACUUM ANALYZE</> all databases; this is equivalent to
running <command>VACUUM ANALYZE</command> manually.
</para>
@ -189,7 +188,7 @@ psql template1 &lt; <replaceable class="parameter">infile</replaceable>
</sect2>
<sect2 id="backup-dump-large">
<title>Large Databases</title>
<title>Handling large databases</title>
<para>
Since <productname>PostgreSQL</productname> allows tables larger
@ -249,17 +248,19 @@ cat <replaceable class="parameter">filename</replaceable>* | psql <replaceable c
<formalpara>
<title>Use the custom dump format.</title>
<para>
If <productname>PostgreSQL</productname> was built on a system with the <application>zlib</> compression library
installed, the custom dump format will compress data as it writes it
to the output file. For large databases, this will produce similar dump
sizes to using <command>gzip</command>, but has the added advantage that the tables can be
restored selectively. The following command dumps a database using the
custom dump format:
If <productname>PostgreSQL</productname> was built on a system with the
<application>zlib</> compression library installed, the custom dump
format will compress data as it writes it to the output file. This will
produce dump file sizes similar to using <command>gzip</command>, but it
has the added advantage that tables can be restored selectively. The
following command dumps a database using the custom dump format:
<programlisting>
pg_dump -Fc <replaceable class="parameter">dbname</replaceable> > <replaceable class="parameter">filename</replaceable>
</programlisting>
A custom-format dump is not a script for <application>psql</>, but
instead must be restored with <application>pg_restore</>.
See the <xref linkend="app-pgdump"> and <xref
linkend="app-pgrestore"> reference pages for details.
</para>
@ -276,7 +277,8 @@ pg_dump -Fc <replaceable class="parameter">dbname</replaceable> > <replaceable c
object</primary><secondary>backup</secondary></indexterm> To dump
large objects you must use either the custom or the tar output
format, and use the <option>-b</> option in
<application>pg_dump</>. See the reference pages for details. The
<application>pg_dump</>. See the <xref linkend="app-pgdump"> reference
page for details. The
directory <filename>contrib/pg_dumplo</> of the
<productname>PostgreSQL</> source tree also contains a program
that can dump large objects.
@ -366,7 +368,9 @@ tar -cf backup.tar /usr/local/pgsql/data
data files and WAL log on different disks) there may not be any way
to obtain exactly-simultaneous frozen snapshots of all the volumes.
Read your file system documentation very carefully before trusting
to the consistent-snapshot technique in such situations.
to the consistent-snapshot technique in such situations. The safest
approach is to shut down the database server for long enough to
establish all the frozen snapshots.
</para>
<para>
@ -616,9 +620,12 @@ archive_command = 'test ! -f .../%f &amp;&amp; cp %p .../%f'
modifications made to the data in your <productname>PostgreSQL</> database
it will not restore changes made to configuration files (that is,
<filename>postgresql.conf</>, <filename>pg_hba.conf</> and
<filename>pg_ident.conf</>) after the initial base backup.
<filename>pg_ident.conf</>), since those are edited manually rather
than through SQL operations.
You may wish to keep the configuration files in a location that will
be backed up by your regular file system backup procedures.
be backed up by your regular file system backup procedures. See
<xref linkend="runtime-config-file-locations"> for how to relocate the
configuration files.
</para>
</sect2>
@ -930,8 +937,8 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
in the command.
</para>
<para>
It is important for the command to return a zero exit status only
if it succeeds. The command <emphasis>will</> be asked for file
It is important for the command to return a zero exit status if and
only if it succeeds. The command <emphasis>will</> be asked for file
names that are not present in the archive; it must return nonzero
when so asked. Examples:
<programlisting>
@ -1083,7 +1090,7 @@ restore_command = 'copy /mnt/server/archivedir/%f "%p"' # Windows
that was current when the base backup was taken. If you want to recover
into some child timeline (that is, you want to return to some state that
was itself generated after a recovery attempt), you need to specify the
target timeline in <filename>recovery.conf</>. You cannot recover into
target timeline ID in <filename>recovery.conf</>. You cannot recover into
timelines that branched off earlier than the base backup.
</para>
</sect2>
@ -1131,6 +1138,13 @@ restore_command = 'copy /mnt/server/archivedir/%f "%p"' # Windows
<secondary>compatibility</secondary>
</indexterm>
<para>
This section discusses how to migrate your database data from one
<productname>PostgreSQL</> release to a newer one.
The software installation procedure <foreignphrase>per se</> is not the
subject of this section; those details are in <xref linkend="installation">.
</para>
<para>
As a general rule, the internal data storage format is subject to
change between major releases of <productname>PostgreSQL</> (where
@ -1140,17 +1154,21 @@ restore_command = 'copy /mnt/server/archivedir/%f "%p"' # Windows
storage formats. For example, releases 7.0.1, 7.1.2, and 7.2 are
not compatible, whereas 7.1.1 and 7.1.2 are. When you update
between compatible versions, you can simply replace the executables
and reuse the data area on disk. Otherwise you need to <quote>back
up</> your data and <quote>restore</> it on the new server, using
<application>pg_dump</>. There are checks in place that prevent you
from using a data area with an incompatible version of
<productname>PostgreSQL</productname>, so no harm can be done by
confusing these things. It is recommended that you use the
<application>pg_dump</> program from the newer version of
<productname>PostgreSQL</> to take advantage of any enhancements in
<application>pg_dump</> that may have been made. The precise
installation procedure is not the subject of this section; those
details are in <xref linkend="installation">.
and reuse the data directory on disk. Otherwise you need to back
up your data and restore it on the new server. This has to be done
using <application>pg_dump</>; file system level backup methods
obviously won't work. There are checks in place that prevent you
from using a data directory with an incompatible version of
<productname>PostgreSQL</productname>, so no great harm can be done by
trying to start the wrong server version on a data directory.
</para>
<para>
It is recommended that you use the <application>pg_dump</> and
<application>pg_dumpall</> programs from the newer version of
<productname>PostgreSQL</>, to take advantage of any enhancements
that may have been made in these programs. Current releases of the
dump programs can read data from any server version back to 7.0.
</para>
<para>
@ -1165,11 +1183,17 @@ pg_dumpall -p 5432 | psql -d template1 -p 6543
to transfer your data. Or use an intermediate file if you want.
Then you can shut down the old server and start the new server at
the port the old one was running at. You should make sure that the
database is not updated after you run <application>pg_dumpall</>,
old database is not updated after you run <application>pg_dumpall</>,
otherwise you will obviously lose that data. See <xref
linkend="client-authentication"> for information on how to prohibit
access. In practice you probably want to test your client
applications on the new setup before switching over.
access.
</para>
<para>
In practice you probably want to test your client
applications on the new setup before switching over completely.
This is another reason for setting up concurrent installations
of old and new versions.
</para>
<para>
@ -1194,22 +1218,16 @@ psql template1 < backup
you of strategic places to perform these steps.
</para>
<para>
You will always need a SQL dump (<application>pg_dump</> dump) for
migrating to a new release. File-system-level backups (including
on-line backups) will not work, for the same reason that you can't
just do the update in-place: the file formats won't necessarily be
compatible across major releases.
</para>
<note>
<para>
When you <quote>move the old installation out of the way</quote>
it is no longer perfectly usable. Some parts of the installation
contain information about where the other parts are located. This
is usually not a big problem but if you plan on using two
it may no longer be perfectly usable. Some of the executable programs
contain absolute paths to various installed programs and data files.
This is usually not a big problem but if you plan on using two
installations in parallel for a while you should assign them
different installation directories at build time.
different installation directories at build time. (This problem
is rectified in <productname>PostgreSQL</> 8.0 and later, but you
need to be wary of moving older installations.)
</para>
</note>
</sect1>

14
doc/src/sgml/diskusage.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/diskusage.sgml,v 1.12 2004/12/01 19:00:27 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/diskusage.sgml,v 1.13 2004/12/28 19:08:58 tgl Exp $
-->
<chapter id="diskusage">
@ -24,7 +24,10 @@ $PostgreSQL: pgsql/doc/src/sgml/diskusage.sgml,v 1.12 2004/12/01 19:00:27 tgl Ex
which is used to store values too wide to fit comfortably in the main
table. There will be one index on the
<acronym>TOAST</> table, if present. There may also be indexes associated
with the base table.
with the base table. Each table and index is stored in a separate disk
file &mdash; possibly more than one file, if the file would exceed one
gigabyte. Naming conventions for these files are described in <xref
linkend="file-layout">.
</para>
<para>
@ -135,6 +138,13 @@ SELECT relname, relpages FROM pg_class ORDER BY relpages DESC;
not wait until the disk is completely full to take action.
</para>
</tip>
<para>
If your system supports per-user disk quotas, then the database
will naturally be subject to whatever quota is placed on the user
the server runs as. Exceeding the quota will have the same bad
effects as running out of space entirely.
</para>
</sect1>
</chapter>

26
doc/src/sgml/monitoring.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.26 2004/03/26 03:18:28 neilc Exp $
$PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.27 2004/12/28 19:08:58 tgl Exp $
-->
<chapter id="monitoring">
@ -26,7 +26,8 @@ $PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.26 2004/03/26 03:18:28 neilc
analyzing performance. Most of this chapter is devoted to describing
<productname>PostgreSQL</productname>'s statistics collector,
but one should not neglect regular Unix monitoring programs such as
<command>ps</> and <command>top</>. Also, once one has identified a
<command>ps</>, <command>top</>, <command>iostat</>, and <command>vmstat</>.
Also, once one has identified a
poorly-performing query, further investigation may be needed using
<productname>PostgreSQL</productname>'s <xref linkend="sql-explain"
endterm="sql-explain-title"> command.
@ -172,25 +173,28 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<title>Viewing Collected Statistics</Title>
<para>
Several predefined views are available to show the results of
statistics collection, listed in <xref
linkend="monitoring-stats-views-table">. Alternatively, one can
Several predefined views, listed in <xref
linkend="monitoring-stats-views-table">, are available to show the results
of statistics collection. Alternatively, one can
build custom views using the underlying statistics functions.
</para>
<para>
When using the statistics to monitor current activity, it is important
to realize that the information does not update instantaneously.
Each individual server process transmits new access counts to the collector
just before waiting for another client command; so a query still in
Each individual server process transmits new block and row access counts to
the collector just before going idle; so a query or transaction still in
progress does not affect the displayed totals. Also, the collector itself
emits new totals at most once per <varname>pgstat_stat_interval</varname> milliseconds
(500 by default). So the displayed totals lag behind actual activity.
emits a new report at most once per <varname>pgstat_stat_interval</varname>
milliseconds (500 by default). So the displayed information lags behind
actual activity. Current-query information is reported to the collector
immediately, but is still subject to the
<varname>pgstat_stat_interval</varname> delay before it becomes visible.
</para>
<para>
Another important point is that when a server process is asked to display
any of these statistics, it first fetches the most recent totals emitted by
any of these statistics, it first fetches the most recent report emitted by
the collector process and then continues to use this snapshot for all
statistical views and functions until the end of its current transaction.
So the statistics will appear not to change as long as you continue the
@ -614,7 +618,7 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS procpid,
database administrator to view information about the outstanding
locks in the lock manager. For example, this capability can be used
to:
<itemizedlist>
<listitem>
<para>

23
doc/src/sgml/regress.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/regress.sgml,v 1.44 2004/12/03 17:46:19 tgl Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/regress.sgml,v 1.45 2004/12/28 19:08:58 tgl Exp $ -->
<chapter id="regress">
<title id="regress-title">Regression Tests</title>
@ -15,16 +15,14 @@
The regression tests are a comprehensive set of tests for the SQL
implementation in <productname>PostgreSQL</productname>. They test
standard SQL operations as well as the extended capabilities of
<productname>PostgreSQL</productname>. From
<productname>PostgreSQL</productname> 6.1 onward, the regression
tests are current for every official release.
<productname>PostgreSQL</productname>.
</para>
<sect1 id="regress-run">
<title>Running the Tests</title>
<para>
The regression test can be run against an already installed and
The regression tests can be run against an already installed and
running server, or using a temporary installation within the build
tree. Furthermore, there is a <quote>parallel</quote> and a
<quote>sequential</quote> mode for running the tests. The
@ -51,12 +49,13 @@ gmake check
<screen>
<computeroutput>
======================
All 93 tests passed.
All 96 tests passed.
======================
</computeroutput>
</screen>
or otherwise a note about which tests failed. See <xref
linkend="regress-evaluation"> below for more.
linkend="regress-evaluation"> below before assuming that a
<quote>failure</> represents a serious problem.
</para>
<para>
@ -130,10 +129,14 @@ gmake SHELL=/bin/ksh check
server, <![%standalone-ignore;[as explained in <xref linkend="runtime">, ]]> then type
<screen>
gmake installcheck
</screen>
or for a parallel test
<screen>
gmake installcheck-parallel
</screen>
The tests will expect to contact the server at the local host and the
default port number, unless directed otherwise by <envar>PGHOST</envar> and <envar>PGPORT</envar>
environment variables.
default port number, unless directed otherwise by <envar>PGHOST</envar> and
<envar>PGPORT</envar> environment variables.
</para>
</sect1>
@ -323,7 +326,7 @@ exclusion of those that don't.
diff results/random.out expected/random.out
</programlisting>
should produce only one or a few lines of differences. You need
not worry unless the random test repeatedly fails.
not worry unless the random test fails repeatedly.
</para>
</sect2>
</sect1>