• Task
  • Version · 6.0
  • Manage

Upgrade Liquibase Server

Last updated: September 29, 2026

liquibase-platform update upgrades a running Liquibase Server deployment in place. It pulls the new images, runs the new version's database migrations, and recreates the services. Your data and secrets are left exactly as they are. The server never upgrades itself and cannot schedule an upgrade, so a version changes only when you run this command.

Note: Do not run liquibase-platform install --force to upgrade. That flag regenerates every secret in the deployment, including the database passwords and LIQUIBASE_PLATFORM_ENCRYPTION_KEY. The new passwords will not match your existing database volumes, and anything already encrypted in the secrets database becomes unreadable. Use it only for a from-scratch reinstall.

Procedure

1

Note the version you are running

From the deployment directory, run:

./liquibase-platform status

Version reports the image tag the deployment is running now. Write it down. It is the version you would return to if you have to restore from a backup.

2

Back up both databases and the encryption key

Liquibase Server keeps its data in two PostgreSQL databases, the primary database and the secrets database. The upgrade runs migrations against both, so back up both before you start.

Back up LIQUIBASE_PLATFORM_ENCRYPTION_KEY from the deployment's .env file as well, and store it somewhere secure. Without that key, everything held in the secrets database is unrecoverable.

Note: No command reverses an upgrade, so this backup is the only way back to the version you are running now.

3

Run the upgrade

From the deployment directory, run the upgrade with the version you are moving to.

Be sure to:

  • Replace your_version with the image tag you are upgrading to. For example, 6.0.1

./liquibase-platform update --tag your_version

The command patches only IMAGE_TAG in .env. The database passwords, the auth secret, and LIQUIBASE_PLATFORM_ENCRYPTION_KEY are left alone, and no volumes are removed.

It then pulls the new images, starts the databases and waits for them to report healthy, migrates the primary database and then the secrets database, recreates the services, and waits for the API to pass its health check. Each stage is reported as it runs.

To pull from a registry other than the one recorded in .env, add --registry. That flag also updates IMAGE_REGISTRY in .env.

Be sure to:

  • Replace your_version with the image tag you are upgrading to

  • Replace your_registry_url with the container registry URL provided by Liquibase. For example, registry.liquibase.com

./liquibase-platform update --tag your_version --registry your_registry_url

If the deployment is not in the current directory, add --dir and point it at the directory holding docker-compose.yml.

4

Verify the upgrade

The upgrade runs its own health check and exits with a non-zero status if the API does not come back. Confirm the result yourself as well:

./liquibase-platform status

Version should show the tag you passed, every service should be running, and API Health should report OK. Then sign in to the web app and confirm your projects, connections, and operation history are all still there.

Troubleshooting

The upgrade stops during migration

The command stops and names the database that failed. Your data and volumes are intact, and the databases are left running so you can inspect them. Read the logs, fix the cause, then run the same liquibase-platform update command again.

./liquibase-platform logs --service db

Use --service secrets-db for the secrets database.

The API does not come back

The command reports that the update applied but the API is unreachable, and exits with a non-zero status. Your data is intact. Check the API and proxy logs, then the overall status.

./liquibase-platform logs --service api
./liquibase-platform logs --service nginx
./liquibase-platform status

"No existing installation found"

liquibase-platform update needs an existing .env in the working directory. Add --dir if the deployment lives somewhere other than the current directory. If nothing is installed yet, run liquibase-platform install instead.

Early Access preview installs

When the deployment's .env sets LIQUIBASE_PLATFORM_IMAGE_SOURCE=preview, the upgrade skips both the registry authentication check and the image pull, and uses images that are already on the host. Load the new version's images onto the host before you run the upgrade.

Returning to an earlier version

No command reverses an upgrade. Running liquibase-platform update with an earlier tag does not undo the migrations the newer version applied, so returning to an earlier version means restoring the backup you took before you upgraded.

PreviousHand off what a departing user ownsNextUser access after you upgrade