Configure resource environments
Learn how to create resource environments with different resource configurations for production and testing.
| Multiple Environments Availability | |||
|---|---|---|---|
| Cloud | Generally Available | ||
| Self-hosted Edge | Generally Available | ||
| Self-hosted Stable | Generally Available | ||
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 Cloud or self-hosted 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 the Business or 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.
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:
- Select the Resources tab and click Edit.
- 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.
Configure per-environment permissions
Admins for organizations on the Business or Enterprise plan can configure different access levels to resources from Settings > Permissions. Learn more in the permission groups documentation.
Switch resource environments
You can switch between resource environments directly from the 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
| End-User Environments Availability | |||
|---|---|---|---|
| Cloud | Public beta | ||
| Self-hosted Edge 3.36 or later | Public beta | ||
| Self-hosted Stable 3.33 or later | Public beta | ||
Users that have Use access to an 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
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 app, the next app you open automatically uses the same staging environment.
You can link directly to a Retool app and include the _environment URL query parameter to automatically open it with a specified environment.
The default resource environment for Public Apps is production.
Reference the selected resource environment
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.