Configuring dbt environments

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 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. 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
Restricted Querier permissions or higher on the shared model. If using custom roles, you need the Use IDE permission.

Managing dbt environments

dbt environments are managed in the dbt IDE through the model IDE:

In Omni, click Develop in the left navigation.
In the list of models, click the model you want to work with to open the model IDE.
In the model IDE, click the dbt icon in the left navigation.
Click Sync at the top of the file list.

This opens the Sync and Environment settings:

Highlighted Environments section in the dbt IDE, accessed by clicking Sync in the IDE's file list — Access your dbt environments by clicking Sync in the dbt IDE's file list

Creating dbt environments

Personal environment
Shared environment

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:

Open the Sync section of the dbt IDE.
In the Environments section, click Add Environment.
Define the environment settings.
Optional: Add your dbt project’s environment variables.
Click Save to create the environment.

Editing dbt environments

See Environment ownership for the permissions required to edit environments.

To update an existing environment:

In the Sync page of the dbt IDE, click the icon next to the environment.
Click Edit.
Update the environment’s settings and/or variables.
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 during the initial setup, or update it after the environment is created:

In the Sync page of the dbt IDE, click the icon next to the environment.
Click Edit.
Set Belongs to to the user that should own the environment.
Click Save.

Configuring dbt environment settings

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:

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, 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

required

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.

required

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 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 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.

In the Sync page of the dbt IDE, click the icon next to the environment.
Click Edit.
In the Environment Variables section, click Add variable.
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.
Click Save to create the variable.

Renaming dbt variables

Variable names cannot be changed after the variable is saved. To rename a variable:

In the Sync page of the dbt IDE, click the icon next to the environment.
Click Edit.
Scroll to the Environment Variables section.
Delete the variable.
Create a variable with the new name.

Deleting dbt variables

To delete a variable:

In the Sync page of the dbt IDE, click the icon next to the environment.
Click Edit.
Scroll to the Environment Variables section.
Click the icon next to the variable. This will immediately delete the variable.

Next steps

Syncing dbt — Sync an environment’s dbt metadata into your Omni model
Debugging dbt sync issues — Resolve models that Omni couldn’t match after a sync

Getting started

Manage content

Analyze & build

Visualize & present

Deliver content

Model data

Manage integrations

Configuring dbt environments

How it works

Environment ownership

Requirements

Managing dbt environments

Creating dbt environments

Editing dbt environments

Assigning dbt environment ownership

Configuring dbt environment settings

dbt environment settings reference

Managing dbt environment variables

Adding dbt variables

Renaming dbt variables

Deleting dbt variables

Next steps

​How it works

​Environment ownership

​Requirements

​Managing dbt environments

​Creating dbt environments

​Editing dbt environments

​Assigning dbt environment ownership

​Configuring dbt environment settings

​dbt environment settings reference

​Managing dbt environment variables

​Adding dbt variables

​Renaming dbt variables

​Deleting dbt variables

​Next steps

How it works

Environment ownership

Requirements

Managing dbt environments

Creating dbt environments

Editing dbt environments

Assigning dbt environment ownership

Configuring dbt environment settings

dbt environment settings reference

Managing dbt environment variables

Adding dbt variables

Renaming dbt variables

Deleting dbt variables

Next steps