# Prepare and Do Migrations

Your software is now running, which is good, but perhaps over time, a software upgrade vote proposal is passed. You now need to upgrade your node to the next version. The state may need to migrate too. When the state needs to migrate, it is also said that there are breaking changes. This state migration is the upgrade step that takes most of the time.

You can do this whole process somewhat manually, or use a tool to assist you to do it smoothly and fast. This is not an unreasonable concern, since when you perform an upgrade all nodes are simultaneously down.

The main tool is Cosmovisor (opens new window). This is a wrapper executable that in turn launches your node as a subprocess. It watches out for when the node stops and drops upgrade information.

Before you upgrade your mainnet, it is good practice to upgrade your testnet(s). You can also use your mainnet state in a temporary testnet to test the computation needs of your state upgrade.

# Set up Cosmovisor

Cosmovisor is a piece of software that you need to install (opens new window) on your node computer. Its configuration is done via:

1. Environment variables (opens new window).
2. Configuration files and folders (opens new window) that are polled at intervals and which you prepare by hand or via a command (opens new window).

When starting you can pass Cosmovisor command-line arguments that it will pass on to the wrapped Cosmos chain executable. Typically, you use cosmovisor run start, where start is the same as in myprojectd start.

# The process

When it launches, Cosmovisor does the following:

1. Starts and launches your node executable, for, example myprojectd.
2. Polls regularly for potential upgrade information, for instance in .myprojectd/data/upgrade-info.json.

Note how this file is in the data folder and created by the x/upgrade module (opens new window) when appropriate.

3. When upgrade-info.json is available, waits for the executable to stop on its own, in effect after it has committed all states at the given block height.
4. If instructed to by the configuration, downloads the new executable as described in upgrade-info.json. Otherwise looks for it in the configuration folder, for instance .myprojectd/cosmovisor/upgrades/<name>/bin. In this case <name> is picked from upgrade-info.json too.
5. Exchanges the symbolic link to the current executable for the new one.
6. Restarts the node.

When restarting, the node launches its in-place migration (opens new window) process for all modules that have a new version (opens new window).

Downloading an executable is a potential security risk, so although you have the choice of doing it (opens new window) automatically, this is not the default behavior.

Previously, you may have set up your node executable as a service. If you use Cosmovisor, you can in fact replace your node executable in the declaration of your node service. Update its /etc/systemd/system/myprojectd.service service declaration as follows:

After which, you can relaunch your node with:

# Upgrade manually

Cosmovisor is here to help you migrate fast. You can still do it by hand (opens new window).

If you would like to see how to apply what you've learned, you can go straight to the exercise in Simulate a migration in production in Docker.

More specifically, you can jump to:

• Prepare checkers executables, to see how to prepare the before- and after-migration executables.
• Prepare Cosmovisor executable, to see how to find the version and compile the executable of Cosmovisor that will work best with your blockchain executable.
• Make an upgrade proposal, to see the migration take place with an upgrade proposal.