1034 lines
39 KiB
Plaintext
1034 lines
39 KiB
Plaintext
<!--
|
|
doc/src/sgml/ref/pgupgrade.sgml
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="pgupgrade">
|
|
<indexterm zone="pgupgrade">
|
|
<primary>pg_upgrade</primary>
|
|
</indexterm>
|
|
|
|
<refmeta>
|
|
<refentrytitle><application>pg_upgrade</application></refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo>Application</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>pg_upgrade</refname>
|
|
<refpurpose>upgrade a <productname>PostgreSQL</productname> server instance</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>pg_upgrade</command>
|
|
<arg choice="plain"><option>-b</option></arg>
|
|
<arg choice="plain"><replaceable>oldbindir</replaceable></arg>
|
|
<arg choice="opt"><option>-B</option> <replaceable>newbindir</replaceable></arg>
|
|
<arg choice="plain"><option>-d</option></arg>
|
|
<arg choice="plain"><replaceable>oldconfigdir</replaceable></arg>
|
|
<arg choice="plain"><option>-D</option></arg>
|
|
<arg choice="plain"><replaceable>newconfigdir</replaceable></arg>
|
|
<arg rep="repeat"><replaceable>option</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
<application>pg_upgrade</application> (formerly called <application>pg_migrator</application>) allows data
|
|
stored in <productname>PostgreSQL</productname> data files to be upgraded to a later <productname>PostgreSQL</productname>
|
|
major version without the data dump/restore typically required for
|
|
major version upgrades, e.g., from 12.14 to 13.10 or from 14.9 to 15.5.
|
|
It is not required for minor version upgrades, e.g., from 12.7 to 12.8
|
|
or from 14.1 to 14.5.
|
|
</para>
|
|
|
|
<para>
|
|
Major PostgreSQL releases regularly add new features that often
|
|
change the layout of the system tables, but the internal data storage
|
|
format rarely changes. <application>pg_upgrade</application> uses this fact
|
|
to perform rapid upgrades by creating new system tables and simply
|
|
reusing the old user data files. If a future major release ever
|
|
changes the data storage format in a way that makes the old data
|
|
format unreadable, <application>pg_upgrade</application> will not be usable
|
|
for such upgrades. (The community will attempt to avoid such
|
|
situations.)
|
|
</para>
|
|
|
|
<para>
|
|
<application>pg_upgrade</application> does its best to
|
|
make sure the old and new clusters are binary-compatible, e.g., by
|
|
checking for compatible compile-time settings, including 32/64-bit
|
|
binaries. It is important that
|
|
any external modules are also binary compatible, though this cannot
|
|
be checked by <application>pg_upgrade</application>.
|
|
</para>
|
|
|
|
<para>
|
|
pg_upgrade supports upgrades from 9.2.X and later to the current
|
|
major release of <productname>PostgreSQL</productname>, including snapshot and beta releases.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
|
|
<para>
|
|
<application>pg_upgrade</application> accepts the following command-line arguments:
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><option>-b</option> <replaceable>bindir</replaceable></term>
|
|
<term><option>--old-bindir=</option><replaceable>bindir</replaceable></term>
|
|
<listitem><para>the old PostgreSQL executable directory;
|
|
environment variable <envar>PGBINOLD</envar></para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-B</option> <replaceable>bindir</replaceable></term>
|
|
<term><option>--new-bindir=</option><replaceable>bindir</replaceable></term>
|
|
<listitem><para>the new PostgreSQL executable directory;
|
|
default is the directory where <application>pg_upgrade</application> resides;
|
|
environment variable <envar>PGBINNEW</envar></para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-c</option></term>
|
|
<term><option>--check</option></term>
|
|
<listitem><para>check clusters only, don't change any data</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-d</option> <replaceable>configdir</replaceable></term>
|
|
<term><option>--old-datadir=</option><replaceable>configdir</replaceable></term>
|
|
<listitem><para>the old database cluster configuration directory; environment
|
|
variable <envar>PGDATAOLD</envar></para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-D</option> <replaceable>configdir</replaceable></term>
|
|
<term><option>--new-datadir=</option><replaceable>configdir</replaceable></term>
|
|
<listitem><para>the new database cluster configuration directory; environment
|
|
variable <envar>PGDATANEW</envar></para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-j <replaceable class="parameter">njobs</replaceable></option></term>
|
|
<term><option>--jobs=<replaceable class="parameter">njobs</replaceable></option></term>
|
|
<listitem><para>number of simultaneous processes or threads to use
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-k</option></term>
|
|
<term><option>--link</option></term>
|
|
<listitem><para>use hard links instead of copying files to the new
|
|
cluster</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-N</option></term>
|
|
<term><option>--no-sync</option></term>
|
|
<listitem>
|
|
<para>
|
|
By default, <command>pg_upgrade</command> will wait for all files
|
|
of the upgraded cluster to be written safely to disk. This option
|
|
causes <command>pg_upgrade</command> to return without waiting, which
|
|
is faster, but means that a subsequent operating system crash can leave
|
|
the data directory corrupt. Generally, this option is
|
|
useful for testing but should not be used on a production
|
|
installation.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-o</option> <replaceable class="parameter">options</replaceable></term>
|
|
<term><option>--old-options</option> <replaceable class="parameter">options</replaceable></term>
|
|
<listitem><para>options to be passed directly to the
|
|
old <command>postgres</command> command; multiple
|
|
option invocations are appended</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-O</option> <replaceable class="parameter">options</replaceable></term>
|
|
<term><option>--new-options</option> <replaceable class="parameter">options</replaceable></term>
|
|
<listitem><para>options to be passed directly to the
|
|
new <command>postgres</command> command; multiple
|
|
option invocations are appended</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-p</option> <replaceable>port</replaceable></term>
|
|
<term><option>--old-port=</option><replaceable>port</replaceable></term>
|
|
<listitem><para>the old cluster port number; environment
|
|
variable <envar>PGPORTOLD</envar></para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-P</option> <replaceable>port</replaceable></term>
|
|
<term><option>--new-port=</option><replaceable>port</replaceable></term>
|
|
<listitem><para>the new cluster port number; environment
|
|
variable <envar>PGPORTNEW</envar></para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-r</option></term>
|
|
<term><option>--retain</option></term>
|
|
<listitem><para>retain SQL and log files even after successful completion
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-s</option> <replaceable>dir</replaceable></term>
|
|
<term><option>--socketdir=</option><replaceable>dir</replaceable></term>
|
|
<listitem><para>directory to use for postmaster sockets during upgrade;
|
|
default is current working directory; environment
|
|
variable <envar>PGSOCKETDIR</envar></para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--sync-method=</option><replaceable>method</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
When set to <literal>fsync</literal>, which is the default,
|
|
<command>pg_upgrade</command> will recursively open and synchronize all
|
|
files in the upgraded cluster's data directory. The search for files
|
|
will follow symbolic links for the WAL directory and each configured
|
|
tablespace.
|
|
</para>
|
|
<para>
|
|
On Linux, <literal>syncfs</literal> may be used instead to ask the
|
|
operating system to synchronize the whole file systems that contain the
|
|
upgraded cluster's data directory, its WAL files, and each tablespace.
|
|
See <xref linkend="syncfs"/> for more information about using
|
|
<function>syncfs()</function>.
|
|
</para>
|
|
<para>
|
|
This option has no effect when <option>--no-sync</option> is used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-U</option> <replaceable>username</replaceable></term>
|
|
<term><option>--username=</option><replaceable>username</replaceable></term>
|
|
<listitem><para>cluster's install user name; environment
|
|
variable <envar>PGUSER</envar></para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-v</option></term>
|
|
<term><option>--verbose</option></term>
|
|
<listitem><para>enable verbose internal logging</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-V</option></term>
|
|
<term><option>--version</option></term>
|
|
<listitem><para>display version information, then exit</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--clone</option></term>
|
|
<listitem>
|
|
<para>
|
|
Use efficient file cloning (also known as <quote>reflinks</quote> on
|
|
some systems) instead of copying files to the new cluster. This can
|
|
result in near-instantaneous copying of the data files, giving the
|
|
speed advantages of <option>-k</option>/<option>--link</option> while
|
|
leaving the old cluster untouched.
|
|
</para>
|
|
|
|
<para>
|
|
File cloning is only supported on some operating systems and file
|
|
systems. If it is selected but not supported, the
|
|
<application>pg_upgrade</application> run will error. At present, it
|
|
is supported on Linux (kernel 4.5 or later) with Btrfs and XFS (on
|
|
file systems created with reflink support), and on macOS with APFS.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--copy</option></term>
|
|
<listitem>
|
|
<para>
|
|
Copy files to the new cluster. This is the default. (See also
|
|
<option>--link</option> and <option>--clone</option>.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--copy-file-range</option></term>
|
|
<listitem>
|
|
<para>
|
|
Use the <function>copy_file_range</function> system call for efficient
|
|
copying. On some file systems this gives results similar to
|
|
<option>--clone</option>, sharing physical disk blocks, while on others
|
|
it may still copy blocks, but do so via an optimized path. At present,
|
|
it is supported on Linux and FreeBSD.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-?</option></term>
|
|
<term><option>--help</option></term>
|
|
<listitem><para>show help, then exit</para></listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Usage</title>
|
|
|
|
<para>
|
|
These are the steps to perform an upgrade
|
|
with <application>pg_upgrade</application>:
|
|
</para>
|
|
|
|
<procedure>
|
|
<step performance="optional">
|
|
<title>Optionally move the old cluster</title>
|
|
|
|
<para>
|
|
If you are using a version-specific installation directory, e.g.,
|
|
<filename>/opt/PostgreSQL/&majorversion;</filename>, you do not need to move the old cluster. The
|
|
graphical installers all use version-specific installation directories.
|
|
</para>
|
|
|
|
<para>
|
|
If your installation directory is not version-specific, e.g.,
|
|
<filename>/usr/local/pgsql</filename>, it is necessary to move the current PostgreSQL install
|
|
directory so it does not interfere with the new <productname>PostgreSQL</productname> installation.
|
|
Once the current <productname>PostgreSQL</productname> server is shut down, it is safe to rename the
|
|
PostgreSQL installation directory; assuming the old directory is
|
|
<filename>/usr/local/pgsql</filename>, you can do:
|
|
|
|
<programlisting>
|
|
mv /usr/local/pgsql /usr/local/pgsql.old
|
|
</programlisting>
|
|
to rename the directory.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<title>For source installs, build the new version</title>
|
|
|
|
<para>
|
|
Build the new PostgreSQL source with <command>configure</command> flags that are compatible
|
|
with the old cluster. <application>pg_upgrade</application> will check <command>pg_controldata</command> to make
|
|
sure all settings are compatible before starting the upgrade.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Install the new PostgreSQL binaries</title>
|
|
|
|
<para>
|
|
Install the new server's binaries and support
|
|
files. <application>pg_upgrade</application> is included in a default installation.
|
|
</para>
|
|
|
|
<para>
|
|
For source installs, if you wish to install the new server in a custom
|
|
location, use the <literal>prefix</literal> variable:
|
|
|
|
<programlisting>
|
|
make prefix=/usr/local/pgsql.new install
|
|
</programlisting></para>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Initialize the new PostgreSQL cluster</title>
|
|
|
|
<para>
|
|
Initialize the new cluster using <command>initdb</command>.
|
|
Again, use compatible <command>initdb</command>
|
|
flags that match the old cluster. Many
|
|
prebuilt installers do this step automatically. There is no need to
|
|
start the new cluster.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Install extension shared object files</title>
|
|
|
|
<para>
|
|
Many extensions and custom modules, whether from
|
|
<filename>contrib</filename> or another source, use shared object
|
|
files (or DLLs), e.g., <filename>pgcrypto.so</filename>. If the old
|
|
cluster used these, shared object files matching the new server binary
|
|
must be installed in the new cluster, usually via operating system
|
|
commands. Do not load the schema definitions, e.g., <command>CREATE
|
|
EXTENSION pgcrypto</command>, because these will be duplicated from
|
|
the old cluster. If extension updates are available,
|
|
<application>pg_upgrade</application> will report this and create
|
|
a script that can be run later to update them.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Copy custom full-text search files</title>
|
|
|
|
<para>
|
|
Copy any custom full text search files (dictionary, synonym,
|
|
thesaurus, stop words) from the old to the new cluster.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Adjust authentication</title>
|
|
|
|
<para>
|
|
<command>pg_upgrade</command> will connect to the old and new servers several
|
|
times, so you might want to set authentication to <literal>peer</literal>
|
|
in <filename>pg_hba.conf</filename> or use a <filename>~/.pgpass</filename> file
|
|
(see <xref linkend="libpq-pgpass"/>).
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Prepare for publisher upgrades</title>
|
|
|
|
<para>
|
|
<application>pg_upgrade</application> attempts to migrate logical
|
|
slots. This helps avoid the need for manually defining the same
|
|
logical slots on the new publisher. Migration of logical slots is
|
|
only supported when the old cluster is version 17.0 or later.
|
|
Logical slots on clusters before version 17.0 will silently be
|
|
ignored.
|
|
</para>
|
|
|
|
<para>
|
|
Before you start upgrading the publisher cluster, ensure that the
|
|
subscription is temporarily disabled, by executing
|
|
<link linkend="sql-altersubscription"><command>ALTER SUBSCRIPTION ... DISABLE</command></link>.
|
|
Re-enable the subscription after the upgrade.
|
|
</para>
|
|
|
|
<para>
|
|
There are some prerequisites for <application>pg_upgrade</application> to
|
|
be able to upgrade the logical slots. If these are not met an error
|
|
will be reported.
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
The new cluster must have
|
|
<link linkend="guc-wal-level"><varname>wal_level</varname></link> as
|
|
<literal>logical</literal>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The new cluster must have
|
|
<link linkend="guc-max-replication-slots"><varname>max_replication_slots</varname></link>
|
|
configured to a value greater than or equal to the number of slots
|
|
present in the old cluster.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The output plugins referenced by the slots on the old cluster must be
|
|
installed in the new PostgreSQL executable directory.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The old cluster has replicated all the transactions and logical decoding
|
|
messages to subscribers.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
All slots on the old cluster must be usable, i.e., there are no slots
|
|
whose
|
|
<link linkend="view-pg-replication-slots">pg_replication_slots</link>.<structfield>conflict_reason</structfield>
|
|
is not <literal>NULL</literal>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The new cluster must not have permanent logical slots, i.e.,
|
|
there must be no slots where
|
|
<link linkend="view-pg-replication-slots">pg_replication_slots</link>.<structfield>temporary</structfield>
|
|
is <literal>false</literal>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
</step>
|
|
|
|
<step>
|
|
<title>Prepare for subscriber upgrades</title>
|
|
|
|
<para>
|
|
Setup the <link linkend="logical-replication-config-subscriber">
|
|
subscriber configurations</link> in the new subscriber.
|
|
<application>pg_upgrade</application> attempts to migrate subscription
|
|
dependencies which includes the subscription's table information present in
|
|
<link linkend="catalog-pg-subscription-rel">pg_subscription_rel</link>
|
|
system catalog and also the subscription's replication origin. This allows
|
|
logical replication on the new subscriber to continue from where the
|
|
old subscriber was up to. Migration of subscription dependencies is only
|
|
supported when the old cluster is version 17.0 or later. Subscription
|
|
dependencies on clusters before version 17.0 will silently be ignored.
|
|
</para>
|
|
|
|
<para>
|
|
There are some prerequisites for <application>pg_upgrade</application> to
|
|
be able to upgrade the subscriptions. If these are not met an error
|
|
will be reported.
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
All the subscription tables in the old subscriber should be in state
|
|
<literal>i</literal> (initialize) or <literal>r</literal> (ready). This
|
|
can be verified by checking <link linkend="catalog-pg-subscription-rel">pg_subscription_rel</link>.<structfield>srsubstate</structfield>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The replication origin entry corresponding to each of the subscriptions
|
|
should exist in the old cluster. This can be found by checking
|
|
<link linkend="catalog-pg-subscription">pg_subscription</link> and
|
|
<link linkend="catalog-pg-replication-origin">pg_replication_origin</link>
|
|
system tables.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The new cluster must have
|
|
<link linkend="guc-max-replication-slots"><varname>max_replication_slots</varname></link>
|
|
configured to a value greater than or equal to the number of
|
|
subscriptions present in the old cluster.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Stop both servers</title>
|
|
|
|
<para>
|
|
Make sure both database servers are stopped using, on Unix, e.g.:
|
|
|
|
<programlisting>
|
|
pg_ctl -D /opt/PostgreSQL/12 stop
|
|
pg_ctl -D /opt/PostgreSQL/&majorversion; stop
|
|
</programlisting>
|
|
|
|
or on Windows, using the proper service names:
|
|
|
|
<programlisting>
|
|
NET STOP postgresql-12
|
|
NET STOP postgresql-&majorversion;
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Streaming replication and log-shipping standby servers must be
|
|
running during this shutdown so they receive all changes.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Prepare for standby server upgrades</title>
|
|
|
|
<para>
|
|
If you are upgrading standby servers using methods outlined in section <xref
|
|
linkend="pgupgrade-step-replicas"/>, verify that the old standby
|
|
servers are caught up by running <application>pg_controldata</application>
|
|
against the old primary and standby clusters. Verify that the
|
|
<quote>Latest checkpoint location</quote> values match in all clusters.
|
|
Also, make sure <varname>wal_level</varname> is not set to
|
|
<literal>minimal</literal> in the <filename>postgresql.conf</filename> file on the
|
|
new primary cluster.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Run <application>pg_upgrade</application></title>
|
|
|
|
<para>
|
|
Always run the <application>pg_upgrade</application> binary of the new server, not the old one.
|
|
<application>pg_upgrade</application> requires the specification of the old and new cluster's
|
|
data and executable (<filename>bin</filename>) directories. You can also specify
|
|
user and port values, and whether you want the data files linked or cloned
|
|
instead of the default copy behavior.
|
|
</para>
|
|
|
|
<para>
|
|
If you use link mode, the upgrade will be much faster (no file
|
|
copying) and use less disk space, but you will not be able to access
|
|
your old cluster
|
|
once you start the new cluster after the upgrade. Link mode also
|
|
requires that the old and new cluster data directories be in the
|
|
same file system. (Tablespaces and <filename>pg_wal</filename> can be on
|
|
different file systems.)
|
|
Clone mode provides the same speed and disk space advantages but
|
|
does not cause the old cluster to be unusable once the new cluster
|
|
is started. Clone mode also requires that the old and new data
|
|
directories be in the same file system. This mode is only available
|
|
on certain operating systems and file systems.
|
|
</para>
|
|
|
|
<para>
|
|
The <option>--jobs</option> option allows multiple CPU cores to be used
|
|
for copying/linking of files and to dump and restore database schemas
|
|
in parallel; a good place to start is the maximum of the number of
|
|
CPU cores and tablespaces. This option can dramatically reduce the
|
|
time to upgrade a multi-database server running on a multiprocessor
|
|
machine.
|
|
</para>
|
|
|
|
<para>
|
|
For Windows users, you must be logged into an administrative account,
|
|
and then run <application>pg_upgrade</application> with quoted
|
|
directories, e.g.:
|
|
|
|
<programlisting>
|
|
pg_upgrade.exe
|
|
--old-datadir "C:/Program Files/PostgreSQL/12/data"
|
|
--new-datadir "C:/Program Files/PostgreSQL/&majorversion;/data"
|
|
--old-bindir "C:/Program Files/PostgreSQL/12/bin"
|
|
--new-bindir "C:/Program Files/PostgreSQL/&majorversion;/bin"
|
|
</programlisting>
|
|
|
|
Once started, <command>pg_upgrade</command> will verify the two clusters are compatible
|
|
and then do the upgrade. You can use <command>pg_upgrade --check</command>
|
|
to perform only the checks, even if the old server is still
|
|
running. <command>pg_upgrade --check</command> will also outline any
|
|
manual adjustments you will need to make after the upgrade. If you
|
|
are going to be using link or clone mode, you should use the option
|
|
<option>--link</option> or <option>--clone</option> with
|
|
<option>--check</option> to enable mode-specific checks.
|
|
<command>pg_upgrade</command> requires write permission in the current directory.
|
|
</para>
|
|
|
|
<para>
|
|
Obviously, no one should be accessing the clusters during the
|
|
upgrade. <application>pg_upgrade</application> defaults to running servers
|
|
on port 50432 to avoid unintended client connections.
|
|
You can use the same port number for both clusters when doing an
|
|
upgrade because the old and new clusters will not be running at the
|
|
same time. However, when checking an old running server, the old
|
|
and new port numbers must be different.
|
|
</para>
|
|
|
|
<para>
|
|
If an error occurs while restoring the database schema, <command>pg_upgrade</command> will
|
|
exit and you will have to revert to the old cluster as outlined in <xref linkend="pgupgrade-step-revert"/>
|
|
below. To try <command>pg_upgrade</command> again, you will need to modify the old
|
|
cluster so the pg_upgrade schema restore succeeds. If the problem is a
|
|
<filename>contrib</filename> module, you might need to uninstall the <filename>contrib</filename> module from
|
|
the old cluster and install it in the new cluster after the upgrade,
|
|
assuming the module is not being used to store user data.
|
|
</para>
|
|
</step>
|
|
|
|
<step id="pgupgrade-step-replicas">
|
|
<title>Upgrade streaming replication and log-shipping standby servers</title>
|
|
|
|
<para>
|
|
If you used link mode and have Streaming Replication (see <xref
|
|
linkend="streaming-replication"/>) or Log-Shipping (see <xref
|
|
linkend="warm-standby"/>) standby servers, you can follow these steps to
|
|
quickly upgrade them. You will not be running <application>pg_upgrade</application> on
|
|
the standby servers, but rather <application>rsync</application> on the primary.
|
|
Do not start any servers yet.
|
|
</para>
|
|
|
|
<para>
|
|
If you did <emphasis>not</emphasis> use link mode, do not have or do not
|
|
want to use <application>rsync</application>, or want an easier solution, skip
|
|
the instructions in this section and simply recreate the standby
|
|
servers once <application>pg_upgrade</application> completes and the new primary
|
|
is running.
|
|
</para>
|
|
|
|
<procedure>
|
|
|
|
<step>
|
|
<title>Install the new PostgreSQL binaries on standby servers</title>
|
|
|
|
<para>
|
|
Make sure the new binaries and support files are installed on all
|
|
standby servers.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Make sure the new standby data directories do <emphasis>not</emphasis> exist</title>
|
|
|
|
<para>
|
|
Make sure the new standby data directories do <emphasis>not</emphasis>
|
|
exist or are empty. If <application>initdb</application> was run, delete
|
|
the standby servers' new data directories.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Install extension shared object files</title>
|
|
|
|
<para>
|
|
Install the same extension shared object files on the new standbys
|
|
that you installed in the new primary cluster.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Stop standby servers</title>
|
|
|
|
<para>
|
|
If the standby servers are still running, stop them now using the
|
|
above instructions.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Save configuration files</title>
|
|
|
|
<para>
|
|
Save any configuration files from the old standbys' configuration
|
|
directories you need to keep, e.g., <filename>postgresql.conf</filename>
|
|
(and any files included by it), <filename>postgresql.auto.conf</filename>,
|
|
<literal>pg_hba.conf</literal>, because these will be overwritten
|
|
or removed in the next step.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Run <application>rsync</application></title>
|
|
|
|
<para>
|
|
When using link mode, standby servers can be quickly upgraded using
|
|
<application>rsync</application>. To accomplish this, from a directory on
|
|
the primary server that is above the old and new database cluster
|
|
directories, run this on the <emphasis>primary</emphasis> for each standby
|
|
server:
|
|
|
|
<programlisting>
|
|
rsync --archive --delete --hard-links --size-only --no-inc-recursive old_cluster new_cluster remote_dir
|
|
</programlisting>
|
|
|
|
where <option>old_cluster</option> and <option>new_cluster</option> are relative
|
|
to the current directory on the primary, and <option>remote_dir</option>
|
|
is <emphasis>above</emphasis> the old and new cluster directories
|
|
on the standby. The directory structure under the specified
|
|
directories on the primary and standbys must match. Consult the
|
|
<application>rsync</application> manual page for details on specifying the
|
|
remote directory, e.g.,
|
|
|
|
<programlisting>
|
|
rsync --archive --delete --hard-links --size-only --no-inc-recursive /opt/PostgreSQL/12 \
|
|
/opt/PostgreSQL/&majorversion; standby.example.com:/opt/PostgreSQL
|
|
</programlisting>
|
|
|
|
You can verify what the command will do using
|
|
<application>rsync</application>'s <option>--dry-run</option> option. While
|
|
<application>rsync</application> must be run on the primary for at least one
|
|
standby, it is possible to run <application>rsync</application> on an upgraded
|
|
standby to upgrade other standbys, as long as the upgraded standby
|
|
has not been started.
|
|
</para>
|
|
|
|
<para>
|
|
What this does is to record the links created by
|
|
<application>pg_upgrade</application>'s link mode that connect files in the
|
|
old and new clusters on the primary server. It then finds matching
|
|
files in the standby's old cluster and creates links for them in the
|
|
standby's new cluster. Files that were not linked on the primary
|
|
are copied from the primary to the standby. (They are usually
|
|
small.) This provides rapid standby upgrades. Unfortunately,
|
|
<application>rsync</application> needlessly copies files associated with
|
|
temporary and unlogged tables because these files don't normally
|
|
exist on standby servers.
|
|
</para>
|
|
|
|
<para>
|
|
If you have tablespaces, you will need to run a similar
|
|
<application>rsync</application> command for each tablespace directory, e.g.:
|
|
|
|
<programlisting>
|
|
rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tblsp/PG_12_201909212 \
|
|
/vol1/pg_tblsp/PG_&majorversion;_202307071 standby.example.com:/vol1/pg_tblsp
|
|
</programlisting>
|
|
|
|
If you have relocated <filename>pg_wal</filename> outside the data
|
|
directories, <application>rsync</application> must be run on those directories
|
|
too.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Configure streaming replication and log-shipping standby servers</title>
|
|
|
|
<para>
|
|
Configure the servers for log shipping. (You do not need to run
|
|
<function>pg_backup_start()</function> and <function>pg_backup_stop()</function>
|
|
or take a file system backup as the standbys are still synchronized
|
|
with the primary.) If the old primary is prior to version 17.0, then no
|
|
slots on the primary are copied to the new standby, so all the slots on
|
|
the old standby must be recreated manually. If the old primary is
|
|
version 17.0 or later, then only logical slots on the primary are copied
|
|
to the new standby, but other slots on the old standby are not copied,
|
|
so must be recreated manually.
|
|
</para>
|
|
</step>
|
|
|
|
</procedure>
|
|
|
|
</step>
|
|
|
|
<step>
|
|
<title>Restore <filename>pg_hba.conf</filename></title>
|
|
|
|
<para>
|
|
If you modified <filename>pg_hba.conf</filename>, restore its original settings.
|
|
It might also be necessary to adjust other configuration files in the new
|
|
cluster to match the old cluster, e.g., <filename>postgresql.conf</filename>
|
|
(and any files included by it), <filename>postgresql.auto.conf</filename>.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Start the new server</title>
|
|
|
|
<para>
|
|
The new server can now be safely started, and then any
|
|
<application>rsync</application>'ed standby servers.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Post-upgrade processing</title>
|
|
|
|
<para>
|
|
If any post-upgrade processing is required, pg_upgrade will issue
|
|
warnings as it completes. It will also generate script files that must
|
|
be run by the administrator. The script files will connect to each
|
|
database that needs post-upgrade processing. Each script should be
|
|
run using:
|
|
|
|
<programlisting>
|
|
psql --username=postgres --file=script.sql postgres
|
|
</programlisting>
|
|
|
|
The scripts can be run in any order and can be deleted once they have
|
|
been run.
|
|
</para>
|
|
|
|
<caution>
|
|
<para>
|
|
In general it is unsafe to access tables referenced in rebuild scripts
|
|
until the rebuild scripts have run to completion; doing so could yield
|
|
incorrect results or poor performance. Tables not referenced in rebuild
|
|
scripts can be accessed immediately.
|
|
</para>
|
|
</caution>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Statistics</title>
|
|
|
|
<para>
|
|
Because optimizer statistics are not transferred by <command>pg_upgrade</command>, you will
|
|
be instructed to run a command to regenerate that information at the end
|
|
of the upgrade. You might need to set connection parameters to
|
|
match your new cluster.
|
|
</para>
|
|
|
|
<para>
|
|
Using <command>vacuumdb --all --analyze-only</command> can efficiently
|
|
generate such statistics, and the use of <option>--jobs</option>
|
|
can speed it up. Option <option>--analyze-in-stages</option>
|
|
can be used to generate minimal statistics quickly.
|
|
If <varname>vacuum_cost_delay</varname> is set to a non-zero
|
|
value, this can be overridden to speed up statistics generation
|
|
using <envar>PGOPTIONS</envar>, e.g., <literal>PGOPTIONS='-c
|
|
vacuum_cost_delay=0' vacuumdb ...</literal>.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<title>Delete old cluster</title>
|
|
|
|
<para>
|
|
Once you are satisfied with the upgrade, you can delete the old
|
|
cluster's data directories by running the script mentioned when
|
|
<command>pg_upgrade</command> completes. (Automatic deletion is not
|
|
possible if you have user-defined tablespaces inside the old data
|
|
directory.) You can also delete the old installation directories
|
|
(e.g., <filename>bin</filename>, <filename>share</filename>).
|
|
</para>
|
|
</step>
|
|
|
|
<step id="pgupgrade-step-revert" performance="optional">
|
|
<title>Reverting to old cluster</title>
|
|
|
|
<para>
|
|
If, after running <command>pg_upgrade</command>, you wish to revert to the old cluster,
|
|
there are several options:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
If the <option>--check</option> option was used, the old cluster
|
|
was unmodified; it can be restarted.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
If the <option>--link</option> option was <emphasis>not</emphasis>
|
|
used, the old cluster was unmodified; it can be restarted.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
If the <option>--link</option> option was used, the data
|
|
files might be shared between the old and new cluster:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
If <command>pg_upgrade</command> aborted before linking started,
|
|
the old cluster was unmodified; it can be restarted.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
If you did <emphasis>not</emphasis> start the new cluster, the old
|
|
cluster was unmodified except that, when linking started, a
|
|
<literal>.old</literal> suffix was appended to
|
|
<filename>$PGDATA/global/pg_control</filename>. To reuse the old
|
|
cluster, remove the <filename>.old</filename> suffix from
|
|
<filename>$PGDATA/global/pg_control</filename>; you can then restart
|
|
the old cluster.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
If you did start the new cluster, it has written to shared files
|
|
and it is unsafe to use the old cluster. The old cluster will
|
|
need to be restored from backup in this case.
|
|
</para>
|
|
</listitem>
|
|
|
|
</itemizedlist></para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
</step>
|
|
</procedure>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
<application>pg_upgrade</application> creates various working files, such
|
|
as schema dumps, stored within <filename>pg_upgrade_output.d</filename> in
|
|
the directory of the new cluster. Each run creates a new subdirectory named
|
|
with a timestamp formatted as per ISO 8601
|
|
(<literal>%Y%m%dT%H%M%S</literal>), where all its generated files are
|
|
stored.
|
|
<filename>pg_upgrade_output.d</filename> and its contained files will be
|
|
removed automatically if <application>pg_upgrade</application> completes
|
|
successfully; but in the event of trouble, the files there may provide
|
|
useful debugging information.
|
|
</para>
|
|
|
|
<para>
|
|
<application>pg_upgrade</application> launches short-lived postmasters in
|
|
the old and new data directories. Temporary Unix socket files for
|
|
communication with these postmasters are, by default, made in the current
|
|
working directory. In some situations the path name for the current
|
|
directory might be too long to be a valid socket name. In that case you
|
|
can use the <option>-s</option> option to put the socket files in some
|
|
directory with a shorter path name. For security, be sure that that
|
|
directory is not readable or writable by any other users.
|
|
(This is not supported on Windows.)
|
|
</para>
|
|
|
|
<para>
|
|
All failure, rebuild, and reindex cases will be reported by
|
|
<application>pg_upgrade</application> if they affect your installation;
|
|
post-upgrade scripts to rebuild tables and indexes will be
|
|
generated automatically. If you are trying to automate the upgrade
|
|
of many clusters, you should find that clusters with identical database
|
|
schemas require the same post-upgrade steps for all cluster upgrades;
|
|
this is because the post-upgrade steps are based on the database
|
|
schemas, and not user data.
|
|
</para>
|
|
|
|
<para>
|
|
For deployment testing, create a schema-only copy of the old cluster,
|
|
insert dummy data, and upgrade that.
|
|
</para>
|
|
|
|
<para>
|
|
<application>pg_upgrade</application> does not support upgrading of databases
|
|
containing table columns using these <type>reg*</type> OID-referencing system data types:
|
|
<simplelist>
|
|
<member><type>regcollation</type></member>
|
|
<member><type>regconfig</type></member>
|
|
<member><type>regdictionary</type></member>
|
|
<member><type>regnamespace</type></member>
|
|
<member><type>regoper</type></member>
|
|
<member><type>regoperator</type></member>
|
|
<member><type>regproc</type></member>
|
|
<member><type>regprocedure</type></member>
|
|
</simplelist>
|
|
(<type>regclass</type>, <type>regrole</type>, and <type>regtype</type> can be upgraded.)
|
|
</para>
|
|
|
|
<para>
|
|
If you want to use link mode and you do not want your old cluster
|
|
to be modified when the new cluster is started, consider using the clone mode.
|
|
If that is not available, make a copy of the
|
|
old cluster and upgrade that in link mode. To make a valid copy
|
|
of the old cluster, use <command>rsync</command> to create a dirty
|
|
copy of the old cluster while the server is running, then shut down
|
|
the old server and run <command>rsync --checksum</command> again to update the
|
|
copy with any changes to make it consistent. (<option>--checksum</option>
|
|
is necessary because <command>rsync</command> only has file modification-time
|
|
granularity of one second.) You might want to exclude some
|
|
files, e.g., <filename>postmaster.pid</filename>, as documented in <xref
|
|
linkend="backup-lowlevel-base-backup"/>. If your file system supports
|
|
file system snapshots or copy-on-write file copies, you can use that
|
|
to make a backup of the old cluster and tablespaces, though the snapshot
|
|
and copies must be created simultaneously or while the database server
|
|
is down.
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="app-initdb"/></member>
|
|
<member><xref linkend="app-pg-ctl"/></member>
|
|
<member><xref linkend="app-pgdump"/></member>
|
|
<member><xref linkend="app-postgres"/></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|