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 <pgsql-bugs@lists.postgresql.org>.
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
- Oracle Critical Database Patch ID for October 2024 along with enabled Download Link
- Oracle Critical Database Patch ID for July 2024 along with enabled Download Link
- Oracle Critical Database Patch ID for April 2024 along with enabled Download Link
- Oracle Critical Database Patch ID for January 2024 along with enabled Download Link
- Oracle Critical Database Patch ID for October 2023 along with enabled Download Link