Deploy dbt project objects¶

In dbt Projects on Snowflake, deploying a dbt project object means copying your dbt project code into Snowflake to create the object or update it with a new version. You do this with the snow dbt deploy command in the Snowflake CLI, Snowsight, or CREATE DBT PROJECT and ALTER DBT PROJECT SQL commands.

Deploy a dbt project object using Snowflake CLI¶

This is the recommended approach for deploying dbt project objects. For a full walkthrough from setup to deployment, see Tutorial: Get started with dbt Projects on Snowflake.

The snow dbt deploy command uploads local files to a temporary stage and creates a new dbt project object or updates it by making a new version. A valid dbt project must contain two files:

dbt_project.yml: A standard dbt configuration file that specifies the profile to use.
profiles.yml: A dbt connection profile definition referenced in dbt_project.yml. profiles.yml must define the database, role, schema, and type.
- By default, dbt Projects on Snowflake uses your target schema (target.schema) specified from your dbt environment or profile. When you execute a dbt project object, dbt attempts to create the target schema specified in profiles.yml if it doesn’t already exist. For more information, see Understand schema generation and customization.
```
<profile_name>:
  target: dev
  outputs:
    dev:
      database: <database_name>
      role: <role_name>
      schema: <schema_name>
      type: snowflake
```

The following examples illustrate how to use the snow dbt deploy command:

Warning

Don’t use --force unless you intentionally want to recreate the dbt project object. In snow dbt deploy, --force runs CREATE OR REPLACE DBT PROJECT, which removes all existing versions and run history.

Deploy a dbt project object named jaffle_shop:
```
snow dbt deploy jaffle_shop
```
Deploy a project named jaffle_shop from a specified directory, using a profiles.yml from a separate directory. The CLI copies that profiles.yml into the root of the deployed project object, overwriting any existing profiles.yml in this location:
```
snow dbt deploy jaffle_shop --source /path/to/dbt/directory --profiles-dir ~/.dbt/
```

Deploy a project named jaffle_shop from a specified directory, supplying a profiles.yml from outside the project, setting a default target, pinning a dbt version, and enabling external access integrations:

snow dbt deploy jaffle_shop --source /path/to/dbt/directory \
  --profiles-dir ~/.dbt/ \
  --default-target prod \
  --dbt-version 1.11.11 \
  --external-access-integration dbthub-integration \
  --external-access-integration github-integration

Deploy a project named jaffle_shop and set a specific version for the dbt project object:
```
snow dbt deploy jaffle_shop --dbt-version '1.11.11'
```

Deploy a dbt project object using Snowsight¶

Deploying a dbt project object in Snowsight takes the dbt code in your workspace and creates a new or updates an existing dbt project object.

To deploy a dbt project object in Snowsight, complete the following steps:

Sign in to Snowsight.
In the navigation menu, select Projects » Workspaces.
In the Workspaces menu, select the workspace that contains your dbt project.
Optionally, run the dbt deps command to pull in project dependencies.
Confirm that your dbt files are in place.

To verify that things work, run the dbt compile, dbt run, or dbt build command, as follows:
1. Below the workspace editor, open the Output tab so that you can see stdout after you run dbt commands from the workspace.
2. From the menu bar above the workspace editor, confirm that the correct Project and Profile are selected.
3. From the command list, select dbt compile, dbt run, or dbt build, then select the execute button. This step parses your project.
From the top right of your workspace, select Connect then select one of the following:
- Deploy dbt project to connect a new dbt project. On first deploy, this creates a schema-level dbt project object.
- Existing dbt deployment to connect to an existing dbt project. Deploying adds a new version to the existing dbt project object (equivalent to ALTER DBT PROJECT … ADD VERSION FROM 'snow://workspace/…/versions/last').
In the Deploy dbt project popup window, select the following:
- Under Select location, select your database and schema.
- Under Select or Create dbt project, select Create dbt project.
- Enter a name and description.
- Optionally, enter a default target to choose which profile will be used for compilation and subsequent runs (for example, prod). The target of a dbt project object execution can still be overridden with --target in ARGS.
- Optionally, select Run dbt deps, then select your external access integration to execute dbt deps automatically during deployment. Alternatively, you can run dbt deps from inside the workspace before deployment to ensure your dbt_packages folder is included without any additional steps.
Select Deploy.

The Output tab displays the command that runs on Snowflake, which is similar to the following example:
```
CREATE DBT PROJECT mydb.my_dbt_projects_schema.my_dbt_project
  FROM 'snow://workspace/mydb.my_dbt_projects_schema.sales_model/versions/version$2'
  EXTERNAL_ACCESS_INTEGRATIONS = ();
```
```
my_dbt_project successfully created.
```
The Connect menu now displays the name of the dbt project object that you created, with the following options:
- Redeploy dbt project: Updates the dbt project object with the current workspace version of the project by using ALTER. This increments the version of the dbt project object by one. For more information, see Versions for dbt project objects and files.
- Disconnect: Disconnects the workspace from the dbt project object, but doesn’t delete the dbt project object.
- Edit project: Update the comment, default target, and external access integration for the dbt project object.
- View project: Opens the dbt project object in the object explorer, where you can view the CREATE DBT PROJECT command for the dbt project object and run history for the project.
- Create schedule: Provides options for you to create a task that runs the dbt project object on a schedule. For more information, see Schedule execution of dbt project objects on Snowflake.
- View schedules: Opens a list of schedules (tasks) that run the dbt project object, with the option to view task details in the object explorer.
Optionally, confirm your dbt project object exists by running the SHOW DBT PROJECTS command in a worksheet, for example:
```
SHOW DBT PROJECTS IN DATABASE mydb;
```

Deploy a dbt project object using SQL commands¶

The CREATE DBT PROJECT and ALTER DBT PROJECT commands copy the files specified in the FROM clause of the statement to create and add new versions to a dbt project object, respectively.

Caution

Deploying directly from a Git repository stage with SQL commands bypasses CI/CD validation. There’s no pull request review and no tests run before changes reach production. We recommend using these commands for development and testing only. For a comprehensive guide on deploying to production, see Tutorial: Set up CI/CD integrations on dbt Projects on Snowflake.

The CREATE DBT PROJECT command creates a new object with a single initial version (for example, VERSION$1), as shown below.

CREATE DBT PROJECT mydb.my_dbt_projects_schema.my_dbt_project
  FROM '@sales_db.integrations_schema.sales_dbt_git_stage/branches/main'
  DEFAULT_TARGET = 'prod'
  EXTERNAL_ACCESS_INTEGRATIONS = my_dbt_ext_access
  COMMENT = 'Generates sales data models.';

The ALTER DBT PROJECT command creates a new version within the existing object with a unique, incremented version number (for example, VERSION$2, VERSION$3, etc.).

ALTER DBT PROJECT mydb.my_dbt_projects_schema.my_dbt_project
  ADD VERSION
  FROM '@sales_db.integrations_schema.sales_dbt_git_stage/branches/main/sales_dbt_project';

Source file locations¶

The dbt project object source files can be in any one of the following locations:

An internal named stage, for example:

'@my_db.my_schema.my_internal_named_stage/path/to/dbt_projects_or_projects_parent'

Internal user stages and table stages aren’t supported.

A dbt workspace, for example:

'snow://workspace/user$.public."my_workspace_name"/versions/live'

Workspace URIs use versions/live, which refers to the active working state of the workspace. We recommend enclosing the workspace name in double quotes because workspace names are case-sensitive and can contain special characters.

An existing dbt project stage, for example:

'snow://dbt/my_db.my_schema.my_existing_dbt_project_object/versions/last'

The version specifier is required and can be last (as shown in the previous example), first, or the specifier for any existing version in the form version$num. For more information, see Versions for dbt project objects and files.

A Git repository stage, for example:

'@my_db.my_schema.my_git_repository_stage/branches/my_branch/path/to/dbt_project_or_projects_parent'

For more information about creating and managing a Git repository object and stage, see Using a Git repository in Snowflake and CREATE GIT REPOSITORY.