How to manually upgrade PostgreSQL¶
Manual upgrade steps¶
To upgrade your PostgreSQL service instance from one version to another, without any downtime, the following steps should be applied to each environment where the upgrade is required. Note that for these instructions to be valid there will be more than one PostgreSQL service availabe. Ensure you select the correct versions when provisioning and deprovisioning the “old” and “new” versions of your PostgreSQL service.
Check the prefix of the current installation. This will be
DEFAULTif it has not been manually changed, but can be anything. For the purposes of these instructions we will refer to it as
Add the PostgreSQL service for the new version to your environment. Assign this the default prefix
Provision the new PosgreSQL service.
Repeat steps 1-3 for each environment.
At this point, the environment is still running on the old version of the database, but the service for the new version is deployed and ready to receive data. The following steps will copy the data from the existing database to the new version.
When a service shows as
Attached, it means that it is ready to use. It does not indicate that it is being used by
your environment. The new version will not be in use until you deploy the changes in step 11.
For more information on how and when services are provisioned and attached, please see the Services documentation: https://docs.divio.com/en/latest/background/services/
Create a backup for the
(Optional) Prepare a backup download and back this up somewhere. This step is not required from a migration perspective, but may be needed to comply with local policies or just useful as a pre-migration snapshot later.
Once the backup has completed, restore it to the
Rename the prefix for the old database version from
Rename the prefix for the new database version from
DEFAULT(or whatever prefix your original PostgreSQL service had prior to the upgrade).
Deploy the environment.
Repeat steps 5-11 for each environment.
Your environment is now using the new PostgreSQL service for the upgraded version.
In order to run the project locally with the upgraded database, a few extra steps are required:
docker-compose.ymlfor the project to use the PostgrSQL image
docker-compose down -vto stop the containers and remove the volumes.
divio app pull db <environment>to pull the updated database from the environment you want locally.
docker-compose upto bring everything up again.
As with all database migrations, there is a small risk here. Any data written to the database in the short time between step 4 (creating the backup of the old database service), and step 9 (deploying the changes) will be lost.
It is the user’s responsibility to assess this risk and act accordingly. If your application rarely writes the database and is mostly reading it, the risk is low. If the only database writes are controlled by you as a Divio user, then this process is safe. If, on the other hand, the users of your application are continually creating new records in the database, this process carries a higher risk.
To mitigate this risk, ensure that your application (or any parts of it that write to the database) is unreachable during the period that these operations are being performed.