PostGIS upgrade with Ubuntu 20.04.02

09.2021 / Category: / Tags: |

Last time, we installed PostGIS on top of PostgreSQL. Today, I will complement this article by describing how to upgrade PostGIS on Ubuntu. A detailed description can be found at and should be referred to in parallel.

Let me first define our scenario and goal:

An artificial customer wants his PostGIS-enabled PostgreSQL 13 cluster running on Ubuntu 20.04.02 to be upgraded. The current PostGIS extension states version 2.5 and should be upgraded to its latest version. At the customer site, one spatial database serving both vector and raster data must be upgraded to its successor.

It should be highlighted here, that PostGIS upgrades can be accomplished in two ways, namely a soft or hard upgrade. A soft upgrade refers to only the binary upgrade of a PostGIS’ extension, a hard upgrade implies dumping and restoring the whole database in a fresh PostGIS enabled database. From this description, it would be natural to choose the soft upgrade path by default. Unfortunately, a soft upgrade is not possible all the time, especially when PostGIS objects' internal storage changes. So how do we know which path to follow? Fortunately, PostGIS release notes explicitly state when a hard upgrade is required. Seems we are in luck and a soft upgrade is sufficient for our use case 😊. For completeness, the annex contains needed steps to carry out a hard upgrade too.

Now, let's break down this task in the following steps:

  1. Status quo assessment
  2. PostGIS upgrade on OS level
  3. PostGIS upgrade on database level

Status quo

Let's start and cross-check statements with reality by listing installed packages on the OS level.

From the listing, we realize that PostGIS extension 2.5 has been installed on top of PostgreSQL 13.

Verify PostGIS extension

It makes sense to extend our test by verifying that our PostGIS extension has been registered correctly within PostgreSQL’s ecosystem. This can be quickly checked on the cluster level by reviewing the related system catalogs or querying pg_available_extensions as a shortcut.

Surprise, surprise - results of our query confirm the availability of PostGIS extension(s) in version 2.5 only. Finally, it is not only interesting to list available extensions on a cluster level but rather explicitly the listing installed extensions on the database level.

Use dx

To do so, let’s open up a psql session, connect to our database and finally utilize dx to quickly grab the installed extensions.

How to get more detailed info on the PostGIS extension

Additionally, querying postgis_full_version() returns even more detailed information about our PostGIS extension.

I, by the way, recommend using all available mechanisms to assess the status on the cluster and database level to gain a holistic picture of the system.

PostGIS Upgrade on the OS level

After assessing our cluster, we can move forward and install the latest PostGIS packages for PostgreSQL 13 on Ubuntu 20.

Let's quickly ensure that the required PostGIS package is accessible by grabbing the available packages utilizing apt-cache search.

Install the latest PostGIS 3 version

Seems we are fine and can install the latest PostGIS 3 version as follows:

Verify packages registration within PostgreSQL

It can't hurt to replay what I mentioned in the beginning: query installed PostgreSQL packages on the OS level (1) and verify packages registration (2) within PostgreSQL.

PostGIS upgrade on the database level

As the requirements are fulfilled, we can proceed and upgrade PostGIS within our database. Let’s open up a psql session, connect to our database and call PostGIS_Extensions_Upgrade(). Please note that PostGIS_Extensions_Upgrade() is only available from 2.5 upwards. Upgrading from prior versions imply manual steps (see annex) or upgrading to 2.5 as intermediate version. From version 3 PostGIS separates functionality for vector and raster in different extensions - PostGIS_Extensions_Upgrade() takes care of this fact.

Upgrade and install PostGIS_Raster

Reading the query result, it seems we are not done and the PostGIS raster extension must be upgraded separately. This should be necessary only when moving from PostGIS version <3 to PostGIS 3. The reason behind this is that raster functionality has been moved to a separate extension named PostGIS_Raster. To upgrade and install PostGIS_Raster, a second call to PostGIS_Extensions_Upgrade() does the trick.

Finally, let's utilize dx again to see what we achieved.

Conclusion on PostGIS Upgrade

Congratulations! You made it here and followed my partially repetitive steps to upgrade your PostGIS installation. It should be stated that depending on the PostGIS version and OS, upgrades can turn out to be tricky and cause headaches and sleepless nights. Do not forget to backup and assess your system comprehensively before initiating an upgrade!


Manual soft upgrade from PostGIS versions <2.5 (PostgreSQL <=12*)


*-From unpackaged removed by PostgreSQL version 13.0,

Semi-automatic soft upgrade from PostGIS versions <2.5


Hard upgrade from PostGIS version 2.5


1. Create a new database and enable PostGIS

2. Dump and restore database

3. Rename databases

In case you'd like to read more about PostGIS, see my post about upgrading PostGIS-related libraries such as GEOS and GDAL.


In order to receive regular updates on important changes in PostgreSQL, subscribe to our newsletter, or follow us on Twitter, Facebook, or LinkedIn.

0 0 votes
Article Rating
Notify of
1 Comment
Newest Most Voted
Inline Feedbacks
View all comments
2 years ago

This is an essential supplement to PostGIS's own documentation. It succinctly covers the problems I've encountered and their solutions. I can't thank you enough for this demo.

CYBERTEC Logo white
CYBERTEC PostgreSQL International GmbH
Römerstraße 19
2752 Wöllersdorf

+43 (0) 2622 93022-0

Get the newest PostgreSQL Info & Tools

    This site is protected by reCAPTCHA and the Google Privacy Policy & Terms of Service apply.

    CYBERTEC PostgreSQL International GmbH
    Would love your thoughts, please comment.x
    linkedin facebook pinterest youtube rss twitter instagram facebook-blank rss-blank linkedin-blank pinterest youtube twitter instagram