Permissions database migration required in self-hosted Retool 4.31 and later
Self-hosted Retool 4.0 introduced an automatic database migration that prepares your instance to support Role-Based Access Control (RBAC). That migration ran in the background and did not affect any functionality.
Starting in self-hosted Retool 4.31, this migration runs as a required step. This applies to:
- Edge channel: 4.31 Edge and later.
- Stable channel: 4.33 Stable (upcoming Q3 2026 release) and later.
If your instance hasn't already completed this migration in the background on an earlier release, you must do so before upgrading. If you attempt to upgrade from a pre-4.0 release (e.g., upgrading directly from 3.384 Stable to 4.33 Stable), a deployment-blocking migration failure occurs.
If you already completed the migration, upgrading to Retool 4.31 or later results in low or no downtime, since there's nothing left for it to do.
What happens when you upgrade
The migration runs automatically before your deployment comes up, which causes downtime. Your entire instance is unavailable until the migration completes. Downtime duration depends on your database type, instance size, and the complexity of your permissions data, but expect at least an hour. To prevent the migration from running indefinitely if something goes wrong, it has built-in timeouts: 15 minutes per batch read/write, and 6 hours overall.
If you already completed the migration successfully on an earlier release, you skip this migration and its downtime entirely when you upgrade to Retool 4.31 or later.
To confirm you already completed the migration, check whether Retool has shown an Action Required: Incomplete Migration banner on your settings pages. If you haven't seen it within 15 hours of deploying the release that ran the migration (most instances surface it within 3 hours), the migration succeeded. To confirm sooner, you can query your database directly to check that permissionsV2CustomGroupsMigrated is true for all your organizations.
If you already completed the migration on an earlier release and it fails when you upgrade to Retool 4.31 or later, your deployment fails to come up. Roll back to your pre-upgrade release to run the migration there instead, where it runs nonblocking. Rolling back is safe, whether triggered by a failure or by canceling mid-migration: the migration resumes where it left off.
If you upgraded directly from a release that never ran the migration, the migration always fails, per the warning above. Rolling back in this case doesn't resolve the failure, since your pre-upgrade release never completed it either. Upgrade forward to version 4.0 first, (refer to the deployment upgrade guides), then reattempt your upgrade to Retool 4.31 or later.
If you haven't already completed the migration
Upgrading first to version 4.0 is required, not optional. Doing so lets the migration run nonblocking, giving you and Retool support time to identify and resolve any database issues before they become critical.
Upgrading directly to Retool 4.31 or later without first completing the migration on an earlier release will result in a deployment-blocking failure. Resolving it requires upgrading to a release that completes the migration first (refer to the deployment upgrade guides) so it can run nonblocking there.
Resolving a failed migration
If the migration fails, contact our support team as soon as possible.
Re-running a failed migration automatically sends error logs to Retool, so if you share your container logs, Retool can diagnose where the failure occurred. If your instance is airgapped and you can't send logs directly, an admin needs to shell into your backend jobs-runner pod, where logs from the last migration run are stored in /tmp. Retool needs these logs before an engineer can root cause the issue.
For background on the original migration and how failures surfaced then, refer to Permissions database migration in self-hosted Retool 4.0.