Updating self-hosted Retool

Learn how to upgrade your self-hosted Retool deployment.

There are a few high-level phases to work through to update a self-hosted version of Retool. These include:

Preparing for the update

  • Choose the version of Retool to upgrade to. Learn about the differences between your current Retool version and the new version.
  • Pick a set of your Retool apps to use to test the new version.
  • Schedule downtime for the upgrade.

1. Choose the version

Check the Releases page to see each version of Retool and its changelog. Read the changelogs between your current version and the version you're upgrading to. Changelogs also contain instructions for managing deprecated features.

Whenever possible, upgrade to the most recent version. In some cases, if a feature is deprecated in the newest version, you might want to upgrade to the version just before the latest so you can take time to migrate off the deprecated feature before upgrading to the newest version.

2. Pick apps to test with

Here are some suggestions for picking the apps.

  • Include your most critical apps if possible.
  • Select apps that use a variety of Resources and Components.
  • Select at least three apps.

3. Schedule downtime for the upgrade

Retool recommends scheduling downtime, even if it’s for a short time period or during off-peak hours. If you're running Retool on a single container or node, there will be downtime during the upgrade. During this time, explain to users that they shouldn't use or edit apps during the upgrade. You might want to make an announcement to your users at a few days in advance.

If you run multiple instances—for example, dev, staging, and production instances—you might consider scheduling separate downtimes for each: for example, upgrading dev first, and then staging, and then production.

The amount of time to schedule varies. For example, point-in-time recovery and taking database snapshots can impact the timeframe. If you're upgrading for the first time, make sure to work through the next section to establish a baseline.

Pre-update testing

This section includes some recommendations but you should customize testing to fit your installation. Pre-update testing includes:

  • Spinning up a separate, temporary Retool instance and seed it with your current apps.
  • Installing the new version on the temporary instance.
  • Testing your apps on the new version.

By running your upgrade on a temporary instance, you can test out the upgrade process in a low-risk environment and build confidence for the upgrades in your main Retool instances. As you test, you might want to write or update an internal upgrade runbook. Your runbook can include specific context and commands for your company and become a resource for other colleagues.

Testing on a sandbox instance is particularly recommended if:

  • You usually run a single instance of Retool.
  • Your primary Retool instances are heavily used.
  • You have done a moderate to high amount of customization in your Retool apps. For example, using custom CSS, custom components, or Retool app development workflows.
  • Your current version of Retool is more than two months behind the most recent version.

1. Spin up a temporary Retool instance

You can find instructions for spinning up a Retool instance in our deployment guide but you should finish reading this section before getting started.

If you have a permanent sandbox instance, you can use that instance instead of spinning up new infrastructure. You’ll likely still make use of the instructions below for seeding the instance with the latest version of your test apps.

The database

Retool recommends seeding the temporary instance with your current apps by copying your existing Retool instance’s PostgreSQL database. If you run multiple instances, select the instance that you use when developing apps. It’s important to use a copy of your existing database. Don't connect to your existing Retool database: it will likely be altered in the course of upgrading and testing because upgrades often include database migrations.

Copy the data

To make a copy of the data, you can use the built-in PostgreSQL pg_dump command to dump the database to a file, and then create a new database seeded with that file. There's an example of this on Retool's storage database page. However, if you're using a managed PostgreSQL database, your cloud provider likely has a way to make a copy of the database and load it into a new database.

Allow the temporary instance to read the copied database

For the new Retool instance to read the contents of the database, you must set the ENCRYPTION_KEY and USE_GCM_ENCRYPTION environment variables in the new Retool instance to the same value as in your current Retool instance. If you use Docker, you can run these commands after spinning up the instance.

  1. Run sudo docker-compose down.
  2. Update the docker.env file to set ENCRYPTION_KEY and USE_GM_ENCRYPTION to the desired value.
  3. Run sudo docker-compose up -d.

Initial Retool version

As the starting point, install your current version of Retool. You can find your current version by clicking the question mark in the lower right corner of the application editor. Use this version number in your deployment template files for the new instance.

General setup

You might be able to use a simpler setup than what you usually run. For example, even if you usually run on Kubernetes, you might want to spin up the equivalent of a single AWS EC2 machine. This may be a good choice for you if you are highly confident in the mechanics of upgrading on your usual infrastructure, and primarily want to test the functionality of your Retool apps with the new Retool software.

2. Install the new version

In this step, run the upgrade on the temporary Retool instance. Follow the same steps used for production.

3. Test your apps

Make sure the core functionality of your apps work as expected. You might want to write some test cases or a checklist to help with this process.

If your tests pass, you can move on to upgrading your production instances. If you find any issues, you can reach out to the Retool Support team for assistance.


To complete the installation, you need to:

  • Remind your users about the start of the scheduled downtime.
  • Create a backup of your Retool instances and then install the new version.
  • Notify your users after the upgrade is complete.

1. Remind your users about the downtime

As a courtesy to your users, it’s helpful to send an additional announcement to them shortly before you begin the downtime. If you're using the Git Syncing feature to sync apps across multiple Retool instances, Retool recommends not promoting any of your apps between instances while you do the upgrade. It's better to upgrade instances individually. For example, you might upgrade your development instance first and then move to staging, and then production.

2. Create a backup

You need to create a backup for each of your Retool instances so that you can restore them if needed.

If you're deployed on a cloud platform like AWS, the cloud provider might have a convenient way to backup all of the state of your running instances. For example, AWS offers a way to backup EC2 instances as an AMI.

If you would like to take the backup in a platform-agnostic way, here are the essential pieces:

  • Retool Postgres database: If your Postgres database is managed outside of Retool and has point-in-time recovery enabled, you already have backups. Otherwise, you can enable point-in-time recovery, or take a snapshot of the database.
  • Environment variables: The most important environment variable to make sure you have stored in a safe place is the ENCRYPTION_KEY. You should also store any environment variables specific to your Retool instance. For example, in a Docker deployment, you can copy the contents of your docker.env file.
  • If you're using Git Syncing and updating your read-write instance, you can create a backup by creating a new branch based off the current branch. For example, if your instance writes to a branch called dev, you can create a branch that is a copy of that branch, called dev-backup-<date>, and push that to your Git origin.

3. Install the new version

Retool releases can be pulled from Docker Hub. How you update depends on how you’ve deployed Retool.

Docker Compose deployment

  1. In the first line of the Dockerfile, update the version number to the new version. You should see something like FROM tryretool/backend:X.Y.Z. Replace X.Y.Z with the version number.
  2. Then run the included update script in the retool-onpremise directory:

Kubernetes deployment

  1. To update Retool on Kubernetes, use the following command and replace X.Y.Z with the version number or named tag that you want to upgrade to.
kubectl set image deploy/api api=tryretool/backend:X.Y.Z

If you're running a multi-container deployment, check out our guide on the order in which to upgrade your containers.

4. Notify your users after the upgrade is complete

As a courtesy to your users, it’s helpful to send an announcement to them to let them know they can use Retool again.