How do we set up Retool environments (staging vs prod) and promote releases safely?

Most teams outgrow a single “everything happens in prod” Retool setup very quickly. To ship apps confidently, you need clear staging vs production environments, safe data access, and a repeatable way to promote releases without surprises.

This guide walks through how to set up Retool environments, connect staging vs production resources, and promote changes safely—so you can iterate quickly while protecting your live users and data.

Why you need staging vs production in Retool

Retool gives you tools to separate development and production in a few key ways:

Staging & production resources
Connect your apps to different databases or APIs per environment. For example:
- Staging: staging-postgres.mycompany.internal
- Production: prod-postgres.mycompany.internal
Resource environment permissions
Control who can read/write to each environment’s resources, ensuring only the right people can touch production.
Environment configuration variables
Define environment-specific secrets and values (like API keys, base URLs, feature flags) and reference them across Retool.
Retool Database per environment
If you use Retool Database, you can automatically create a database for each environment and safely ship schema changes between them.

Together, these let you build and test in isolation, then switch apps to production resources only when you’re ready.

Core concepts: resources, environments, and configuration

Before diving into setup, it helps to understand how Retool structures these pieces.

Resources

A resource is a connection to a database, API, or other backend. Common examples:

PostgreSQL, MySQL, Snowflake, BigQuery, MongoDB
REST or GraphQL APIs
Retool Database

Each resource can have different configurations for each environment (staging vs prod), so your app logic stays the same while the underlying data source changes.

Environments

An environment is a context within your Retool instance—typically:

Development / Staging: For building and testing against non-production data.
Production: For real end users and live data.

Retool lets you:

Connect apps to staging resources during development.
Switch seamlessly to production resources when in user mode.

Environment configuration variables

Environmental configuration variables let you store:

Secrets: API keys, tokens, connection strings
Config values: base URLs, feature flags, timeouts
Environment-specific toggles: sandbox vs live endpoints

You define them once per environment and reference them in resources, queries, and components.

Step 1: Plan your Retool environments

Start by deciding how many environments you need and who should access each.

Common approach:

Development / Staging environment
- Used by: Developers, internal testers, QA
- Data: Mock, synthetic, or anonymized copy of production
- Permissions: Broad access is ok; safer to experiment
Production environment
- Used by: End users, business users, or internal teams doing real work
- Data: Live production data
- Permissions: Restricted—only admins and trusted users can edit apps and resources

Clarify:

Which databases/APIs are staging vs production.
What level of data fidelity is required in staging.
Who can deploy/promote changes to production.

Step 2: Create staging and production resources

Next, connect your databases and APIs as resources and configure them per environment.

2.1 Connect to all databases and APIs

In Retool:

Go to Resources.
Click Create new.
Choose your resource type (Postgres, REST API, etc.).
Configure:
- Name: Include env in the name, e.g., Orders DB (staging) and Orders DB (production).
- Connection details: Host, port, database name, credentials.
Test the connection.
Save.

Repeat for both staging and production variants of each resource.

Tip: Use consistent naming conventions so it’s obvious which resource is safe to test against and which is production-critical.

2.2 Use environment-specific settings

If you prefer one logical resource with multiple environment configs:

Define staging and production connection settings.
Use environment variables (see next section) for hostnames, ports, and credentials.
Ensure that when you’re in staging mode, queries execute against staging, and in production user mode, they hit production.

Step 3: Use environmental configuration variables

To keep secrets and config organized and safe:

Open your Retool environment settings.
Define environment configuration variables for each environment, like:
- API_BASE_URL=https://api-staging.example.com (staging)
- API_BASE_URL=https://api.example.com (production)
- STRIPE_API_KEY (sandbox vs live)
- DB_CONNECTION_STRING (staging vs prod)
Reference these variables in:
- Resource configurations (host, connection string, credentials).
- Queries (e.g., dynamic URLs for REST resources).
- App logic (feature flags, toggles).

This keeps your app code the same while behavior changes per environment.

Step 4: Build apps against staging resources

With staging resources and config in place, build everything against staging first.

4.1 Connect to staging resources by default

When building a new app:

Use the staging resource for queries (e.g., Orders DB (staging)).
Ensure all data-modifying queries (INSERT, UPDATE, DELETE) are pointing to staging.

4.2 Use a Retool Database per environment (optional)

If you use Retool Database:

Automatically create a Retool Database for each environment.
Develop your app against the dev or staging Retool Database first.
Later, sync schema changes and data as needed to the production Retool Database.

Step 5: Securely ship changes across environments

Once your app is working in staging, you need a safe way to promote it to production.

5.1 Switching an app from staging to production

The high-level flow:

Develop and test in staging mode.
Verify all queries, components, and workflows using staging resources.
When ready to go live:
- Switch the app’s resource references from staging to production (or rely on environment-based resource configs).
- Ensure environment variables point to production endpoints.
Publish the app to production users.

If you’ve used environment-aware resources and config variables correctly, switching environments should mostly be about toggling which environment the app is running in, not rewriting queries.

5.2 Resource environment permissions

To promote releases safely:

Use resource environment permissions to:
- Limit who can modify production resources (e.g., only admins or senior engineers).
- Allow more people to work with staging resources freely.

This way, even if someone misconfigures a staging query, production remains protected.

Step 6: Inspect and release schema changes safely

Schema changes are one of the biggest risks when promoting from staging to production. Retool provides a workflow to handle this.

6.1 Develop against your dev or staging database

Build and iterate using a dev or staging database.
Test:
- New tables, columns, indexes.
- Query performance.
- Edge cases, error states, and rollback behavior.

6.2 Inspect schema differences

Before promoting changes:

Inspect schema changes between your dev/staging and production databases.
Review:
- New or altered tables.
- Added/removed columns.
- Constraints and indexes.

This lets you catch breaking changes before they reach production.

6.3 Release schema changes to production

Once verified:

Release schema changes to your production database.
In Retool Database, you can safely:
- Sync schema changes between environments.
- Ensure your production database matches the tested staging schema.

After the schema is updated:

Re-run key workflows against production with minimal test data.
Monitor logs and error states for early issues.

Step 7: Promote app releases in a controlled way

Combine the above practices into a repeatable promotion workflow.

7.1 Recommended release process

Feature development
- Build in staging using staging resources.
- Use environment variables for anything environment-specific.
Internal QA
- Invite QA and stakeholders to test the app in staging.
- Validate queries, data flows, and edge cases.
Schema review (if applicable)
- Inspect schema changes between staging and production.
- Apply changes to production only after review and approval.
Configuration check
- Confirm environment configuration variables for production are correct:
  - API endpoints
  - Auth providers
  - Analytics tools (e.g., Segment, Google Analytics)
Production switch
- Switch the app to run with production resources.
- Ensure resource environment permissions are correctly set for prod.
Gradual rollout
- Optionally expose the app to a small group of users first.
- Monitor usage and error logs.
- Expand access when stable.

7.2 Building a release checklist

Use a simple checklist before every production promotion:

All queries use environment-aware resources.
No direct staging endpoints hard-coded in queries or components.
Schema changes inspected and synced to production.
Environment variables audited for production correctness.
Permissions set correctly for production resources.
Rollback plan in place (previous version saved, quick switch back to staging if needed).

Best practices for safe Retool environments and releases

To keep your staging vs production setup robust over time, adopt the following habits.

Use clear naming and tagging

Name resources and apps with explicit environment labels:
- Customers API (staging)
- Customers API (production)
Avoid ambiguous labels like “test” or “main” without environment context.

Minimize hard-coded endpoints and secrets

Replace hard-coded URLs or keys with environment configuration variables.
Centralize configuration so a single environment switch updates everything.

Enforce permissions on production

Restrict who can:
- Edit production apps.
- Modify production resources.
- Apply production schema changes.
Grant broader access in staging for faster iteration.

Keep staging data realistic but safe

Use:
- Anonymized copies of production data, or
- Synthetic data that reflects real-world scenarios.
Avoid using raw production PII in staging environments.

Summary: A safe pattern for staging vs production in Retool

To set up Retool environments (staging vs prod) and promote releases safely:

Create distinct resources for staging and production databases/APIs.
Use environment configuration variables to handle endpoints, secrets, and flags.
Build and test apps against staging resources first.
Inspect and release schema changes from dev/staging to production.
Switch to production resources only after thorough testing and review.
Control access with resource environment permissions so production remains protected.

With this setup, your team can iterate rapidly in staging while keeping production stable, secure, and predictable.