New product announcement 🎉 Satori - LiveOps to know your players, deliver features, run experiments and schedule events

Upgrade Nakama

When upgrading to a new version of Nakama, you need to do three things before you run the newer version:

  • Check the Release Notes, in case that version has specific upgrade requirements.
  • Migrate your data to the format supported by the new version of Nakama.
  • Ensure that the client version you’re running is compatible with the server deployed.


As new versions of Nakama, or CockroachDB, become available you might want to upgrade. Docker makes upgrading easy, as all you need to do is pull down a new version of the container image. When upgrading to a new version of Nakama, the process in the docker-compose.yml performs a migration of your data to the new database schema automatically.

You can pull the most recent Nakama image and allow Docker Compose to perform the data migration.

docker-compose down # top and remove both the Nakama and CockroachDB containers
docker pull heroiclabs/nakama # download the latest Nakama image
docker-compose up # start the containers (both Nakama and CockroachDB) as fresh installs

And, similarly, here’s how to update the CockroachDB container:

docker pull cockroachdb/cockroach # download the latest CockroachDB image

If you’d like to explicitly run a database schema migration, issue the following command:

docker run heroiclabs/nakama migrate up

Manual upgrade

You can upgrade one node or your whole cluster to the latest version of Nakama by following the instructions below.

For each node in the cluster:

Stop Nakama. If you are using systemd on a Linux setup, the command is:

sudo systemctl stop nakama

Back-up CockroachDB:

cockroach dump nakama > mydatabackup.sql --insecure

Download the latest release and replace the nakama binary with the newer download.

Upgrade the database schema with the following command:

nakama migrate up

To downgrade Nakama you can follow the same procedure, but replace the migration command with the following:

nakama migrate down --limit 1

Start Nakama and verify that the upgraded version is running.

sudo systemctl start nakama