dokku/dokku-postgres
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: document the process of upgrading major postgres versions

Browse Source 
While it would be nice to automatically handle this, there is a ton of pain in doing so. Rather than being smart about it, document the process so that users can make rational decisions about their upgrade process.

Closes dokku/dokku-postgres#219
This commit is contained in:
Jose Diaz-Gonzalez
2021-09-13 01:26:58 -04:00
parent b8a8b139f9
commit 5855d1bdd5
2 changed files with 61 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
README.md
View File

@@ -401,6 +401,37 @@ You can upgrade an existing service to a new image or image-version:
dokku postgres:upgrade lollipop dokku postgres:upgrade lollipop
``` ```
Postgres does not handle upgrading data for major versions automatically (eg. 11 => 12). Upgrades should be done manually. Users are encouraged to upgrade to the latest minor release for their postgres version before performing a major upgrade.
While there are many ways to upgrade a postgres database, for safety purposes, it is recommended that an upgrade is performed by exporting the data from an existing database and importing it into a new database. This also allows testing to ensure that applications interact with the database correctly after the upgrade, and can be used in a staging environment.
The following is an example of how to upgrade a postgres database named `lollipop-11` from 11.13 to 12.8.
```shell
# stop any linked apps
dokku ps:stop linked-app
# export the database contents
dokku postgres:export lollipop-11 > /tmp/lollipop-11.export
# create a new database at the desired version
dokku postgres:create lollipop-12 --image-version 12.8
# import the export file
dokku postgres:import lollipop-12 < /tmp/lollipop-11.export
# run any sql tests against the new database to verify the import went smoothly
# unlink the old database from your apps
dokku postgres:unlink lollipop-11 linked-app
# link the new database to your apps
dokku postgres:link lollipop-12 linked-app
# start the linked apps again
dokku ps:start linked-app
```
### Service Automation ### Service Automation
Service scripting can be executed using the following commands: Service scripting can be executed using the following commands:

30
docs/upgrade.md Normal file
View File

@@ -0,0 +1,30 @@
Postgres does not handle upgrading data for major versions automatically (eg. 11 => 12). Upgrades should be done manually. Users are encouraged to upgrade to the latest minor release for their postgres version before performing a major upgrade.
While there are many ways to upgrade a postgres database, for safety purposes, it is recommended that an upgrade is performed by exporting the data from an existing database and importing it into a new database. This also allows testing to ensure that applications interact with the database correctly after the upgrade, and can be used in a staging environment.
The following is an example of how to upgrade a postgres database named `lollipop-11` from 11.13 to 12.8.
```shell
# stop any linked apps
dokku ps:stop linked-app
# export the database contents
dokku postgres:export lollipop-11 > /tmp/lollipop-11.export
# create a new database at the desired version
dokku postgres:create lollipop-12 --image-version 12.8
# import the export file
dokku postgres:import lollipop-12 < /tmp/lollipop-11.export
# run any sql tests against the new database to verify the import went smoothly
# unlink the old database from your apps
dokku postgres:unlink lollipop-11 linked-app
# link the new database to your apps
dokku postgres:link lollipop-12 linked-app
# start the linked apps again
dokku ps:start linked-app
```