Permissions database migration in self-hosted Retool 4.0

Self-hosted Retool 4.0 includes an automatic database migration that prepares your instance for upcoming improvements to how Retool handles organization permissions. This migration runs in the background during deployment and does not affect any functionality.

Retool strongly recommends upgrading to self-hosted Retool 4.0 before upgrading to a future release. Doing so allows the migration to run as intended, giving you time to identify and resolve any issues before they become critical. If you attempt to upgrade a pre-4.0 release to a post-4.0 release, this may result in migration issues which can impact the deployment until resolved.

What happens when you upgrade

When you deploy Retool 4.0 stable, the migration runs automatically in the background. In most cases, no action is required.

If the migration fails—even for a single space within your instance—all organization admins will see a notification banner across all settings pages to indicate that the database is in an inconsistent state. This notification includes a link for an admin to trigger the migration again.

The database integrity check can take approximately three hours from upgrade completion. If the check fails, the notification banner is displayed. For larger instances, this check can take up to 15 hours.

If the migration fails

Should the migration fail, no existing functionality is impacted. In most cases, an admin can trigger the migration again. The option to trigger a migration again is disabled if it is already in progress so it cannot be triggered multiple times.

If re-running does not resolve the issue, contact our support team as soon as possible.

Any migration failures must be resolved before upgrading to a future stable release. Attempts to upgrade to a future release with a failed migration will fail and would require rolling back until the migration failure is resolved.