Skip to main content

Self-hosted Retool upgrade best practices

Learn about best practices for upgrading your self-hosted Retool deployment.

This guide provides high-level recommendations and best practices for updating Retool for production deployments. For deployment-specific installation instructions, use the deployment guide for your Retool deployment type.

Prepare for the update​

Before you upgrade, choose the version to upgrade to and schedule downtime for the upgrade.

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.

Keep your deployment instance up-to-date with the latest release. If your current version is more than 10 versions behind, Retool recommends you upgrade incrementally (e.g., 3.0, 3.10, 3.20...) and verify each installation.

Schedule downtime​

If you run Retool on a single container or node, there will be downtime during the upgrade. If you run a multi-container deployment, see the Scale Retool infrastructure guide to learn about zero-downtime upgrades. If you run multiple instances, consider scheduling separate downtimes for each: for example, upgrade dev first, then staging, and then production.

Schedule the downtime in advance, even if it's a short time period or during off-peak hours. Clearly communicate to users that they should not use or edit apps during the upgrade. It may be helpful to make an announcement to users a few days in advance.

The amount of time to schedule varies. For example, point-in-time recovery and taking database snapshots can impact the duration.

Test apps on a sandbox instance​

Testing on a sandbox instance is not required, but it is 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.

Pre-update testing includes spinning up a separate, temporary Retool instance with the new version and testing it with your current apps. This allows you test the upgrade process in a low-risk environment and build confidence for upgrading your production instances.

1. Spin up a temporary instance​

Follow the instructions in your deployment guide for spinning up a new instance, or use an existing sandbox instance. First, install your current version of Retool.

Copy your database​

Retool recommends seeding the temporary instance with your current apps by copying your existing instance’s PostgreSQL database to the temporary instance. It’s important to use a copy of your existing database. Don't connect to your existing Retool database: upgrades often include database migrations, which may alter the database.

Refer to your database provider for instructions on backing up your database to a file and restoring the new database with that file.

When you connect your new instance to the database, set the ENCRYPTION_KEY and USE_GCM_ENCRYPTION environment variables to the same value as in your existing Retool instance.

2. Install the new version​

Run the upgrade on the temporary Retool instance, following the upgrade steps for your deployment type.

3. Test your apps​

Test the new instance on your most critical apps, and apps which use a variety of resources and components. You might want to write test cases, a checklist, or an internal upgrade runbook to help standardize this process. This can include specific context and commands and become a resource for your team.

After your tests pass, upgrade your production instances.

Upgrade Retool​

During Retool upgrades, remind users about the downtime and completed upgrades, and create backups of your instances. Upgrade instances sequentially, starting with the development instance, followed by staging and production.

1. Remind your users about the downtime​

As a courtesy, it’s helpful to send an announcement to your users shortly before you begin the downtime. If you use Source Control, you should also avoid merging any pull requests while you perform the upgrade.

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 upgrading in batches, create a backup before each batch.

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

On all deployments:

  • Back up your Retool PostgreSQL database. If your PostgreSQL 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.
  • Copy and store your ENCRYPTION_KEY environment variable, along with any environment variables specific to your instance, in a safe place.

3. Install the new version​

Retool releases can be pulled from Docker Hub. See the deployment guide for your instance for detailed instructions.

After installation, Retool recommends manually testing the deployment to verify it was successful. You can use the release notes to better understand what has changed and what to test. Depending on how you're using Retool, you might want to verify your apps, queries, and workflows work as expected. If you're upgrading in batches, test the deployment after each batch.

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.