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 replace its live version in a single operation. You can deploy with the snow dbt deploy command in Snowflake CLI, Snowsight, or the CREATE DBT PROJECT and ALTER DBT PROJECT ... DEPLOY SQL commands.
Deploy a dbt project object using Snowflake CLI¶
This is the recommended approach for deploying dbt project objects. Use Snowflake CLI in a CI/CD pipeline. For a full walkthrough from setup to deployment, see Tutorial: Set up CI/CD integrations on 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 the live version of an existing object in a single operation. A valid dbt project must contain
dbt_project.yml and one of the supported profile files:
-
dbt_project.yml: A standard dbt configuration file that specifies the profile to use. -
dbt_projects_profiles.ymlorprofiles.yml: A dbt connection profile definition referenced indbt_project.yml. The selected profile file must define the database, role, schema, and type. If both files are present, Snowflake usesdbt_projects_profiles.ymland ignoresprofiles.ymlduring deployment, compilation, and subsequent commands.- 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 indbt_projects_profiles.ymlorprofiles.ymlif it doesn’t already exist. For more information, see Understand schema generation and customization.
- By default, dbt Projects on Snowflake uses your target schema (
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 may remove run history.
-
Deploy a dbt project object named
jaffle_shop: -
Deploy a project named
jaffle_shopfrom a specified directory, using a profile file from a separate directory. The CLI looks fordbt_projects_profiles.ymlfirst and usesprofiles.ymlonly ifdbt_projects_profiles.ymlisn’t present. The CLI copies the file into the root of the deployed project object with the same filename, overwriting a file with the same name in this location: -
Deploy a project named
jaffle_shopfrom a specified directory, supplying a profile file in a folder outside the project, setting a default target, pinning a dbt version, and enabling external access integrations: -
Deploy a project named
jaffle_shopand set a specific dbt runtime version:
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 dbt project object or updates an existing one.
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:- Below the workspace editor, open the Output tab so that you can see stdout after you run dbt commands from the workspace.
- From the menu bar above the workspace editor, confirm that the correct Project and Profile are selected.
- 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 updates the live version of the existing dbt project object
in a single operation
(equivalent to
ALTER DBT PROJECT ... DEPLOY FROM 'snow://workspace/.../versions/live').
-
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
--targetinARGS. - Optionally, select Run dbt deps, then select your external access integration to execute
dbt depsautomatically during deployment. Alternatively, you can rundbt depsfrom inside the workspace before deployment to ensure yourdbt_packagesfolder 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:
The Connect menu now displays the name of the dbt project object that you created, with the following options:
- Redeploy dbt project: Replaces the live version of the dbt project object with the current workspace contents in a single operation by using
ALTER DBT PROJECT ... DEPLOY. For more information, see Live version 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: Select the calendar icon next to the dbt project menu, and then select + Create new 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: Select the calendar icon next to the dbt project menu to see the schedules (tasks) that run the dbt project object. To open a task’s details page, select the … menu for the schedule, and then select View.
- Redeploy dbt project: Replaces the live version of the dbt project object with the current workspace contents in a single operation by using
-
Optionally, confirm your dbt project object exists by running the SHOW DBT PROJECTS command in a worksheet, for example:
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 a dbt project object or update its live version, 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 one mutable version named live, as shown below.
The ALTER DBT PROJECT command replaces the full set of files in the live version in a single operation.
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/live'The version specifier is required and is
live.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.