Skip to main content

Backup and disaster recovery best practices

Learn how to back up and recover your self-managed Retool instance.

A reliable backup strategy protects against accidental deletion, database corruption, and infrastructure failures. Plan and test your backup process before going to production.

Understand what to back up​

A complete Retool backup covers three things:

  • The platform PostgreSQL database, which stores apps, users, resources, audit logs, workflows, and organization settings.
  • Your ENCRYPTION_KEY and all other instance-specific environment variables. These are not stored in the database and must be preserved separately.
  • Your object storage bucket contents, if you use Retool Storage.

Back up your platform database​

For production, use a managed PostgreSQL service (such as Amazon RDS, Cloud SQL, or Azure Database for PostgreSQL) and enable automated backups with point-in-time recovery (PITR). PITR lets you restore to any moment within the retention window, which reduces data loss exposure.

If you run a containerized PostgreSQL instance (for example, in a development or proof-of-concept deployment), use pg_dump to export the database to a file and store that file in a location outside your Retool containers. Containerized PostgreSQL is not recommended for production; refer to the platform database migration guide to move to an external managed service.

At minimum, take a fresh database snapshot or backup before every Retool upgrade.

Store your encryption key securely​

Retool uses the ENCRYPTION_KEY environment variable to encrypt sensitive values in the platform database, including resource credentials. If you lose the encryption key, the encrypted data in your database becomes unrecoverable even if the database backup is intact.

Store the encryption key and all instance environment variables separately from your database backup:

When restoring a Retool instance, set the ENCRYPTION_KEY environment variable to the same value that was in use when the backup was taken. Mismatched keys will prevent Retool from decrypting stored credentials.

Back up object storage​

If you use Retool Storage with your own bucket, enable versioning on the bucket to protect against accidental deletions. For critical data, enable cross-region replication to protect against regional outages.

Test your backups​

A backup you have never restored is a backup you cannot rely on. Regularly restore your database backup to a temporary, isolated Retool instance to verify:

  • Retool starts successfully with the restored database.
  • Apps, resources, and workflows are accessible.
  • The ENCRYPTION_KEY you have on file decrypts the restored data without errors.

The upgrade testing flow guide describes how to spin up a temporary instance from a database copy, which also serves as a restore test.

Plan for recovery​

Before an incident, document and store in a known location:

  • The process to restore your PostgreSQL database from backup.
  • The process to retrieve the ENCRYPTION_KEY and other environment variables from your secrets store.
  • The steps to start a new Retool instance against the restored database.

Having this documented reduces recovery time and removes ambiguity when troubleshooting under pressure.