Configuring dbt environments in Omni

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

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.

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 reassign 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 you’re using custom roles, you need the Use IDE permission.

Managing dbt environments

dbt environments can be managed in the Omni UI using the dbt IDE, the dbt environment APIs, or the Omni CLI.

Omni UI
API
CLI

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 page:

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

Use the omni connections dbt-environments-create, omni connections dbt-environments-update, and omni connections dbt-environments-delete commands to create, update, and delete dbt environments using the CLI.

Creating dbt environments

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

Omni UI
API
CLI

To create a personal dbt environment in the Omni UI:

Open the Sync page in the dbt IDE.
In the Environments section, click Add Environment.
Define the environment settings, setting Belongs to to you or another user, if you’re an Organization Admin.
Optional: Add your dbt project’s environment variables.
Click Save to create the environment.

Use the Create a dbt environment API to create a new personal dbt environment.To create a personal environment for:

Yourself - Set the ownerId to your Omni user ID. Get your ID with the Who Am I API.
Another user - Set the ownerId to the other user’s Omni user ID. This requires Organization Admin permissions. Get the user’s ID with the List users API.

curl --request POST \
  --url https://{your-omni-instance}.omniapp.co/api/v1/connections/{connectionId}/dbt/environments \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Blobby's Environment",
  "ownerId": "550e8400-e29b-41d4-a716-446655440000",
  "targetSchema": "blob_analytics",
  "targetDatabase": "blobsrus",
  "variables": [
    {
      "name": "DBT_TARGET",
      "value": "production",
      "isSecret": false
    },
    {
      "name": "DBT_API_KEY",
      "value": "sk-...",
      "isSecret": true
    }
  ]
}
'

Use the Omni CLI omni connections dbt-environments-create command to create a new personal environment.To create a personal environment for:

Yourself - Set the ownerId to your Omni user ID. Get your ID by running omni whoami whoami and locating the user.id value.
Another user - Set the ownerId to the other user’s Omni user ID. This requires Organization Admin permissions. Get the user’s ID by running omni scim users-list and locating the user in the response.

omni connections dbt-environments-create <connection-id> --body '
{
  "name": "Blobby's Environment",
  "ownerId": "550e8400-e29b-41d4-a716-446655440000",
  "targetSchema": "blob_analytics",
  "targetDatabase": "blobsrus",
  "variables": [
    {
      "name": "DBT_TARGET",
      "value": "production",
      "isSecret": false
    },
    {
      "name": "DBT_API_KEY",
      "value": "sk-...",
      "isSecret": true
    }
  ]
}
'

Creating shared environments

Connection Admin or Organization Admin permissions are required to create shared environments. See Environment ownership for more information.

A production environment is created automatically when you set up the dbt integration, so you only need to configure its settings and add environment variables to finish setting it up. Use these instructions to create additional shared environments.

Omni UI
API
CLI

To create a shared dbt environment in the Omni UI:

Open the Sync page in the dbt IDE.
In the Environments section, click Add Environment.
Define the environment settings, setting Belongs to to No one (shared).
Optional: Add your dbt project’s environment variables.
Click Save to create the environment.

Use the Create a dbt environment API to create a new shared dbt environment, omitting the ownerId from the request body:

curl --request POST \
  --url https://{your-omni-instance}.omniapp.co/api/v1/connections/{connectionId}/dbt/environments \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Shared environment",
  "targetSchema": "blob_analytics",
  "targetDatabase": "blobsrus",
  "variables": [
    {
      "name": "DBT_TARGET",
      "value": "production",
      "isSecret": false
    },
    {
      "name": "DBT_API_KEY",
      "value": "sk-...",
      "isSecret": true
    }
  ]
}
'

Use the Omni CLI omni connections dbt-environments-create command to create a new shared environment.Omit the ownerId property from the request body to create the shared environment:

omni connections dbt-environments-create <connection-id> --body '
{
  "name": "Shared environment",
  "targetSchema": "blob_analytics",
  "targetDatabase": "blobsrus",
  "variables": [
    {
      "name": "DBT_TARGET",
      "value": "production",
      "isSecret": false
    },
    {
      "name": "DBT_API_KEY",
      "value": "sk-...",
      "isSecret": true
    }
  ]
}
'

Editing dbt environments

See Environment ownership for the permissions required to edit environments.

Omni UI
API
CLI

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, variables, or both.
Click Save.

Use the Update a dbt environment API to update an existing dbt environment, providing the environmentId as a path parameter. Only include the fields you want to update in the request body:

curl --request PUT \
  --url https://{your-omni-instance}.omniapp.co/api/v1/connections/{connectionId}/dbt/environments/{environmentId} \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Blobby Development",
  "targetSchema": "dev_schema"
}
'

Use the Omni CLI omni connections dbt-environments-update command to update an existing dbt environment. Only include the fields you want to update in the --body:

omni connections dbt-environments-update <connection-id> <environment-id> --body '
{
  "name": "Blobby Development",
  "targetSchema": "dev_schema"
}
'

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:

Omni UI
API
CLI

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.

Use the Update a dbt environment API to change the owner of an existing dbt environment. Set the ownerId to the ID of the user who should own the environment:

curl --request PUT \
  --url https://{your-omni-instance}.omniapp.co/api/v1/connections/{connectionId}/dbt/environments/{environmentId} \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ownerId": "550e8400-e29b-41d4-a716-446655440000"
}
'

Use the Omni CLI omni connections dbt-environments-update command to change the owner of an existing dbt environment. Set the ownerId to the ID of the user who should own the environment:

omni connections dbt-environments-update <connection-id> <environment-id> --body '
{
  "ownerId": "550e8400-e29b-41d4-a716-446655440000"
}
'

Configuring dbt environment settings

A dbt environment’s settings mirror one entry from your dbt configuration. Copy the values directly from your profiles.yml (dbt Core) or dbt Cloud environment credentials to ensure Omni runs dbt commands the way your project expects. 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? Copy the values 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.

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.

required

The schema where dbt models are built when the models don’t have a custom schema defined. Copy this value from the schema in your profiles.yml (dbt Core) or your dbt Cloud environment credentials.For a developer environment, this is the developer’s personal schema.

The default database where dbt models are built. Defaults to the connection’s database — copy the database value from your profiles.yml or dbt Cloud environment if this environment builds models in a different database. Shown only on dialects that support multiple databases or catalogs.

A custom value for target.name when Omni runs dbt commands. Copy the target value from your profiles.yml or the Target name from dbt Cloud environment credentials if 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. Copy the role value from your profiles.yml if your dbt code relies on it, which is most common when developers dynamically switch databases by role.

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.

Omni UI
API
CLI

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 as write-only, so it’s masked after saving. Names beginning with DBT_ENV_SECRET_ are marked secret automatically.
Click Save to create the variable.

Use the Update a dbt environment API to add variables to an existing dbt environment. Include a variable’s id to update an existing variable:

curl --request PUT \
  --url https://{your-omni-instance}.omniapp.co/api/v1/connections/{connectionId}/dbt/environments/{environmentId} \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "variables": [
    {
      "name": "DBT_NEW_VAR",
      "value": "new_value",
      "isSecret": false
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "DBT_TARGET",
      "value": "new_value",
      "isSecret": false
    }
  ]
}
'

Use the Omni CLI omni connections dbt-environments-update command to add variables to an existing dbt environment. Include a variable’s id to update an existing variable:

omni connections dbt-environments-update <connection-id> <environment-id> --body '
{
  "variables": [
    {
      "name": "DBT_NEW_VAR",
      "value": "new_value",
      "isSecret": false
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "DBT_TARGET",
      "value": "new_value",
      "isSecret": false
    }
  ]
}
'

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 immediately deletes 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 in Omni

How it works

Environment ownership

Requirements

Managing dbt environments

Creating dbt environments

Creating personal environments

Creating shared 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

​Creating personal environments

​Creating shared 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

Creating personal environments

Creating shared 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