Hi Retool team/community,
What is the supported upgrade path for a legacy self-hosted Retool 2.100.5 installation to a supported Stable release?
I've read the upgrade planning guide, which recommends sequential Stable upgrades, and the permissions migration notice, which recommends stopping at 4.0 before later releases. The missing piece is the legacy entry path from 2.100.5 and the compatible Helm chart versions.
Could you help clarify:
- Which exact intermediate backend image versions are required starting from 2.100.5, and which Helm chart version should be used at each step?
- Is 3.334.32-stable a suitable temporary checkpoint before patched 4.0.x and later supported releases? The Node.js/Brotli advisory lists a fix in 3.334.32+
- For installations using YAML Source Control, which bridge version should run the YAML-to-Toolscript conversion?
- Is there a supported way to inspect pending database migrations before upgrading and verify their completion afterward?
Thanks!
Summary
A self-hosted Retool instance on a legacy 2.100.5 image needs a supported upgrade path to a current Stable release, including which intermediate backend image and Helm chart versions to use at each step, whether 3.334.32-stable is a valid checkpoint before patched 4.0.x, which version handles YAML Source Control-to-Toolscript conversion, and how to inspect/verify database migrations.
AI Response
Retool's supported approach is to upgrade sequentially through each Stable release rather than jumping directly to the target, so required database migrations run in order and with integrity — this is the exact guidance Retool staff gives for legacy 2.x instances, and skipping releases risks bypassing a required migration step. There is no published table pairing one specific backend image with one specific Helm chart version per step; instead, pin the matching Helm chart for each Stable release as you step through it (use the chart version shipped alongside each release and verify the deployment before moving on), and treat the 3.x→4.0 transition as a distinct one-time step using the dedicated 3.x→4.0 upgrade guides. Landing on a recent 3.334.x patch as a staging checkpoint before moving to a patched 4.0.x is consistent with the documented stable-by-stable path (e.g., ...→ 3.334 → 4.0 → 4.34 → ...). Always take a database snapshot and confirm your ENCRYPTION_KEY and env vars before each step, since rollback requires restoring the pre-upgrade database because migrations alter the schema. Retool does not publish a named standalone YAML-to-Toolscript 'bridge' version or a documented pre-upgrade migration-preview command, so for those two specifics rely on the per-release changelogs you review before each hop rather than an assumed fixed version.
Sources
Upgrade planning best practices | Retool Docs
Authoritative guidance confirming the sequential stable-by-stable upgrade path (e.g., 3.334 → 4.0 → 4.34 → 4.86), verifying each install, reviewing changelogs between versions, and backing up before every step because migrations alter the schema.
Upgrade to Latest version from 2.117.21 to latest
A solved topic covering a near-identical legacy 2.x → current upgrade, where Retool staff strongly recommends incremental upgrades so required database migrations run with integrity and points to the release timeline as the step-by-step guide.
The Community Team is testing out a new automation. Let us know if it's helpful (or not) by leaving a
,
, or
. Or by marking this post as the "Solution"! Let us know if you have any feedback here. 