Configure resource environments

Learn how to create resource environments with different resource configurations for production and testing.

All Retool organizations on paid plans have production and staging resource environments:

• Production is the default resource environment for Retool apps and cannot be removed or renamed.
• Staging allows you to test apps without impacting production.

Administrators of Retool organizations can create any number of separate resource environments to build, run, and test apps and workflows. All administrators and editors can access and use these environments by default. Organizations on a Business or an Enterprise plan can configure per-environment resource permissions to allow users to access only certain resource environments, such as allowing access to staging data but preventing access to production.

When you configure a resource, you set the resource environments that resource is accessible in. This allows you to test apps with staging data and restrict access to production data. Resource environments differ from versioning apps: apps function across resource environments. When you query a resource in an app, the resource's environments determine the data the app uses.

Create a resource environment

Administrators create and manage resource environments for a Retool organization from the Environments settings. Click Create new to create a resource environment. All resource environments must have a unique name and display color.

Creating a new environment

Configure resources

Multiple resources environments allow you to display and test against nonsensitive (non-production) data. You can set up connections to your data sources (e.g., database or API) and add environment-specific credentials within the same resource.

Each resource must be configured for your organization's default resource environment. New resources are configured for the default resource environment automatically.

To configure a resource for a specific environment:

1. Select the Resources tab and click Edit.
2. Add the appropriate resource credentials for each defined resource environment.

You don't need to configure a resource for every resource environment. Keep in mind that you cannot switch to an resource environment while editing an app if it hasn't been configured with a resource that is referenced by the app.

Configuring environment resources

Configure per-environment permissions

Admins for organizations on a Business or an Enterprise plan can configure different access levels to resources from Settings > Permissions. Learn more in the permission groups documentation.

Switch resource environments

How you switch resource environments depends on whether you build with apps or classic apps.

Apps

While building apps, use the environment selector in the status bar to switch resource environments. The preview restarts on the same page once the switch is confirmed. You cannot switch to a resource environment where a resource that your functions use isn't configured.

Published apps run in production unless the app URL includes the _environment URL query parameter, such as ?_environment=staging. If a resource requires authentication, users must re-authenticate the first time they switch to a different resource environment.

Learn more in Use resource environments.

Classic apps

You can switch between resource environments directly from the classic app IDE. Users with edit or admin access can also switch resource environments in preview mode. You cannot switch to a resource environment that is not configured with a required resource.

You can access resource settings and configure them for other resource environments by clicking Edit in the Resource field of a query.

Switching resource environments automatically reloads the app to use the appropriate resources and credentials. If your resource requires authentication, users must re-authenticate the first time they switch to a different resource environment. Retool then stores separate access tokens for each resource environment.

Viewer resource environments

Users that have Use access to a classic app can switch between multiple environments from the Retool contextual menu in the lower-left corner.

This feature is not supported on Retool Mobile.

Use specific environments across apps

In classic apps, Retool saves your most recently selected resource environment to your browser cache and automatically uses it the next time you open an app. For example, if you switch to a staging environment in one classic app, the next classic app you open automatically uses the same staging environment.

You can link directly to an app or classic app and include the _environment URL query parameter to automatically open it with a specified environment. For classic apps, refer to Customize app URLs for more about URL parameters.

note

The default resource environment for public links is production.

Reference the selected resource environment

In classic apps, the retoolContext object contains the environment property that corresponds to the name of the resource environment currently in use. Use {{ retoolContext.environment }} to reference this anywhere you need to surface the resource environment in your app.