PostgreSQL major version upgrade from 12.8 to 13.4 using pg_upgrade

October 16, 2021
()

PostgreSQL major version upgrade from 12.8 to 13.4 using pg_upgrade

Current PostgreSQL version numbers consist of a major and a minor version number. For example, in version number 13.1, where 13 is the major version number and 1 is the minor version number.

pg_upgrade is a utility to upgrade PostgreSQL Cluster to major version eg 10.7 to 11.2 or 12.1 to 13.4. pg_upgrade support upgrades from 8.4.X and later to the latest current version. pg_upgrade utility is not applicable for minor version upgrade eg 13.1 to 13.2.

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, though this can be slow. A faster method is pg_upgrade.

In the previous blog post we saw How to perform PostgreSQL minor version upgrade from 13.1 to 13.4 Click here to read more. In this blog post, we will perform PostgreSQL Cluster major version upgrade from 12.8 to 13.4.

 

Follow the below steps to perform a major version upgrade:
1. Verify PostgreSQL-12 Cluster
2. Install the new PostgreSQL-13 software
3. Initialize the new PostgreSQL-13 cluster
4. Stop both PostgreSQL Cluster
5. Perform upgrade check
6. Perform actual upgrade
7. Start and verify PostgreSQL-13 Cluster after upgrade


Step 1. Verify PostgreSQL-12 Cluster: Login to PostgreSQL-12 and check the number of tablespaces, databases and, users. As per the below output we have 2 non-default tablespaces, 8 sample databases & 2 users. We will confirm the same number of objects available after the upgrade is done to PostgreSQL-13.

[root@test-machine01 ~]#
[root@test-machine01 ~]# su - postgres
Last login: Mon Oct 11 09:12:39 +03 2021 on pts/1
[postgres@test-machine01 ~]$
[postgres@test-machine01 ~]$
[postgres@test-machine01 u01]$ psql
psql (9.2.24, server 12.8)
WARNING: psql version 9.2, server version 12.0.
         Some psql features might not work.
Type "help" for help.
postgres=# select version();
                                                 version
---------------------------------------------------------------------------------------------------------
 PostgreSQL 12.8 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 4.8.5 20150623 (Red Hat 4.8.5-44), 64-bit
(1 row)
postgres=#
postgres=# \db+
                           List of tablespaces
    Name    |  Owner   |   Location    | Access privileges | Description
------------+----------+---------------+-------------------+-------------
 pg_default | postgres |               |                   |
 pg_global  | postgres |               |                   |
 tbls01     | postgres | /u01/pg1_tbls |                   |
 tbls02     | postgres | /u01/pg2_tbls |                   |
(4 rows)

postgres=#
postgres=# \l+
                                                                    List of databases
   Name    |  Owner   | Encoding |   Collate   |    Ctype    |   Access privileges   |  Size   | Tablespace |                Description
-----------+----------+----------+-------------+-------------+-----------------------+---------+------------+--------------------------------------------
 postgres  | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |                       | 8193 kB | pg_default | default administrative connection database
 sample1   | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |                       | 16 MB   | pg_default |
 sample2   | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |                       | 16 MB   | pg_default |
 sample3   | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |                       | 16 MB   | pg_default |
 sample4   | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |                       | 16 MB   | pg_default |
 sample5   | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |                       | 16 MB   | pg_default |
 sample6   | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |                       | 15 MB   | tbls01     |
 sample7   | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |                       | 16 MB   | tbls02     |
 template0 | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 | =c/postgres          +| 8049 kB | pg_default | unmodifiable empty database
           |          |          |             |             | postgres=CTc/postgres |         |            |
 template1 | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 | =c/postgres          +| 8049 kB | pg_default | default template for new databases
           |          |          |             |             | postgres=CTc/postgres |         |            |
(10 rows)

postgres=#
postgres=# \du+
                                                                      List of roles
         Role name         |                   Attributes                   |                          Member of                           | Description
---------------------------+------------------------------------------------+--------------------------------------------------------------+-------------
 app_user1                 |                                                | {}                                                           |
 app_user2                 |                                                | {}                                                           |
 app_user3                 |                                                | {}                                                           |
 postgres                  | Superuser, Create role, Create DB, Replication | {}                                                           |

postgres=#


Step 2. Install the new PostgreSQL-13 software: Install PostgreSQL-13 binaries for an upgrade in the same Server of PostgreSQL-12 using OS command yum install.

[root@test-machine01 ~]#
[root@test-machine01 ~]# yum install postgresql13-server postgresql13
Loaded plugins: langpacks, ulninfo
Resolving Dependencies
--> Running transaction check
---> Package postgresql13.x86_64 0:13.4-1PGDG.rhel7 will be installed
---> Package postgresql13-server.x86_64 0:13.4-1PGDG.rhel7 will be installed
--> Finished Dependency Resolution

Dependencies Resolved

=============================================================================================================================================================================
 Package                                         Arch                               Version                                         Repository                          Size
=============================================================================================================================================================================
Installing:
 postgresql13                                    x86_64                             13.4-1PGDG.rhel7                                pgdg13                             1.4 M
 postgresql13-server                             x86_64                             13.4-1PGDG.rhel7                                pgdg13                             5.4 M

Transaction Summary
=============================================================================================================================================================================
Install  2 Packages

Total download size: 6.8 M
Installed size: 29 M
Is this ok [y/d/N]: y
Downloading packages:
(1/2): postgresql13-13.4-1PGDG.rhel7.x86_64.rpm                                                                                                       | 1.4 MB  00:00:03
(2/2): postgresql13-server-13.4-1PGDG.rhel7.x86_64.rpm                                                                                                | 5.4 MB  00:00:05
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Total                                                                                                                                        1.3 MB/s | 6.8 MB  00:00:05
Running transaction check
Running transaction test
Transaction test succeeded
Running transaction
  Installing : postgresql13-13.4-1PGDG.rhel7.x86_64                                                                                                                      1/2
  Installing : postgresql13-server-13.4-1PGDG.rhel7.x86_64                                                                                                               2/2
  Verifying  : postgresql13-13.4-1PGDG.rhel7.x86_64                                                                                                                      1/2
  Verifying  : postgresql13-server-13.4-1PGDG.rhel7.x86_64                                                                                                               2/2

Installed:
  postgresql13.x86_64 0:13.4-1PGDG.rhel7                                            postgresql13-server.x86_64 0:13.4-1PGDG.rhel7

Complete!
[root@test-machine01 ~]#


Step 3. Initialize the new PostgreSQL-13 cluster: Initialize the new cluster using initdb. Once PostgreSQL-13 cluster is initialized change port to 5433 in postgresql.conf file as PostgreSQL-12, cluster already running on port default 5432. Start PostgreSQL-13 service and login to a cluster using psql this is a brand new cluster without any users objects.

[root@test-machine01 ~]#
[root@test-machine01 ~]# /usr/pgsql-13/bin/postgresql-13-setup initdb
Initializing database ... OK

[root@test-machine01 ~]# cd /var/lib/pgsql/13/data
[root@test-machine01 13]#
[root@test-machine01 data]# vi postgresql.conf
port = 5433 
:wq!
[root@test-machine01 data]#
[root@test-machine01 data]# systemctl start postgresql-13
[root@test-machine01 data]#
[root@test-machine01 data]#
[root@test-machine01 data]# su - postgres
Last login: Mon Oct 11 09:28:14 +03 2021 on pts/1
[postgres@test-machine01 ~]$
[postgres@test-machine01 ~]$ psql -p 5433
Type "help" for help.

postgres=# show port;
 port
------
 5433
(1 row)

postgres=# \l
                                  List of databases
   Name    |  Owner   | Encoding |   Collate   |    Ctype    |   Access privileges
-----------+----------+----------+-------------+-------------+-----------------------
 postgres  | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |
 template0 | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 | =c/postgres          +
           |          |          |             |             | postgres=CTc/postgres
 template1 | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 | =c/postgres          +
           |          |          |             |             | postgres=CTc/postgres
(3 rows)

postgres=#
postgres=# \du
                                                               List of roles
         Role name         |                   Attributes                   |                          Member of
---------------------------+------------------------------------------------+--------------------------------------------------------------
 postgres                  | Superuser, Create role, Create DB, Replication | {}


Step 4. Stop both PostgreSQL Cluster: Stop both PostgreSQL-13 & PostgreSQL-12 before upgrade using pg_ctl utility. Once the clusters are down verify all processes are stopped.

[postgres@test-machine01 ~]$
[postgres@test-machine01 ~]$  ps -ef|grep postmaster
postgres  31125      1  0 09:11 ?        00:00:02 /usr/pgsql-12/bin/postmaster -D /var/lib/pgsql/12/data/
postgres  32403      1  0 09:27 ?        00:00:00 /usr/pgsql-13/bin/postmaster -D /var/lib/pgsql/13/data/
postgres  49550  49477  0 13:24 pts/1    00:00:00 grep --color=auto postmaster
[postgres@test-machine01 ~]$
[postgres@test-machine01 ~]$
[postgres@test-machine01 ~]$
[postgres@test-machine01 ~]$  /usr/pgsql-12/bin/pg_ctl -D /var/lib/pgsql/12/data status
pg_ctl: server is running (PID: 31125)
/usr/pgsql-12/bin/postgres "-D" "/var/lib/pgsql/12/data/"
[postgres@test-machine01 ~]$
[postgres@test-machine01 ~]$  /usr/pgsql-13/bin/pg_ctl -D /var/lib/pgsql/13/data status
pg_ctl: server is running (PID: 32403)
/usr/pgsql-13/bin/postgres "-D" "/var/lib/pgsql/13/data/"
[postgres@test-machine01 ~]$

[postgres@test-machine01 ~]$
[postgres@test-machine01 ~]$  /usr/pgsql-12/bin/pg_ctl -D /var/lib/pgsql/12/data stop
waiting for server to shut down.... done
server stopped
[postgres@test-machine01 ~]$  /usr/pgsql-13/bin/pg_ctl -D /var/lib/pgsql/13/data stop
waiting for server to shut down.... done
server stopped
[postgres@test-machine01 ~]$
[postgres@test-machine01 ~]$
[postgres@test-machine01 ~]$  /usr/pgsql-12/bin/pg_ctl -D /var/lib/pgsql/12/data status
pg_ctl: no server running
[postgres@test-machine01 ~]$  /usr/pgsql-13/bin/pg_ctl -D /var/lib/pgsql/13/data status
pg_ctl: no server running
[postgres@test-machine01 ~]$
[postgres@test-machine01 ~]$   ps -ef|grep postmaster
postgres  49637  49477  0 13:25 pts/1    00:00:00 grep --color=auto postmaster
[postgres@test-machine01 ~]$
[postgres@test-machine01 ~]$


Step 5. Perform upgrade check: Always run the pg_upgrade binary of the new server. Use option –help to get full list of options. Use option -c with pg_upgrade to verify if Cluster is compatible for upgrade.

[postgres@test-machine01 data]$ /usr/pgsql-13/bin/pg_upgrade --help
pg_upgrade upgrades a PostgreSQL cluster to a different major version.

Usage:
  pg_upgrade [OPTION]...

Options:
  -b, --old-bindir=BINDIR       old cluster executable directory
  -B, --new-bindir=BINDIR       new cluster executable directory (default
                                same directory as pg_upgrade)
  -c, --check                   check clusters only, don't change any data
  -d, --old-datadir=DATADIR     old cluster data directory
  -D, --new-datadir=DATADIR     new cluster data directory
  -j, --jobs=NUM                number of simultaneous processes or threads to use
  -k, --link                    link instead of copying files to new cluster
  -o, --old-options=OPTIONS     old cluster options to pass to the server
  -O, --new-options=OPTIONS     new cluster options to pass to the server
  -p, --old-port=PORT           old cluster port number (default 50432)
  -k, --link                    link instead of copying files to new cluster

Before running pg_upgrade you must:
  create a new database cluster (using the new version of initdb)
  shutdown the postmaster servicing the old cluster
  shutdown the postmaster servicing the new cluster

When you run pg_upgrade, you must provide the following information:
  the data directory for the old cluster  (-d DATADIR)
  the data directory for the new cluster  (-D DATADIR)
  the "bin" directory for the old version (-b BINDIR)
  the "bin" directory for the new version (-B BINDIR)

For example:
  pg_upgrade -d oldCluster/data -D newCluster/data -b oldCluster/bin -B newCluster/bin
or
  $ export PGDATAOLD=oldCluster/data
  $ export PGDATANEW=newCluster/data
  $ export PGBINOLD=oldCluster/bin
  $ export PGBINNEW=newCluster/bin
  $ pg_upgrade

Report bugs to <[email protected]>.
PostgreSQL home page: <https://www.postgresql.org/>
[postgres@test-machine01 data]$

[postgres@test-machine01 ~]$
[postgres@test-machine01 ~]$   /usr/pgsql-13/bin/pg_upgrade --old-datadir "/var/lib/pgsql/12/data" --new-datadir "/var/lib/pgsql/13/data" --old-bindir "/usr/pgsql-12/bin" --new-bindir "/usr/pgsql-13/bin" -c
Performing Consistency Checks
-----------------------------
Checking cluster versions                                   ok
Checking database user is the install user                  ok
Checking database connection settings                       ok
Checking for prepared transactions                          ok
Checking for system-defined composite types in user tables  ok
Checking for reg* data types in user tables                 ok
Checking for contrib/isn with bigint-passing mismatch       ok
Checking for presence of required libraries                 ok
Checking database user is the install user                  ok
Checking for prepared transactions                          ok
Checking for new cluster tablespace directories             ok

*Clusters are compatible*
[postgres@test-machine01 ~]$


Step 6. Perform actual upgrade: Once Check step is successfully executed without any error. We can proceed with the actual upgrade. In this step, we will not use option -c. Also, you need to decide to go with link mode (-k ) or default copy mode. 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. Once the upgrade is done 2 shell script files will be generated to analyze analyze_new_cluster.sh and to delete the old cluster delete_old_cluster.sh.

[postgres@test-machine01 ~]$
[postgres@test-machine01 ~]$     /usr/pgsql-13/bin/pg_upgrade --old-datadir "/var/lib/pgsql/12/data" --new-datadir "/var/lib/pgsql/13/data" --old-bindir "/usr/pgsql-12/bin" --new-bindir "/usr/pgsql-13/bin"
Performing Consistency Checks
-----------------------------
Checking cluster versions                                   ok
Checking database user is the install user                  ok
Checking database connection settings                       ok
Checking for prepared transactions                          ok
Checking for system-defined composite types in user tables  ok
Checking for reg* data types in user tables                 ok
Checking for contrib/isn with bigint-passing mismatch       ok
Creating dump of global objects                             ok
Creating dump of database schemas
                                                            ok
Checking for presence of required libraries                 ok
Checking database user is the install user                  ok
Checking for prepared transactions                          ok
Checking for new cluster tablespace directories             ok

If pg_upgrade fails after this point, you must re-initdb the
new cluster before continuing.

Performing Upgrade
------------------
Analyzing all rows in the new cluster                       ok
Freezing all rows in the new cluster                        ok
Deleting files from new pg_xact                             ok
Copying old pg_xact to new server                           ok
Setting oldest XID for new cluster                          ok
Setting next transaction ID and epoch for new cluster       ok
Deleting files from new pg_multixact/offsets                ok
Copying old pg_multixact/offsets to new server              ok
Deleting files from new pg_multixact/members                ok
Copying old pg_multixact/members to new server              ok
Setting next multixact ID and offset for new cluster        ok
Resetting WAL archives                                      ok
Setting frozenxid and minmxid counters in new cluster       ok
Restoring global objects in the new cluster                 ok
Restoring database schemas in the new cluster
                                                            ok
Copying user relation files
                                                            ok
Setting next OID for new cluster                            ok
Sync data directory to disk                                 ok
Creating script to analyze new cluster                      ok
Creating script to delete old cluster                       ok
Checking for extension updates                              ok

Upgrade Complete
----------------
Optimizer statistics are not transferred by pg_upgrade so,
once you start the new server, consider running:
    ./analyze_new_cluster.sh

Running this script will delete the old cluster's data files:
    ./delete_old_cluster.sh
[postgres@test-machine01 ~]$

[postgres@test-machine01 ~]$
[postgres@test-machine01 ~]$ ./analyze_new_cluster.sh
This script will generate minimal optimizer statistics rapidly
so your system is usable, and then gather statistics twice more
with increasing accuracy.  When it is done, your system will
have the default level of optimizer statistics. 

If you have used ALTER TABLE to modify the statistics target for
any tables, you might want to remove them and restore them after
running this script because they will delay fast statistics generation.

If you would like default statistics as quickly as possible, cancel
this script and run:
    "/usr/pgsql-13/bin/vacuumdb" --all --analyze-only

vacuumdb: processing database "postgres": Generating minimal optimizer statistics (1 target)
vacuumdb: processing database "sample1": Generating minimal optimizer statistics (1 target)
vacuumdb: processing database "sample2": Generating minimal optimizer statistics (1 target)
vacuumdb: processing database "sample3": Generating minimal optimizer statistics (1 target)
vacuumdb: processing database "sample4": Generating minimal optimizer statistics (1 target)
vacuumdb: processing database "sample5": Generating minimal optimizer statistics (1 target)
vacuumdb: processing database "sample6": Generating minimal optimizer statistics (1 target)
vacuumdb: processing database "sample7": Generating minimal optimizer statistics (1 target)
vacuumdb: processing database "template1": Generating minimal optimizer statistics (1 target)
vacuumdb: processing database "postgres": Generating medium optimizer statistics (10 targets)
vacuumdb: processing database "sample1": Generating medium optimizer statistics (10 targets)
vacuumdb: processing database "sample2": Generating medium optimizer statistics (10 targets)
vacuumdb: processing database "sample3": Generating medium optimizer statistics (10 targets)
vacuumdb: processing database "sample4": Generating medium optimizer statistics (10 targets)
vacuumdb: processing database "sample5": Generating medium optimizer statistics (10 targets)
vacuumdb: processing database "sample6": Generating medium optimizer statistics (10 targets)
vacuumdb: processing database "sample7": Generating medium optimizer statistics (10 targets)
vacuumdb: processing database "template1": Generating medium optimizer statistics (10 targets)
vacuumdb: processing database "postgres": Generating default (full) optimizer statistics
vacuumdb: processing database "sample1": Generating default (full) optimizer statistics
vacuumdb: processing database "sample2": Generating default (full) optimizer statistics
vacuumdb: processing database "sample3": Generating default (full) optimizer statistics
vacuumdb: processing database "sample4": Generating default (full) optimizer statistics
vacuumdb: processing database "sample5": Generating default (full) optimizer statistics
vacuumdb: processing database "sample6": Generating default (full) optimizer statistics
vacuumdb: processing database "sample7": Generating default (full) optimizer statistics
vacuumdb: processing database "template1": Generating default (full) optimizer statistics

Done
[postgres@test-machine01 ~]$


Step 7. Start and verify PostgreSQL-13 Cluster after upgrade: Once upgrade and analyze steps are done. Login to PostgreSQL-13 cluster and verify all user’s objects available after the upgrade.

[postgres@test-machine01 data]$
[postgres@test-machine01 data]$ /usr/pgsql-13/bin/pg_ctl -D /var/lib/pgsql/13/data start
waiting for server to start....2021-10-11 13:29:37.389 +03 [50205] LOG:  redirecting log output to logging collector process
2021-10-11 13:29:37.389 +03 [50205] HINT:  Future log output will appear in directory "log".
 done
server started
[postgres@test-machine01 data]$
[postgres@test-machine01 data]$

[postgres@test-machine01 data]$ psql
Type "help" for help.

postgres=# 
postgres=# select version();
                                                 version
---------------------------------------------------------------------------------------------------------
 PostgreSQL 13.4 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 4.8.5 20150623 (Red Hat 4.8.5-44), 64-bit
(1 row)

postgres=#

postgres=#
postgres=# \l+
                                                                    List of databases
   Name    |  Owner   | Encoding |   Collate   |    Ctype    |   Access privileges   |  Size   | Tablespace |                Description
-----------+----------+----------+-------------+-------------+-----------------------+---------+------------+--------------------------------------------
 postgres  | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |                       | 8133 kB | pg_default | default administrative connection database
 sample1   | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |                       | 16 MB   | pg_default |
 sample2   | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |                       | 16 MB   | pg_default |
 sample3   | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |                       | 16 MB   | pg_default |
 sample4   | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |                       | 15 MB   | pg_default |
 sample5   | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |                       | 15 MB   | pg_default |
 sample6   | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |                       | 15 MB   | tbls01     |
 sample7   | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |                       | 15 MB   | tbls02     |
 template0 | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 | =c/postgres          +| 8157 kB | pg_default | unmodifiable empty database
           |          |          |             |             | postgres=CTc/postgres |         |            |
 template1 | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 | postgres=CTc/postgres+| 8133 kB | pg_default | default template for new databases
           |          |          |             |             | =c/postgres           |         |            |
(10 rows)

postgres=#
postgres=# \db+
                           List of tablespaces
    Name    |  Owner   |   Location    | Access privileges | Description
------------+----------+---------------+-------------------+-------------
 pg_default | postgres |               |                   |
 pg_global  | postgres |               |                   |
 tbls01     | postgres | /u01/pg1_tbls |                   |
 tbls02     | postgres | /u01/pg2_tbls |                   |
(4 rows)

postgres=#
postgres=# \du+
                                                                      List of roles
         Role name         |                   Attributes                   |                          Member of                           | Description
---------------------------+------------------------------------------------+--------------------------------------------------------------+-------------
 app_user1                 |                                                | {}                                                           |
 app_user2                 |                                                | {}                                                           |
 app_user3                 |                                                | {}                                                           |
 postgres                  | Superuser, Create role, Create DB, Replication | {}                                                           |

postgres=#


This document is just for learning purpose and always validate in the LAB environment first before applying in the LIVE environment.


Hope so you like this article!
Please share your valuable feedback/comments/subscribe and follow us below and don’t forget to click on the bell icon to get the most recent update. Click here to understand more about our pursuit.


Related Articles

, ,

Loading

How useful was this post?

Click on a star to rate it!

Average rating / 5. Vote count:

No votes so far! Be the first to rate this post.

As you found this post useful...

Follow us on social media!

We are sorry that this post was not useful for you!

Let us improve this post!

Tell us how we can improve this post?

Jamsher Khan

🌐

Hello and welcome to DBsGuru,I’m Jamsher Khan working as Senior Oracle DBA based in KSA-Jeddah, I have working experience in Oracle DBA, SQL Server, MySql, PostgreSQL, Linux, Golden Gate, ODA.Thanks for the visits!Share Learn Grow!

Leave a Reply

Your email address will not be published. Required fields are marked *