upgrade docs: highlight pg_upgrade, warn about globals preservation

Also, remove OID preservation mention, mention non-text dump formats

Backpatch through 9.4

diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 06f064e1a6f7db4a01a42482090052187fd95631..07ca0dc62d6c071647bc414875a36b65e236c394 100644 (file)
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -28,7 +28,7 @@
   <acronym>SQL</> Dump
 
   
-   The idea behind this dump method is to generate a text file with SQL
+   The idea behind this dump method is to generate a file with SQL
    commands that, when fed back to the server, will recreate the
    database in the same state as it was at the time of the dump.
    PostgreSQL provides the utility program
@@ -39,6 +39,9 @@ pg_dump dbname > 
 
    As you see, pg_dump writes its result to the
    standard output. We will see below how this can be useful.
+   While the above command creates a text file, pg_dump
+   can create files in other formats that allow for parallism and more
+   fine-grained control of object restoration.
   
 
   
@@ -98,20 +101,11 @@ pg_dump dbname > 
    exclusive lock, such as most forms of ALTER TABLE.)
   
 
-  
-   
-    If your database schema relies on OIDs (for instance, as foreign
-    keys) you must instruct pg_dump to dump the OIDs
-    as well. To do this, use the -o command-line
-    option.
-   
-  
-
   
    Restoring the Dump
 
    
-    The text files created by pg_dump are intended to
+    Text files created by pg_dump are intended to
     be read in by the psql program. The
     general command form to restore a dump is
 
@@ -127,6 +121,8 @@ psql dbname < 
     supports options similar to pg_dump for specifying
     the database server to connect to and the user name to use. See
     the  reference page for more information.
+    Non-text file dumps are restored using the 
+    linkend="app-pgrestore"> utility.
    
 
    
@@ -225,7 +221,14 @@ psql -f infile postgres
     roles, tablespaces, and empty databases, then invoking
     pg_dump for each database.  This means that while
     each database will be internally consistent, the snapshots of
-    different databases might not be exactly in-sync.
+    different databases are not sychronized.
+   
+
+   
+    Cluster-wide data can be dumped alone using the
+    pg_dumpall --globals-only option.
+    This is necessary to fully backup the cluster if running the
+    pg_dump command on individual databases.
    
   
 


diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml

index 1d91d92fe3618f7a89bb9189bef7c7d8c2eea275..f3374857363bbb35c64000f0ec24740cf922f37c 100644 (file)

--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1517,8 +1517,9 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`
    For major releases of PostgreSQL, the
    internal data storage format is subject to change, thus complicating
    upgrades.  The traditional method for moving data to a new major version
-   is to dump and reload the database.  Other methods are available,
-   as discussed below.
+   is to dump and reload the database, though this can be slow.  A
+   faster method is .  Replication methods are
+   also available, as discussed below.
   
 
   
@@ -1593,12 +1594,14 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`
 
   
 
-  e-methods-pgdump">
-   Upgrading Data via <application>pg_dump</>
+  ing-via-pgdumpall">
+   Upgrading Data via <application>pg_dump<span class="marked">all</span></>
 
    
-    To dump data from one major version of PostgreSQL and
-    reload it in another, you must use pg_dump; file system
+    One upgrade method is to dump data from one major version of
+    PostgreSQL and reload it in another —  to do
+    this, you must use a logical backup tool like
+    pg_dumpall; file system
     level backup methods will not work. (There are checks in place that prevent
     you from using a data directory with an incompatible version of
     PostgreSQL, so no great harm can be done by
@@ -1607,7 +1610,8 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`
 
    
     It is recommended that you use the pg_dump and
-    pg_dumpall programs from the newer version of
+    pg_dumpall programs from the newer
+    version of
     PostgreSQL, to take advantage of enhancements
     that might have been made in these programs.  Current releases of the
     dump programs can read data from any server version back to 7.0.
@@ -1642,14 +1646,12 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`
 
 pg_dumpall > outputfile
 
-      If you need to preserve OIDs (such as when using them as
-      foreign keys), then use the -o option when running
-      pg_dumpall.
      
 
      
       To make the backup, you can use the pg_dumpall
-      command from the version you are currently running.  For best
+      command from the version you are currently running;  see 
+      linkend="backup-dump-all"> for more details.  For best
       results, however, try to use the pg_dumpall
       command from PostgreSQL &version;,
       since this version contains bug fixes and improvements over older
@@ -1683,7 +1685,8 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`
     
      
       If restoring from backup, rename or delete the old installation
-      directory.  It is a good idea to rename the directory, rather than
+      directory if it is not version-specific.  It is a good idea to
+      rename the directory, rather than
       delete it, in case you have trouble and need to revert to it.  Keep
       in mind the directory might consume significant disk space.  To rename
       the directory, use a command like this:
@@ -1755,16 +1758,24 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
 
   
 
-  methods-other">
-   <span class="marked">Non-Dump Upgrade Methods</span>
+  via-pg-upgrade">
+   <span class="marked">Upgrading Data via <application>pg_upgrade</></span>
 
    
-    The pg_upgrade module allows an
-    installation to be migrated in-place from one major
-    PostgreSQL version to the next.  Upgrades can be
-    performed in minutes.
+    The  module allows an installation to
+    be migrated in-place from one major PostgreSQL
+    version to another.  Upgrades can be performed in minutes,
+    particularly with --link mode.  It requires steps similar to
+    pg_dumpall above, e.g.  starting/stopping the server,
+    running initdb.  The pg_upgrade 
+    linkend="pgupgrade">documentation outlines the necessary steps.
    
 
+  
+
+  
+   Upgrading Data via Replication
+
    
     It is also possible to use certain replication methods, such as
     Slony, to create a standby server with the updated version of




This is the main PostgreSQL git repository.
RSS
Atom

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 1d91d92fe3618f7a89bb9189bef7c7d8c2eea275..f3374857363bbb35c64000f0ec24740cf922f37c 100644 (file)
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1517,8 +1517,9 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`
    For major releases of PostgreSQL, the
    internal data storage format is subject to change, thus complicating
    upgrades.  The traditional method for moving data to a new major version
-   is to dump and reload the database.  Other methods are available,
-   as discussed below.
+   is to dump and reload the database, though this can be slow.  A
+   faster method is .  Replication methods are
+   also available, as discussed below.
   
 
   
@@ -1593,12 +1594,14 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`
 
   
 
-  e-methods-pgdump">
-   Upgrading Data via <application>pg_dump</>
+  ing-via-pgdumpall">
+   Upgrading Data via <application>pg_dump<span class="marked">all</span></>
 
    
-    To dump data from one major version of PostgreSQL and
-    reload it in another, you must use pg_dump; file system
+    One upgrade method is to dump data from one major version of
+    PostgreSQL and reload it in another —  to do
+    this, you must use a logical backup tool like
+    pg_dumpall; file system
     level backup methods will not work. (There are checks in place that prevent
     you from using a data directory with an incompatible version of
     PostgreSQL, so no great harm can be done by
@@ -1607,7 +1610,8 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`
 
    
     It is recommended that you use the pg_dump and
-    pg_dumpall programs from the newer version of
+    pg_dumpall programs from the newer
+    version of
     PostgreSQL, to take advantage of enhancements
     that might have been made in these programs.  Current releases of the
     dump programs can read data from any server version back to 7.0.
@@ -1642,14 +1646,12 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`
 
 pg_dumpall > outputfile
 
-      If you need to preserve OIDs (such as when using them as
-      foreign keys), then use the -o option when running
-      pg_dumpall.
      
 
      
       To make the backup, you can use the pg_dumpall
-      command from the version you are currently running.  For best
+      command from the version you are currently running;  see 
+      linkend="backup-dump-all"> for more details.  For best
       results, however, try to use the pg_dumpall
       command from PostgreSQL &version;,
       since this version contains bug fixes and improvements over older
@@ -1683,7 +1685,8 @@ $ kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`
     
      
       If restoring from backup, rename or delete the old installation
-      directory.  It is a good idea to rename the directory, rather than
+      directory if it is not version-specific.  It is a good idea to
+      rename the directory, rather than
       delete it, in case you have trouble and need to revert to it.  Keep
       in mind the directory might consume significant disk space.  To rename
       the directory, use a command like this:
@@ -1755,16 +1758,24 @@ pg_dumpall -p 5432 | psql -d postgres -p 5433
 
   
 
-  methods-other">
-   <span class="marked">Non-Dump Upgrade Methods</span>
+  via-pg-upgrade">
+   <span class="marked">Upgrading Data via <application>pg_upgrade</></span>
 
    
-    The pg_upgrade module allows an
-    installation to be migrated in-place from one major
-    PostgreSQL version to the next.  Upgrades can be
-    performed in minutes.
+    The  module allows an installation to
+    be migrated in-place from one major PostgreSQL
+    version to another.  Upgrades can be performed in minutes,
+    particularly with --link mode.  It requires steps similar to
+    pg_dumpall above, e.g.  starting/stopping the server,
+    running initdb.  The pg_upgrade 
+    linkend="pgupgrade">documentation outlines the necessary steps.
    
 
+  
+
+  
+   Upgrading Data via Replication
+
    
     It is also possible to use certain replication methods, such as
     Slony, to create a standby server with the updated version of