Configure the app builder's orchestration backend

Learn how self-hosted Retool chooses between pg-boss and Temporal for the app builder, how to check which one it uses, and how to change it.

Retool 4.86.0 Stable

Enterprise

The app builder runs its background work, such as agent sessions and app publishing, on an orchestration backend: pg-boss or Temporal. pg-boss is a job queue that uses your instance's existing platform database, so it requires no additional infrastructure. Retool recommends pg-boss for the app builder.

Agent messaging

The app builder also sends live updates, such as the agent's responses in the IDE. With RR_AGENT_PUBSUB_BACKEND=postgres, these go through the platform database, so the app builder doesn't require Redis.

• The Retool Helm chart sets this variable when the agent sandbox is enabled.
• If you deploy Retool another way, set it in your instance's environment variables.

Backend selection

Retool checks these rules from top to bottom and stops at the first match. Rules 3 to 5 apply only the first time Retool starts, when no backend is saved yet:

#	When	Backend
1	RR_POSTGRES_ORCHESTRATION_BACKEND=true is set	pg-boss
2	R2_ORCHESTRATION_BACKEND=temporal is set	Temporal
3	The app builder has no data yet, meaning no app builder apps, libraries, or agent chats exist, even if Temporal is configured	pg-boss
4	Temporal is configured, either your own Temporal cluster or Retool-managed Temporal	Temporal
5	None of the above	pg-boss

How the choice is saved:

• Retool chooses the first time it starts and saves the choice in the platform database. It keeps that backend after restarts and upgrades.
• Rules 1 and 2 apply each time Retool starts and replace the saved backend.

For details on each variable, refer to the general environment variables reference.

Use pg-boss with Helm

If your instance doesn't use Temporal, Retool uses pg-boss without any extra configuration. If the app builder already runs on Temporal and you want to use pg-boss, add the following to your values.yaml file and run helm upgrade.

values.yaml

env:
  RR_POSTGRES_ORCHESTRATION_BACKEND: "true"

Check which backend Retool uses

Query the platform database. A value of postgres means pg-boss.

SELECT backend FROM r2_orchestration_settings;

Change the backend

To change the backend with Helm, update the env section of values.yaml and run helm upgrade:

• To use pg-boss, set RR_POSTGRES_ORCHESTRATION_BACKEND=true.
• To use Temporal, make sure Temporal is configured, remove RR_POSTGRES_ORCHESTRATION_BACKEND, and set R2_ORCHESTRATION_BACKEND=temporal.

If you can't set environment variables, update the saved backend in the platform database instead:

1. Make sure neither RR_POSTGRES_ORCHESTRATION_BACKEND=true nor R2_ORCHESTRATION_BACKEND=temporal is set. Either one replaces the saved backend each time Retool starts.

2. Run one of the following queries. The saved backend exists once Retool has started.

   To switch to pg-boss:

   UPDATE r2_orchestration_settings
   SET backend = 'postgres', reason = 'operator', "decidedAt" = now()
   WHERE id = 1;

   To switch to Temporal:

   UPDATE r2_orchestration_settings
   SET backend = 'temporal', reason = 'operator', "decidedAt" = now()
   WHERE id = 1;

3. Restart all Retool deployments at the same time, for example with kubectl rollout restart, so every pod uses the new backend.

Best practice

Switch backends when no one is using the app builder. Work in progress carries over when you move from pg-boss to Temporal, and is interrupted when you move from Temporal to pg-boss. In both cases, switching while the app builder is idle avoids unexpected behavior.