Hard domain and binary migration in one

Tutorials and Guides
, ,
1

Background

With the release of 2.9 PV versions 3 and 4 are no longer supported. This means that in order to make use of 2.9s great new features a combined binary and protocol version upgrade may be required in one process.

The below demonstrates how to migrate from a sync domain running on a 2.3, 2.4, 2.5, 2.6, 2.7 or 2.8 release and protocol version 3 or 4 to a new sync domain running on the 2.9 release and protocol version 5.

Specifically in this demo we will migrate from 2.3.20 PV 3 to 2.9.1 PV 5

Docs

Code

Note: This demo uses DA’s enterprise docker images for 2.9 and therefore you will need credentials to the Digital Asset Artifactory to run the code.

Clone the source code

git clone https://github.com/bradley-da/canton-protocol-upgrade.git --branch one-step-2.9-migration --single-branch one-step-2.9-migration
cd one-step-2.9-migration
daml studio

Areas of Note

  • ./canton-scripts: holds all the canton scripts used to run the migration process
  • ./configs: The configuration files for both the 2.3 and the 2.9 canton components
  • docker-compose.yaml: All the canton components and their binaries as well as services to run the various scripts

Walkthrough

Setup:

  1. Build the required dar
daml build
  1. Start the domain and participants
docker compose --profile startup up -d
  1. Upload contracts to the participants once startup has completed
docker compose run --rm contracts

Note: All the below commands use canton scripts to automate the migration process.

If instead you’d prefer to run the commands manually through a canton console:

docker compose run --rm console

Upgrade Process:

  1. Start a new domain with the new protocol version. Note this domain must be completely independent of the old domain.
docker compose --profile new-domain up -d
  1. Run the canton script ./canton-scripts/remove-resources.canton which saves the resource limits of the participants to file for restoring after the upgrade process and then set the limits to 0.
docker compose run remove_resources
  1. Bring down the participants
docker compose down participanta participantb
  1. Backup the databases. Note: before migrating it is also recommended to VACUUM the databases.
docker cp ./configs/postgres/backup.sql canton-postgres:/docker-entrypoint-initdb.d/backup.sql
docker exec -u postgres canton-postgres psql -f docker-entrypoint-initdb.d/backup.sql
  1. Restart participants with new binaries and migrate the databases. For this demo the configuration option Canton.participants.participant1.storage.parameters.migrate-and-start = yes has been set within the participants config files. This allows for automatic schema migrations on startup. Therefore the nodes simply need to be restarted with the new binaries and db migrations are done automatically.
docker compose --profile updated-participants up -d
  1. Run the canton script ./canton-scripts/migrate.canton. This script will:
  • Disconnect the participants from all domains
  • Set the sequencer connection configuration for the new domain
  • Migrate the participants to the new domain
  • Connect the participants to the the new domain
docker compose run migrate
  1. Run the canton script ./canton-scripts/restore-resources-and-test. This script will:
  • Restore the resource limits on participants
  • Run cross participant pings to ensure the protocol is healthy
docker compose run restore_and_test
  1. Remove the old existing domain
docker compose down olddomain
  1. Upload additional contracts to the participants as a final test.
docker compose run --rm contracts
  1. Enjoy 2.9!

Clean up

Remove all containers and underlying volumes

docker compose --profile all -v down --remove-orphans

Source Code

https://github.com/bradley-da/canton-protocol-upgrade/tree/one-step-2.9-migration

3 Likes