dbt Projects on Snowflake: dbt project objects migrate to a single mutable live version (Pending)¶

Attention

This behavior change is in the 2026_06 bundle.

For the current status of the bundle, refer to Bundle history.

dbt project objects change from immutable, multi-version objects to objects that have a single, mutable live version. This affects how you reference and update project files, and it removes the version history features that were previously available for a dbt project object.

Before the change:

A dbt project object maintained an immutable, numbered version for each deployment. Deploying a project or running ALTER DBT PROJECT with the ADD VERSION option created a new version (VERSION$1, VERSION$2, and so on), and the files in each version couldn’t be changed after the version was created. You could:

Reference the files in any version through a versioned path, for example snow://dbt/my_db.my_schema.my_project/versions/VERSION$1/dbt_project.yml.
List all versions of the object with SHOW VERSIONS IN DBT PROJECT.
Set or unset the default version with ALTER DBT PROJECT ... SET DEFAULT_VERSION and ALTER DBT PROJECT ... UNSET DEFAULT_VERSION.
Inspect the version state of an object with SHOW DBT PROJECTS or DESCRIBE DBT PROJECT <name>: default_version showed the configured default label (LAST, FIRST, or a specific VERSION$N); default_version_name showed the resolved VERSION$N; default_version_alias showed that version’s alias; and the location URI used .../versions/version$N/.

However, because each version was immutable, a dbt project object couldn’t save the run state that dbt produced during an execution. Every EXECUTE DBT PROJECT run started from an immutable set of files that couldn’t be updated in place.

After the change:

When the 2026_06 behavior change bundle is enabled in your account, a dbt project object has a single, mutable version named live. This introduces new capabilities and updates:

Partial parsing and state flags: The object can write the artifacts that dbt produces during a run (the compiled target/ directory, including files like manifest.json and run_results.json) back to its files, so you can reuse state across runs for partial parsing and flags like --state and --select state:modified.
dbt retry: You can re-run a project starting from the node that failed.
Slim CI deployments: You can compile and build only the models that changed, for example with dbt compile --select state:modified.
source freshness command: You can use dbt source freshness to produce an up-to-date report on your source data.
Single live version file path: Project files are referenced through the live path instead of a versioned path. For example, snow://dbt/my_db.my_schema.my_project/versions/VERSION$1/dbt_project.yml becomes snow://dbt/my_db.my_schema.my_project/versions/live/dbt_project.yml.
Object mutability: The files in the live version are directly editable. You can add, update, and remove them using GET, PUT, and COPY FILES.
Object versions removed: Previously added versions are no longer accessible. They don’t appear in the output of SHOW VERSIONS IN DBT PROJECT, and their versioned snow:// paths can no longer be used.
DEFAULT_VERSION attribute removed: You can no longer modify the default version. ALTER DBT PROJECT ... SET DEFAULT_VERSION and ALTER DBT PROJECT ... UNSET DEFAULT_VERSION result in an error.
SHOW and DESCRIBE output changes: SHOW DBT PROJECTS and DESCRIBE DBT PROJECT <name> reflect the new model: default_version is LIVE; default_version_name and default_version_alias are NULL; and the location URI uses .../versions/live/ regardless of any previously set default.

Because the live version is mutable, dbt can read from and write back to a single working version across runs, which lets a dbt project object persist run state between executions.

Migration to the live version¶

To check the current status of the 2026_06 bundle in your account, enable it, or disable it during the opt-out period, see Managing behavior change releases.

When the 2026_06 behavior change bundle is enabled in your account, dbt project objects that you create or replace are automatically live-version objects. Existing dbt project objects remain versioned and untouched until you explicitly migrate them.

To check whether an existing dbt project object has already been migrated, run SHOW DBT PROJECTS or DESCRIBE DBT PROJECT. If the default_version field shows LIVE, the object is already using the new model. If it shows a version number (for example, VERSION$1), the object still uses the previous versioned model and can be migrated.

To migrate existing objects, you must first opt in to the 2026_06 bundle or contact your Snowflake account representative to request early opt-in for the dbt project object live version feature. Once either is in place, you can migrate individual objects to the live version using SYSTEM$MIGRATE_DBT_PROJECT(<object name>).

If you encounter issues after migrating an object, you can revert it to the previous versioned object using SYSTEM$DEMIGRATE_DBT_PROJECT(<object name>).

When the bundle is fully enabled, any remaining dbt project objects that still use the previous versioned object are automatically migrated to the live version using SYSTEM$MIGRATE_DBT_PROJECT(<object name>). At that point, SYSTEM$DEMIGRATE_DBT_PROJECT(<object name>) will no longer work.

Migrate all dbt project objects in your account¶

Once you’re opted in, you can use the following stored procedure to migrate all dbt project objects in your account in a single step. The procedure accepts an optional database_name parameter: if provided, it scopes the migration to that database only; if omitted, it migrates all dbt project objects across your entire account. The procedure attempts to migrate each object, then returns a summary of how many succeeded along with a list of any that failed. Object names with mixed case or special characters are handled safely by double-quoting each identifier component.

CREATE OR REPLACE PROCEDURE migrate_all_dbt_projects(database_name VARCHAR DEFAULT NULL)
  RETURNS VARCHAR
  LANGUAGE PYTHON
  RUNTIME_VERSION = '3.11'
  PACKAGES = ('snowflake-snowpark-python')
  HANDLER = 'run'
AS
$$
def run(session, database_name=None):
    if database_name:
        rows = session.sql(f'SHOW DBT PROJECTS IN DATABASE "{database_name}"').collect()
    else:
        rows = session.sql("SHOW DBT PROJECTS IN ACCOUNT").collect()
    succeeded = []
    failed = []
    for row in rows:
        db = row['database_name']
        schema = row['schema_name']
        name = row['name']
        full_name = f'"{db}"."{schema}"."{name}"'
        try:
            session.sql(f"SELECT SYSTEM$MIGRATE_DBT_PROJECT('{full_name}')").collect()
            succeeded.append(full_name)
        except Exception as e:
            failed.append(f"{full_name}: {e}")
    total = len(succeeded) + len(failed)
    summary = f"{len(succeeded)} of {total} dbt project objects successfully migrated."
    if failed:
        summary += "\n\nFailed objects:\n" + "\n".join(f"  - {f}" for f in failed)
    return summary
$$;

-- Migrate all dbt project objects in the account:
CALL migrate_all_dbt_projects();

-- Migrate only dbt project objects in a specific database:
CALL migrate_all_dbt_projects('my_database');

Ref: 2362