# 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:
- Environment variables (opens new window).
- 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
# The process
When it launches, Cosmovisor does the following:
- Starts and launches your node executable, for, example
- Polls regularly for potential upgrade information, for instance in
Note how this file is in the
data folder and created by the
x/upgrade module (opens new window) when appropriate.
upgrade-info.jsonis available, waits for the executable to stop on its own, in effect after it has committed all states at the given block height.
- 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
- Exchanges the symbolic link to the
currentexecutable for the new one.
- 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.
To summarize, this section has explored:
- The implications of an eventual need to upgrade or migrate a running network, with the attendant necessity of all its nodes being simultaneously down.
- How to install and set up Cosmovisor, a tool used to reduce downtime and improve the smoothness of an upgrade or migration (by comparison with a "manual" process).
- How to practice using Cosmovisor by upgrading your testnet(s) before you attempt to upgrade your mainnet.