> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# User-selected connection environments

> Let users pick which database connection environment their queries, dashboards, and schedules run against.

With *user-selected environments*, a user can choose which [connection environment](/connect-data/dynamic-environments) their queries run against — directly from a workbook, dashboard, or schedule — instead of being routed solely by a [user attribute](/administration/users/attributes). Admins control which environments each user or group can reach by granting access on the connection.

This builds on [dynamic connection environments](/connect-data/dynamic-environments). It doesn't replace branch-based switching or user-attribute assignment — it adds a third, user-driven way to choose an environment and defines how all three interact.

## How environment selection is resolved

A single model can have an environment chosen for it in more than one way at once. Omni resolves them in a fixed priority order, using the first that applies:

1. **Branch selection** — if you're in a [branch](/content/develop/branch-mode) that has environment switching enabled, the branch's environment wins.
2. **User-selected environment** — the environment the user picked for this model (covered on this page).
3. **User-attribute assignment** — the environment the user's [user attribute](/connect-data/dynamic-environments#setup) routes them to.
4. **Base connection** — if none of the above apply, queries run against the primary (base) connection.

<Info>
  This is the same priority order surfaced in the product, in the connection's **Environments** tab: *"When multiple environment sources apply, the priority order is: branch selection, then user-selected environment, then user attribute assignment."*
</Info>

If a user's selection later becomes invalid — for example, their access is revoked or the environment connection is deleted — Omni falls back to the next applicable source: their user-attribute assignment, or the base connection. The query still runs and routes as if no selection had been made.

### How the three mechanisms compare

| Mechanism                                                       | Who controls it                            | Scope                                         | Best for                                                                 |
| --------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------- | ------------------------------------------------------------------------ |
| [Branch switching](/connect-data/dynamic-environments)          | The person working in the branch           | The branch                                    | Validating model or content changes against a non-production database    |
| [User-attribute assignment](/connect-data/dynamic-environments) | Admin (through user attribute values)      | Every query the user runs, by default         | Routing each user or tenant to a default environment automatically       |
| **User-selected environments**                                  | The end user (within admin-granted access) | The specific model, until the user changes it | Letting trusted users move between environments they're allowed to reach |

## Requirements

* **Omni Organization Admin** permissions are required to grant or revoke environment access.
* The connection must already have one or more [environments configured](/connect-data/dynamic-environments#setup). User-selected environments reuse the same environments you set up for dynamic connections.
* A user only sees the environment picker once they've been **granted access** to at least one environment beyond their default.

## Grant environment access

Access is managed per environment, on the connection's **Environments** tab. Org admins have implicit access to every environment; everyone else needs an explicit grant.

<Steps>
  <Step title="Open the connection's Environments tab" titleSize="h3">
    1. Navigate to **Settings > Connections** and open the primary connection.
    2. Click the **Environments** tab. Each environment you've added is listed here.
  </Step>

  <Step title="Add users or groups to an environment" titleSize="h3">
    Under an environment, find the **Access** section and choose whether you're granting access to **Users** or **Groups**:

    * To grant a user, search in **Add a user...** and select them.
    * To grant a group, switch to **Groups** and search in **Add a group...**.

    Granting a group gives access to every member of that [user group](/administration/users/groups), which is the easiest way to manage access at scale. Granted users and groups appear under **Existing access**, where you can remove access at any time.

    <Note>
      You don't need to grant access to org admins — they can reach every environment implicitly.
    </Note>
  </Step>
</Steps>

### Granting access to the base connection

When dynamic (user-attribute) environment selection is enabled on a connection, the base connection appears as its own selectable environment, pinned to the top of the **Environments** list and labeled **Base connection**.

This exists so you can grant base-connection access to users whose user attribute routes them somewhere else by default. For example, a user whose attribute pins them to **Staging** has no path back to production unless you grant them access to the base connection here.

<Note>
  The **Base connection** row is managed automatically — it appears whenever user-attribute selection is enabled and can't be unlinked. Grant or revoke access to it the same way you would any other environment.
</Note>

## Select an environment as a user

Once a user has access to more than one environment, they can switch between them from within a workbook or dashboard.

1. Open the **File** menu and hover **Connection**.
2. Choose an environment from the submenu. **Default** routes you to your normal environment — the one your user attribute assigns, or the base connection if you have none. Any other entry routes you to that specific environment.

The selection is **saved per model and per user** and persists across sessions until it's changed — there's no need to reselect it each visit. After switching, Omni confirms with a *"Switched connection environment."* message and reruns affected queries against the newly selected environment.

<Note>
  The **Connection** submenu only appears when you have access to an environment other than your default. If you can reach exactly one environment, there's nothing to switch between and the menu is hidden.
</Note>

### Selecting an environment in branches

While you're in a [branch](/content/develop/branch-mode) that has environment switching enabled, the **File > Connection** picker is disabled and shows *"Use branch environment settings to change the connection."* This is by design: branch selection takes precedence over a personal selection, so the branch's environment governs every query you run in it. Switch environments using the branch's own settings instead.

## Pin an environment on a schedule

Schedules can run against a specific environment too. Because a [schedule runs as its owner](/share/deliveries), the environment picker in the delivery form shows the **owner's** accessible environments — even when an admin is editing someone else's schedule.

1. Open the delivery (schedule) form for a dashboard or workbook.
2. In the **Connection** field, choose **Default** or a specific environment.
3. Save the schedule.

The chosen environment is applied on **every scheduled run** and on **Send now**. If the **Connection** field isn't shown, the schedule owner has no environments to choose between, and the schedule runs against their default.

<Warning>
  If a schedule changes hands — through **Duplicate** or an ownership **Transfer** — the pinned environment carries over only when the new owner also has access to it. If they don't, the pin is dropped and the schedule falls back to the new owner's default connection.
</Warning>

## Limitations

* **Schemas across environments should be as close to identical as possible.** As with [dynamic environments](/connect-data/dynamic-environments#limitations), switching an environment swaps the schema model while keeping the overarching model the same. A model that references an object missing from the selected environment will surface modeling errors.
* **Selecting an environment doesn't grant data access** — it only routes queries to a connection the admin has already permitted. Revoking access removes both the ability to select that environment and any existing selection that points to it.
* **Branch environment switching takes precedence.** Inside a branch with environment switching enabled, personal selections are ignored in favor of the branch's environment.

## Troubleshooting

<AccordionGroup>
  <Accordion title="A user doesn't see the Connection picker">
    The **File > Connection** submenu only appears when the user has access to an environment *other than* their default. Confirm they've been granted access to a second environment on the connection's **Environments** tab (directly or through a group).
  </Accordion>

  <Accordion title="Queries are running against the wrong environment">
    Check the resolution order. A branch with environment switching enabled overrides a personal selection, which in turn overrides a user-attribute assignment. If a user's selection was made against an environment they can no longer reach, Omni falls back to their user-attribute assignment or the base connection.
  </Accordion>

  <Accordion title="A user with a non-base user attribute can't reach production">
    Their user attribute routes them away from the base connection. Grant them access to the **Base connection** row on the **Environments** tab so they can select it explicitly.
  </Accordion>
</AccordionGroup>

## Next steps

* [Dynamic connection environments](/connect-data/dynamic-environments) — set up the environments and user-attribute routing this feature builds on
* [Branch Mode](/content/develop/branch-mode) — switch environments while developing in a branch
* [User attributes](/administration/users/attributes) — assign default environments to users
* [User groups](/administration/users/groups) — manage environment access for many users at once