On Tue, Feb 25, 2014 at 05:05:09PM -0800, Josh Berkus wrote:
> On 02/25/2014 04:42 PM, Bruce Momjian wrote:
> > On Tue, Feb 25, 2014 at 06:41:26PM -0500, Tom Lane wrote:
> >> I'm not sure what "many limitations" you think pg_dumpall has that pg_dump
> >> doesn't.
> >>
> >> I do think that it might be time to reword this to recommend pg_upgrade
> >> first, though. ISTM that the current wording dates from when pg_upgrade
> >> could charitably be described as experimental.
> >
> > Wow, so pg_upgrade takes the lead! And from Tom too! :-)
> >
> > I agree with Tom that mentioning pg_dump/restore is going to lead to
> > global object data loss, and throwing the users to a URL with no
> > explanation isn't going to help either. What we could do is to
> > restructure the existing text and add a link to the upgrade URL for more
> > details.
>
> What I was suggesting was something like:
>
> "Users upgrading from earlier versions will need to go through the
> entire upgrade procedure, as described on our upgrade page: <link>"
>
> The problem is that anything we say about "how to upgrade" in one short
> sentence is going to confuse some people. BTW, the reason I got that
> question about pg_dump was that 9.2's release notes say "pg_dump" and
> 9.3's say "pg_dumpall", causing users to think there's been some kind of
> change.
>
> Of course, this means I need to fix the upgrade page, and I need to
> write backported versions of that fix for at least 9.1 and 9.2.
I have developed the attached patch to address the issues raised above:
o non-text output of pg_dump is mentioned
o mentions of using OID for keys is removed
o the necessity of pg_dumpall --globals-only is mentioned
o using pg_dump parallel mode rather than pg_dumpall for upgrades is mentioned
o pg_upgrade is mentioned more prominently for upgrades
o replication upgrades are in their own section
I don't think we want to mention pg_upgrade as the _primary_
major-version upgrade method. While the pg_dump upgrade section is
long, it is mostly about starting/stoping the server, moving
directories, etc, the same things you have to do for pg_upgrade, so I
just mentioned that int the pg_upgrade section. Other ideas?
I plan to apply this to head and 9.4.
--
Bruce Momjian <br...@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ Everyone has their own god. +
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
new file mode 100644
index 06f064e..07ca0dc
*** a/doc/src/sgml/backup.sgml
--- b/doc/src/sgml/backup.sgml
***************
*** 28,34 ****
<title><acronym>SQL</> Dump</title>
<para>
! The idea behind this dump method is to generate a text 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.
<productname>PostgreSQL</> provides the utility program
--- 28,34 ----
<title><acronym>SQL</> Dump</title>
<para>
! 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.
<productname>PostgreSQL</> provides the utility program
*************** pg_dump <replaceable class="parameter">d
*** 39,44 ****
--- 39,47 ----
</synopsis>
As you see, <application>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, <application>pg_dump</>
+ can create files in other formats that allow for parallism and more
+ fine-grained control of object restoration.
</para>
<para>
*************** pg_dump <replaceable class="parameter">d
*** 98,117 ****
exclusive lock, such as most forms of <command>ALTER TABLE</command>.)
</para>
- <important>
- <para>
- If your database schema relies on OIDs (for instance, as foreign
- keys) you must instruct <application>pg_dump</> to dump the OIDs
- as well. To do this, use the <option>-o</option> command-line
- option.
- </para>
- </important>
-
<sect2 id="backup-dump-restore">
<title>Restoring the Dump</title>
<para>
! The text files created by <application>pg_dump</> are intended to
be read in by the <application>psql</application> program. The
general command form to restore a dump is
<synopsis>
--- 101,111 ----
exclusive lock, such as most forms of <command>ALTER TABLE</command>.)
</para>
<sect2 id="backup-dump-restore">
<title>Restoring the Dump</title>
<para>
! Text files created by <application>pg_dump</> are intended to
be read in by the <application>psql</application> program. The
general command form to restore a dump is
<synopsis>
*************** psql <replaceable class="parameter">dbna
*** 127,132 ****
--- 121,128 ----
supports options similar to <application>pg_dump</> for specifying
the database server to connect to and the user name to use. See
the <xref linkend="app-psql"> reference page for more information.
+ Non-text file dumps are restored using the <xref
+ linkend="app-pgrestore"> utility.
</para>
<para>
*************** psql -f <replaceable class="parameter">i
*** 225,231 ****
roles, tablespaces, and empty databases, then invoking
<application>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.
</para>
</sect2>
--- 221,234 ----
roles, tablespaces, and empty databases, then invoking
<application>pg_dump</> for each database. This means that while
each database will be internally consistent, the snapshots of
! different databases are not sychronized.
! </para>
!
! <para>
! Cluster-wide data can be dumped alone using the
! <application>pg_dumpall</> <option>--globals-only</> option.
! This is necessary to fully backup the cluster if running the
! <application>pg_dump</> command on individual databases.
</para>
</sect2>
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
new file mode 100644
index 1d91d92..00cb7cb
*** a/doc/src/sgml/runtime.sgml
--- b/doc/src/sgml/runtime.sgml
*************** $ <userinput>kill -INT `head -1 /usr/loc
*** 1517,1524 ****
For <emphasis>major</> releases of <productname>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.
</para>
<para>
--- 1517,1525 ----
For <emphasis>major</> releases of <productname>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, though this can be slow. A
! faster method is <xref linkend="pgupgrade">. Replication methods are
! also available, as discussed below.
</para>
<para>
*************** $ <userinput>kill -INT `head -1 /usr/loc
*** 1593,1600 ****
</variablelist>
! <sect2 id="upgrade-methods-pgdump">
! <title>Upgrading Data via <application>pg_dump</></title>
<para>
To dump data from one major version of <productname>PostgreSQL</> and
--- 1594,1601 ----
</variablelist>
! <sect2 id="upgrading-via-pgdumpall">
! <title>Upgrading Data via <application>pg_dumpall</></title>
<para>
To dump data from one major version of <productname>PostgreSQL</> and
*************** $ <userinput>kill -INT `head -1 /usr/loc
*** 1642,1655 ****
<screen>
<userinput>pg_dumpall > <replaceable>outputfile</></userinput>
</screen>
- If you need to preserve OIDs (such as when using them as
- foreign keys), then use the <option>-o</option> option when running
- <application>pg_dumpall</>.
</para>
<para>
To make the backup, you can use the <application>pg_dumpall</application>
! command from the version you are currently running. For best
results, however, try to use the <application>pg_dumpall</application>
command from <productname>PostgreSQL</productname> &version;,
since this version contains bug fixes and improvements over older
--- 1643,1654 ----
<screen>
<userinput>pg_dumpall > <replaceable>outputfile</></userinput>
</screen>
</para>
<para>
To make the backup, you can use the <application>pg_dumpall</application>
! command from the version you are currently running; see <xref
! linkend="backup-dump-all"> for more details. For best
results, however, try to use the <application>pg_dumpall</application>
command from <productname>PostgreSQL</productname> &version;,
since this version contains bug fixes and improvements over older
*************** $ <userinput>kill -INT `head -1 /usr/loc
*** 1683,1689 ****
<step>
<para>
If restoring from backup, rename or delete the old installation
! directory. 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:
--- 1682,1689 ----
<step>
<para>
If restoring from backup, rename or delete the old installation
! 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:
*************** pg_dumpall -p 5432 | psql -d postgres -p
*** 1755,1770 ****
</sect2>
! <sect2 id="upgrading-methods-other">
! <title>Non-Dump Upgrade Methods</title>
<para>
! The <link linkend="pgupgrade">pg_upgrade</link> module allows an
! installation to be migrated in-place from one major
! <productname>PostgreSQL</> version to the next. Upgrades can be
! performed in minutes.
</para>
<para>
It is also possible to use certain replication methods, such as
<productname>Slony</>, to create a standby server with the updated version of
--- 1755,1778 ----
</sect2>
! <sect2 id="upgrading-via-pg-upgrade">
! <title>Upgrading Data via <application>pg_upgrade</></title>
<para>
! The <xref linkend="pgupgrade"> module allows an installation to
! be migrated in-place from one major <productname>PostgreSQL</>
! version to another. Upgrades can be performed in minutes.
! It requires steps similar to <application>pg_dumpall</> above, e.g.
! starting/stopping the server, running <application>initdb</>. The
! <application>pg_upgrade</> <link linkend="pgupgrade">documentation</>
! outlines the necessary steps.
</para>
+ </sect2>
+
+ <sect2 id="upgrading-via-replication">
+ <title>Upgrading Data via Replication</title>
+
<para>
It is also possible to use certain replication methods, such as
<productname>Slony</>, to create a standby server with the updated version of
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
