Configure the app builder's orchestration backend
Learn how to run Retool's app builder on pg-boss instead of Temporal, and how to switch between the two.
Both Retool Workflows and Retool Agents require Temporal to function. Retool's app builder uses Temporal but can optionally use pg-boss for orchestration with the existing PostgreSQL database instead.
If your organization has a use case that prevents the use of Temporal (e.g., egress restrictions) and only needs to build apps, you can deploy a self-hosted instance without it.
Considerations
Temporal is a distributed system used to schedule and run asynchronous tasks for Retool Workflows, Retool Agents, and the app builder. A self-hosted Retool instance uses a Temporal cluster to facilitate the execution of each workflow amongst a pool of self-hosted workers that make queries and execute code in your VPC. Temporal manages the queueing, scheduling, and orchestration of workflows to guarantee that each workflow block executes in the correct order of the control flow. It does not store any block results by default.
You can use a Retool-managed cluster on Temporal Cloud, which is recommended for most use cases. You can also use an existing self-managed cluster that is hosted on Temporal Cloud or in your own infrastructure. Alternatively, you can spin up a new self-hosted cluster alongside your self-hosted Retool instance.
pg-boss is a PostgreSQL-backed job queue. It uses your instance's existing platform database for job storage and Postgres's LISTEN/NOTIFY for dispatch. Retool uses pg-boss to queue and execute app builder work that Temporal would otherwise orchestrate, including agent sandbox provisioning, app publishing, and snapshot builds.
If you decide to deploy Retool using pg-boss and not Temporal:
- Both Retool Workflows and Retool Agents are not available.
- pg-boss does not have dedicated debugging UI while Temporal does. Any troubleshooting relies on logs only.
- You can choose to configure Temporal at a later time. This restores workflow and agent availability.
Use pg-boss instead of Temporal
To use pg-boss, omit the retool-temporal-services-helm subchart entirely from the configuration. Retool automatically configures pg-boss and uses the existing platform database.
Switch from pg-boss to Temporal
If your needs change and you want to use Temporal in the future, you can update your instance's configuration to include the retool-temporal-services-helm subchart. Once restarted, the instance automatically switches to using Temporal for the app builder, and any pending pg-boss jobs drain automatically in the background. Retool Workflows and Retool Agents also become available for use.