Horizontally scaling Retool

This doc will explain how you can run horizontally scale Retool on-prem deployments.


Retool is designed to be simple to self-host on your own infrastructure.

Retool is packaged as a single stateless docker container. The only dependency that it has is a Postgres database that Retool uses for storing data like user info, organization settings, audit logs, and apps.

At startup, Retool automatically checks and runs any un-run migrations on the database, and then starts itself up. The Retool server will both serve the API as well as the frontend assets.

Horizontally scaling Retool

To horizontally scale Retool beyond just one container / machine:

  1. Host the Postgres database on an external system (e.g. AWS RDS).
  2. Start multiple Retool containers that use the same Postgres database
  3. Use a load balancer to route traffic between the Retool server containers

You can accomplish this using a variety of strategies; there are some configuration files and examples that you can find here: https://github.com/tryretool/retool-onpremise

Zero down-time upgrades

When you upgrade to versions of Retool that require running new database migrations, it's possible that a simple multi-container set up may run into downtime issues. This is because every container attempts to run the migration at startup, which can potentially lead to a deadlock.

Here are some basic instructions on how you can avoid this:

  1. Know when you'll need to run a migration: whenever we increment a major version (e.g., we have shipped a migration.
  2. When you're upgrading a major version, deploy one single Retool container of the newest version and allow that container to finish running the migrations. Because we make sure that our migrations are always backwards compatible, this will not cause any downtime.
  3. After that single Retool container succeeds in migration, you can then proceed with the full roll-out of the other Retool containers.
  4. Clean up: remove the container created in step 2.


We're working to make this better

This is the safest way to upgrade Retool, but we're actively refining how we deploy Retool. We should have updates on easier upgrade-paths soon.

Did this page help you?