Skip to main content

Sync schema changes across environments

Learn how to sync Retool Database schema changes across environments using schema migrations.

Available on:Team planBusiness planEnterprise plan

The Retool Database resource is automatically configured for all environments your organization uses. Using schema migrations, you can update Retool Database schemas in one environment and copy these changes to another environment. This allows you to iterate on your database schema on testing environments and deploy updates to users on production apps only when changes are ready.

Create a schema migration

You can create a schema migration after creating, updating, or removing any tables or fields in any environment. Select the Environment menu in the upper-right and click Schema migration.

Schema migration modal from environment dropdown

The History view shows past migrations, including the executed SQL and whether the migration completed successfully. Click New migration to start creating a migration.

On the new migration modal, you can choose the source and destination environments using the dropdowns and view the schema differences between the two environments. For example, the following shows the addition of two fields: an integer field named age and a text field named avatar_url. Each are present in the staging environment and not in production.

Schema migration with age and URL fields

You can click the checkboxes next to the modified tables or fields to exclude changes from the migration.

Preview and edit SQL

In the GUI view, the SQL a migration executes is generated automatically. To preview this SQL, click the SQL tab. You can edit this SQL to execute custom migrations, but you cannot return to the GUI view after making changes to the SQL. To return to the GUI view, click the Undo SQL edits button to reset the SQL changes.

Schema migration SQL editor

Execute migrations

To run schema migrations, select the confirmation checkbox and click Migrate. On the History modal, your migration will display as Running and marked as Completed when it's finished. You can then navigate back to your destination environment to see the changes reflected on that database.

Failed migrations

Migrations with errors show as Failed in the History modal. When a migration fails, none of its changes apply to your database, so after fixing any errors you can run a migration containing the same changes. The detail view for these failed migrations contains the related PostgreSQL error message.

Failed migration example