Parsec Server migration

This guide covers the migration procedure for the Parsec server (also called parsec-server).


We consider that you are using the same infrastructure configuration as in the Parsec Server installation guide. Adapt this guide to your own situation.

Updating to a newer version


Before updating to a newer version, make sure to back up the database, in case you need to roll back the update.

In this guide, we will migrate parsec-server from version v2.15.0 to v2.16.0.

  1. Update the parsec-server’s docker image tag of in docker-compose file (parsec-server.docker.yaml):

2  # ...
4  parsec-server:
5    image:
6    # ...

You need to change the used tag (at line 5) to v2.16.0.

  1. List the pending migrations to be applied:

docker compose -f parsec-server.docker.yaml run parsec-server migrate --dry-run

The output should look like this:

0001_initial.sql (already applied)
0002_add_migration_table.sql (already applied)
0003_human_handle.sql (already applied)
0004_invite.sql (already applied)
0005_redacted_certificates.sql (already applied)
0006_outsider_enabled.sql (already applied)
0007_users_limit.sql (already applied)
0008_apiv1_removal.sql (already applied)
0009_add_realm_user_change_table.sql (already applied)
0010_add_pki_certificate_table.sql (already applied)
0011_add_sequester_tables.sql (already applied)
0012_add_sequester_webhook.sql (already applied)
0013_add_shamir_recovery.sql ✔
0014_add_realm_archiving.sql ✔


This output is provided as an example. Don’t expect it to match your output.

The lines ending with already applied are migrations already present on the database whereas the one ending with are migrations to be applied.

  1. Apply the database migration:

docker compose -f parsec-server.docker.yaml run parsec-server migrate
  1. Restart the parsec-server container:

docker compose -f parsec-server.docker.yaml restart parsec-server

Rollback to a previous version


Rollback is currently limited in Parsec. The only possible way to rollback is to use the previous database backup. So you will lose the delta of backup vs current database.

To roll back to a previous version, let’s say we want to downgrade parsec-server from version v2.16.0 to v2.15.0.

  1. Downgrade the parsec-server’s docker image tag in the docker-compose file (parsec-server.docker.yaml). Like in Update the parsec-server tag change the tag v2.16.0 to v2.15.0.

  2. Replace the current database with the backup on the Postgres database.

  3. Restart the parsec-server container