> ## 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.
# Configuring dbt environments
> Mirror your dbt profiles.yml or dbt Cloud environments in Omni so Omni runs dbt commands the way your project expects.
A dbt environment tells Omni how to run dbt commands against your project — which schema your models are built into, which database they live in, and what `target` your project expects.
## How it works
Every time Omni syncs, it compiles your dbt project to build a manifest. Just like a local `dbt run`, that compilation needs to know where your models are built. An Omni environment supplies that information by mirroring an entry from your dbt configuration:
* **dbt Core** — One output block under a profile in your `profiles.yml`
* **dbt Cloud** — One environment, or one developer's credentials
The closer an Omni environment mirrors its dbt counterpart, the more accurately Omni resolves where your models actually live. When the two drift apart, Omni compiles a manifest pointing at the wrong place, and models come back unmatched — see [Debugging dbt sync issues](/integrations/dbt/debugging-sync-issues) for more information.
A production environment is created automatically when you set up the dbt integration. Additional environments, typically one per developer, let you point Omni at development builds and swap between them from an Omni branch.
Environment ownership
Every dbt environment is either **personal**, meaning it belongs to a single user, or **shared**, meaning it doesn't have an owner. Ownership is controlled by the environment's [**Belongs to** setting](#param-belongs-to).
Ownership determines who can manage (create, edit, delete) the environment:
| Environment | Belongs to | Who can manage |
| ------------------------- | ------------ | -------------------------------------- |
| Personal (yours) | You | You; Organization Admins |
| Personal (another user's) | Another user | The other user; Organization Admins |
| Shared | No one | Connection Admins; Organization Admins |
Anyone who can access the model IDE can create an environment for themselves. Creating a shared environment requires Connection Admin or Organization Admin permissions; only Organization Admins can re-assign ownership of an environment.
The production environment is always shared and cannot be assigned an owner.
## Requirements
To follow the steps in this guide, you'll need:
* An Omni connection with a [configured dbt integration](/integrations/dbt/setup)
* **Restricted Querier** permissions or higher on the shared model. If using [custom roles](/administration/users/custom-roles), you need the **Use IDE** permission.
Managing dbt environments
dbt environments are managed in the dbt IDE through the model IDE:
1. In Omni, click **Develop** in the left navigation.
2. In the list of models, click the model you want to work with to open the model IDE.
3. In the model IDE, click the **dbt** icon in the left navigation.
4. Click **Sync** at the top of the file list.
This opens the **Sync** and **Environment** settings:
### Creating dbt environments
All users who want to preview their dbt changes in Omni need a dbt environment. A single personal environment only applies to the user who owns it.
To create a personal dbt environment:
1. [Open the **Sync** section](#manage-environments) of the dbt IDE.
2. In the **Environments** section, click **Add Environment**.
3. Define the [environment settings](#configure-settings).
4. **Optional**: Add your dbt project's [environment variables](#add-variables).
5. Click **Save** to create the environment.
See [Environment ownership](#ownership) for the permissions required to create shared environments.
To create a shared dbt environment:
1. [Open the **Sync** section](#manage-environments) of the dbt IDE.
2. In the **Environments** section, click **Add Environment**.
3. Define the [environment settings](#configure-settings), setting **Belongs to** to **No one (shared)**.
4. **Optional**: Add your dbt project's [environment variables](#add-variables).
5. Click **Save** to create the environment.
Editing dbt environments
See [Environment ownership](#ownership) for the permissions required to edit environments.
To update an existing environment:
1. In the [**Sync** page of the dbt IDE](#manage-environments), click the icon next to the environment.
2. Click **Edit**.
3. Update the environment's [settings](#configure-settings) and/or [variables](#manage-variables).
4. Click **Save**.
Assigning dbt environment ownership
**Organization Admin** permissions are required to assign environment ownership.
The default production environment cannot be assigned an owner.
Organization Admins can assign [ownership of an environment](#ownership) during the initial setup, or update it after the environment is created:
1. In the [**Sync** page of the dbt IDE](#manage-environments), click the icon next to the environment.
2. Click **Edit**.
3. Set **Belongs to** to the user that should own the environment.
4. Click **Save**.
A dbt environment's settings mirror one entry from your dbt configuration. For example, take this `profiles.yml` entry for a developer working locally with dbt Core:
```yaml theme={null}
my_project:
target: dev # Target Name
outputs:
dev:
type: snowflake
database: analytics # Default Database
schema: dbt_blobby # Default Schema
role: transformer # Target Role
```
The matching Omni dbt environment would be:
| Omni setting | Value |
| ---------------- | ------------- |
| Name | `Blobby Dev` |
| Default Schema | `dbt_blobby` |
| Default Database | `analytics` |
| Target Name | `dev` |
| Target Role | `transformer` |
| Belongs to | Blobby |
Note that **Name** and **Belongs to** don't come from your dbt configuration - they're the environment's display label and [owner](#ownership), which are set in Omni.
**Using dbt Cloud?** The same values come from **Profile > Credentials > \[your project] > Development credentials**, where **Schema** maps to **Default Schema** and **Target name** maps to **Target Name**.
dbt environment settings reference
A user-friendly label displayed in the UI. This is what users pick from when switching environments, so name it after what it points at — `Production`, `Staging`, or `Blobby Dev`.
The schema where dbt models are built when the models don't have a custom schema defined. **This must match the schema in your `profiles.yml` (dbt Core) or your dbt Cloud environment (dbt Cloud).**
For a developer environment, this is the developer's personal schema, such as the `schema` value in `profiles.yml`.
The default database where dbt models are built. Defaults to the connection's database — set it only when this environment builds somewhere else. Shown only on dialects that support multiple databases or catalogs.
A custom value for `target.name` when Omni runs dbt commands. Leave unchanged unless you know your dbt code relies on it — for example, a `generate_schema_name` macro that branches on `target.name`. New production environments default to `prod`.
**Snowflake only.** A custom value for `target.role` when Omni runs dbt commands. Leave unchanged unless you know your dbt code relies on it, which is most common when developers dynamically switch databases by role.
The user that owns the environment. Personal environments can only be edited by their owner or by Organization Admins. See [Environment ownership](#ownership) for more information.
Choose **No one (shared)** for environments like production or staging that any Connection Admin should be able to edit. The production environment is always shared.
Defers unbuilt dbt models in this environment to the production environment's builds, so partial builds don't make the rest of your models disappear. Only available on non-production environments. See [Using virtual schemas with partial dbt builds](/integrations/dbt/virtual-schemas#partial-dbt-builds) for more information.
Managing dbt environment variables
If your dbt project uses environment variables — such as to pull dependencies or determine the database or schema that models are built into — Omni needs the same values to compile your project. Environment variables are managed in an individual environment's settings.
Adding dbt variables
Variables aren't shared across environments — they belong to a single environment. If multiple environments require the same variable, you'll need to add it to each environment.
1. In the [**Sync** page of the dbt IDE](#manage-environments), click the icon next to the environment.
2. Click **Edit**.
3. In the **Environment Variables** section, click **Add variable**.
4. Fill in the following:
* **Name** - Must begin with `DBT_` and contain only letters, numbers, and underscores. This cannot be changed after the variable is saved.
* **Value** - The value Omni passes when it runs dbt commands.
* **Secret** - Check this to store the value write-only, so it's masked after saving. Names beginning with `DBT_ENV_SECRET_` are marked secret automatically.
5. Click **Save** to create the variable.
Renaming dbt variables
Variable names cannot be changed after the variable is saved. To rename a variable:
1. In the [**Sync** page of the dbt IDE](#manage-environments), click the icon next to the environment.
2. Click **Edit**.
3. Scroll to the **Environment Variables** section.
4. [Delete the variable](#delete-variables).
5. [Create a variable](#add-variables) with the new name.
Deleting dbt variables
To delete a variable:
1. In the [**Sync** page of the dbt IDE](#manage-environments), click the icon next to the environment.
2. Click **Edit**.
3. Scroll to the **Environment Variables** section.
4. Click the icon next to the variable. **This will immediately delete the variable.**
## Next steps
* [Syncing dbt](/integrations/dbt/syncing-dbt) — Sync an environment's dbt metadata into your Omni model
* [Debugging dbt sync issues](/integrations/dbt/debugging-sync-issues) — Resolve models that Omni couldn't match after a sync