Upgrade planning best practices
Learn how to plan and manage Retool upgrades for self-managed instances.
Retool upgrades are low-risk when planned properly, but a poorly timed upgrade or a skipped step can cause downtime or data loss. Establish a repeatable upgrade process before you need to run your first production upgrade.
Choose a release channel
Retool provides two release channels for self-managed instances:
| Channel | Release cadence | Best for |
|---|---|---|
| Stable | A major release roughly every three months, with patch releases between | Most production deployments |
| Edge | Continuous releases with features as they ship | Teams that want early access to features and are comfortable with frequent updates. |
Most organizations should use the stable channel. It gives you time to plan upgrades around maintenance windows and read the changelog thoroughly before updating. Switch to edge only if you have a specific need for features that ship before the next stable release.
Keep your deployment current
Running far behind the current release makes each upgrade riskier. Changelogs accumulate more breaking changes and deprecations, and incremental migration becomes harder to test.
If your current version is more than 10 versions behind, upgrade incrementally (for example, every 10 versions) and verify each installation before proceeding. Review the Stable releases or Edge releases page and read all changelogs between your current version and your target version before starting.
Test on a staging instance first
For production deployments, run the upgrade on a staging or sandbox instance before applying it to production. Seed the staging instance with a copy of your production database to surface any compatibility issues with your apps, queries, and workflows.
When connecting a staging instance to a copy of the production database, set TEMPORAL_TASKQUEUE_WORKFLOW and WORKER_TEMPORAL_TASKQUEUE to a unique value (such as sandbox-test) to prevent the staging instance from interfering with Workflows running on production.
Refer to the upgrade deployments guide for full pre-upgrade testing instructions.
Back up before every upgrade
Take a database snapshot and verify that you have a copy of your ENCRYPTION_KEY and all instance environment variables before starting any upgrade. If the upgrade fails, you need these to restore your previous state.
Refer to the backup and recovery guide for guidance on what to back up and where to store it.
Plan for downtime
Single-container deployments require downtime during upgrades. Multi-container deployments on Kubernetes support near-zero-downtime rolling upgrades through Helm. If you have strict availability requirements, migrate to a multi-container deployment before your next scheduled upgrade.
Refer to the near-zero downtime upgrades section for the Kubernetes upgrade strategy.
Communicate with users
Upgrades during business hours cause disruption even when they go smoothly. Schedule upgrades during low-usage periods and communicate the maintenance window to users in advance. After the upgrade completes, notify users that Retool is available again.
If you use source control, ask app authors to avoid merging pull requests during the upgrade window to prevent conflicts between database migrations and in-flight changes.
Roll back if an upgrade fails
If a Retool upgrade causes a critical problem, rolling back requires restoring the database to its pre-upgrade state:
- Stop all Retool containers.
- Restore your PostgreSQL database from the backup you took before the upgrade.
- Ensure the
ENCRYPTION_KEYmatches the restored database. - Start containers using the previous Retool image tag.
Do not attempt to roll back Retool without restoring the database. Retool upgrades often include database schema migrations, and running an older container against a migrated database schema will cause errors.
For deployment-specific upgrade and rollback steps, refer to the deployment upgrade guides.