MK IT

Upgrade postgres for nextcloud

March 21, 2026

Errors after upgrading the postgresql container:

FATAL:  password authentication failed for user "oc_admin"

Major Release Upgrades

Upgrading to a new major release requires work, because the internal storage format is subject to change.

Major Upgrade Process

There are multiple ways to perform a major upgrade. We’ll use the following method:

  1. Stop the application container to prevent DB writes.
  2. Create a full DB dump.
  3. Stop the PostgreSQL container.
  4. Rename (backup) the old DB data directory and create a new empty one in its place.
  5. Increment the PostgreSQL version number in your Docker compose file and pull the new image.
  6. Start the updated PostgreSQL container.
  7. Import the DB dump.
  8. Start the application container.
  9. Clean up.

Preparation

  1. Make sure that your application supports the new PostgreSQL version.
  2. Inspect the release notes of the new version you’re upgrading to and the intermediate versions.

Perform the Upgrade

Stop the Application Container

I’m assuming you have a Docker compose file with (at least) one application service and the PostgreSQL service. To stop the application container only, run:

docker compose stop APP_CONTAINER_NAME

Create a Full DB Dump

  1. Look up the name of your PostgreSQL user in your Docker configuration. In my case, it’s simply postgres.

  2. Run the dump command:

    docker exec -it POSTGRESQL_CONTAINER_NAME pg_dumpall -U postgres > dump.sql
  1. Inspect the dump file to make sure it looks correct and is not just an error message.

Stop the PostgreSQL Container

docker compose stop POSTGRESQL_CONTAINER_NAME

Backup the DB Data Directory

Back up the bind-mounted DB data directory db and replace it with a new empty folder:

mv db/ db-old/
mkdir db

Increment the PostgreSQL Version

Edit the Docker compose file, incrementing the image version.

Start the Upgraded PostgreSQL Container

Pull the new image and start the PostgreSQL container:

docker compose pull
docker compose up -d POSTGRESQL_CONTAINER_NAME

Verify the logs. Look for errors and make sure that the PostgreSQL version has actually changed:

docker compose logs --tail 100 --timestamps POSTGRESQL_CONTAINER_NAME

Import the DB Dump

docker exec -i POSTGRESQL_CONTAINER_NAME psql -U postgres < dump.sql

As above, optionally replace postgres with the name of your PostgreSQL user.

Reset user passwords

Connect to PostgreSQL and reset passwords for your nextcloud users:

docker exec -it --user postgres /bin/bash
psql -d <DATABASE-NAME> -U postgres

Inside psql run commands:

postgres=# \password nextcloud
postgres=# \password oc_admin

Restart all docker containers

docker-compose restart

Start the Application Container

docker compose start APP_CONTAINER_NAME
docker compose logs --tail 100 --timestamps

Verify the logs:

docker compose logs --tail 100 --timestamps

Clean Up

Delete the backup directory: rm -rf db-old/
Delete the dump file: rm dump.sql
Delete the old PostgreSQL image: docker image prune -a

Tips

Shell Access in the PostgreSQL Container

Run the following to get an interactive Bash shell in the PostgreSQL container:

docker exec -it POSTGRESQL_CONTAINER_NAME bash