> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paradime.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Upgrade to dbt™ 1.12
> Move your Paradime workspace to dbt Core™ 1.12: the opt-in v2 Rust parser, native private packages, vars.yml, and seven behavior flags flipping on.
dbt Core™ 1.12 is the last stop before v2: it ships an opt-in Rust parser so you can test v2 compatibility early, and it flips seven behavior flags from earlier releases to enabled by default. This guide is based on the official [dbt™ upgrade guide for v1.12](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.12); check the [dbt Core™ 1.12 changelog](https://github.com/dbt-labs/dbt-core/blob/1.12.latest/CHANGELOG.md) for the full detail.
**Prerequisites**
* An [Admin role](/products/settings/users/role-based-access-control) in Paradime, needed to change the workspace dbt™ version.
* Your project on dbt™ 1.11, upgraded via the [1.11 guide](/guides/migrations/dbt-version-upgrades/upgrade-to-dbt-1.11).
Estimated time: 45 minutes, plus project testing.
## What can break
The biggest upgrade impact is the set of behavior flags that become **enabled by default** in 1.12. If you never set them explicitly, their behavior changes when you switch versions:
| Flag (now enabled by default) | Effect after upgrading |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `require_all_warnings_handled_by_warn_error` | All warnings route through the `--warn-error` / `--warn-error-options` handler. Only affects projects using `warn_error: true` or `--warn-error`. |
| `require_batched_execution_for_custom_microbatch_strategy` | Custom microbatch strategies now execute in batches. Setting the flag to `false` with a custom microbatch macro triggers a deprecation warning. |
| `require_nested_cumulative_type_params` | Cumulative metrics using un-nested syntax now raise an error instead of a warning; they must nest under `cumulative_type_params` (required since 1.9). |
| `require_yaml_configuration_for_mf_time_spines` | Suppresses the `MFTimespineWithoutYamlConfigurationDeprecation` warning; legacy SQL file configuration keeps working. No functional impact. |
| `skip_nodes_if_on_run_start_fails` | A failing `on-run-start` hook now skips all selected resources. |
| `state_modified_compare_more_unrendered_values` | `state:modified` compares unrendered values, reducing false positives across target environments. |
| `validate_macro_args` | Macro arguments are validated by default. |
You can opt out of any of these by setting the flag to `false` under `flags:` in `dbt_project.yml`, but note that the v2 engine removes that opt-out.
## What's new in dbt™ 1.12
### Opt-in v2 parser
The `--use-v2-parser` flag delegates parsing to the new v2 Rust parser instead of the v1 Python parser. It is significantly faster, especially on larger projects where it can be 5–10× quicker, and it is the natural first step toward v2 compatibility: you can catch and fix project issues gradually rather than all at once. The flag changes no behavior unless explicitly set.
The Rust parser is beta. Its output manifest may differ from the Python parser's in edge cases, which can affect downstream behavior. Fall back by removing `--use-v2-parser`, and [report issues](https://github.com/dbt-labs/dbt-core/issues) to dbt Labs. See [Opt-in v2 parser](https://docs.getdbt.com/reference/global-configs/parsing#opt-in-v2-parser).
### New Iceberg `catalogs` spec
The [`catalogs.yml` spec](https://docs.getdbt.com/docs/build/iceberg/catalogs-yml) was reworked to be simpler and current with ecosystem Iceberg support. The new spec can also power cross-platform dbt™ Mesh.
### Native private packages
`packages.yml` and `dependencies.yml` support installing packages from private GitHub, GitLab, or Azure DevOps repositories with the `private` key, using your system's SSH configuration for authentication instead of a token or full Git URL:
```yaml theme={"system"}
packages:
- private: your-org/your-internal-repo
provider: "github" # Supported values: "github", "gitlab", "ado"
```
### UDF extensions
* JavaScript UDFs on Snowflake and BigQuery: a `.js` file in `functions/` plus a YAML file with arguments and return type.
* Overloaded UDFs via the `overloads` property, so one function name accepts different input types. Supported for SQL UDFs in Snowflake and Postgres, and Python UDFs in Snowflake. All overloads form one DAG node; on retry, only failed overloads rerun.
* Public third-party PyPI packages for Python UDFs via the optional `packages` config; the warehouse installs them when creating the UDF.
* Python UDFs on Databricks (requires Unity Catalog; `runtime_version` and `entry_point` are ignored), in addition to Snowflake and BigQuery.
### `latest_version_pointer` for versioned models
dbt™ can automatically create a pointer view named after a versioned model's base name (for example `dim_customers`) once the latest version materializes, so you can query the current version without maintaining a view manually. Enable project-wide with the `latest_version_pointer_enabled_by_default: true` flag, per model with `latest_version_pointer.enabled`, and customize the name with `latest_version_pointer.alias` or the `generate_latest_version_pointer_alias` macro.
### `--sql` flag for `dbt run-operation`
Execute ad hoc statements directly against your warehouse without defining a macro, for one-off operations like dropping a table, applying grants, or a data fix. The statement runs through the full Jinja compilation pipeline, so `ref()`, `source()`, `var()`, `target`, and other context variables are available.
### `on_error` model config
Control whether downstream models run when an upstream model fails. Set `on_error: continue` on a model to let its downstream models still attempt to run; the default (`skip_children`) skips all downstream models on failure. `--fail-fast` takes precedence and stops at the first failure regardless.
### Semantic layer updates
* **Apache Ossie support**: place Ossie-format `.json` files in an `osi/` directory at the project root (configurable with `osi-paths`) and dbt™ parses them into the manifest alongside native semantic models. Ossie versions `0.1.0` and `0.1.1` are supported; other versions raise a parse error. dbt™ also writes an `osi_document.json` artifact to `target/` at parse time.
* **New Semantic Layer YAML spec**: `semantic_model` nests directly under each model instead of being a standalone top-level key, entities and dimensions are defined at the column level, measures are replaced by `type: simple` metrics within the model, and `type_params` is deprecated in favor of top-level keys within each metric. See [Migrate to the latest YAML spec](https://docs.getdbt.com/docs/build/latest-metrics-spec).
### `selector` method for named YAML selectors
Reference a named selector from `selectors.yml` inside `--select` or `--exclude`, for example `--select selector:my_selector`, and compose it with other selection methods and operators. Combining the legacy `--selector` flag with `--select` / `--exclude` still ignores the latter two and now also raises a warning.
### `vars.yml`
Define project variables in a `vars.yml` file at the project root instead of `dbt_project.yml`. It is parsed before `dbt_project.yml`, so `dbt_project.yml` can reference those variables with `{{ var('...') }}`. You cannot define variables in both files.
### Improved exception handling
Internal failures that previously surfaced as raw Python errors (`AttributeError`, `KeyError`, `IndexError`, `RuntimeError`) are replaced with clear dbt™ errors such as `CompilationError` and `ParsingError`. Highlights: dependency-graph cycles raise a `CompilationError`, `run-operation` failures include the exception message in `run_results.json`, and snapshot validation failures show the relevant message without the long Python traceback. Use `--debug` when you need the full Python output.
### New behavior flags (disabled by default)
Introduced in 1.12, opt-in:
| Flag | What it does when enabled |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `require_valid_schema_from_generate_schema_name` | Raises a parsing error (instead of a deprecation warning) when a custom `generate_schema_name` macro returns `null`. |
| `require_sql_header_in_test_configs` | Allows `sql_header` in the `config` of a generic data test at the model or column level. |
| `require_corrected_analysis_fqns` | Applies project-level analysis configuration from `dbt_project.yml` (previously silently ignored) and corrects analysis fully qualified names, for example `your_project.my_analysis` instead of `your_project.analyses.my_analysis`. |
| `require_source_and_semantic_model_names_without_spaces` | Raises an error (instead of a warning) when a source or semantic model name contains a space. |
| `allow_jinja_file_extensions` | Recognizes `.j2`, `.jinja`, and `.jinja2` suffixes on `.sql` and `.md` files, enabling Jinja-aware IDE syntax highlighting. |
| `latest_version_pointer_enabled_by_default` | Creates a latest version pointer view for every versioned model without per-model configuration. |
### Adapter-specific changes
* **Snowflake**: `snowflake.quote_args` controls argument-name quoting on JavaScript UDFs; `iceberg_version: 3` opts Iceberg tables into V3 (immutable after creation, default `2`); the `scheduler` parameter on dynamic tables chooses between Snowflake-managed (`ENABLE`, requires `target_lag`) and dbt™-managed (`DISABLE`, dbt™'s default) refreshes; `snowflake_initialization_warehouse` sets a separate warehouse for a dynamic table's initial build; the `transient` config (and the `snowflake_default_transient_dynamic_tables` flag) creates dynamic tables without a Fail-safe period.
* **BigQuery**: parallel microbatch execution is now supported; `bigquery_use_standard_sql_for_partitions` defaults to `true` (standard SQL via `INFORMATION_SCHEMA.PARTITIONS`) ahead of BigQuery's legacy SQL deprecation on June 1, 2026, and can be set to `false` to revert; `bigquery_reject_wildcard_metadata_source_freshness` raises an error on metadata freshness checks against wildcard tables like `events_*`; `job_link_info_level_log: true` logs job links at info level; `job_execution_timeout_seconds` can be set per model, snapshot, seed, or test.
* **Redshift**: `redshift_skip_autocommit_transaction_statements: true` skips unnecessary `BEGIN`/`COMMIT`/`ROLLBACK` statements when autocommit is enabled (defaults to `false`); the `query_group` session parameter tags queries for Workload Manager routing, configurable in the profile and overridable per model.
* **Databricks**: the `row_filter` config applies a Unity Catalog row filter to `table`, `incremental`, `materialized_view`, and `streaming_table` materializations (not regular views or Hive Metastore relations); `databricks_tags` supports key-only tags (`''` or `None` values) and now merges additively across hierarchy levels, with lower-level values winning on conflicts.
### Quick hits
* dbt™ surfaces occasional, non-blocking optimization hints, enabled by default; disable with the `hints_enabled` flag.
* Fusion-specific names in `warn_error_options` (for example `StaticAnalysis`) are tolerated and ignored with a note, so configs can be shared across dbt Core™ and the v2 engine.
* Macros invoked with `dbt run-operation` can `ref()` models with `private` or `protected` access without a `DbtReferenceError`.
* `dbt seed --empty` creates seed tables with the correct schema but no data.
* Environment variables load automatically from a `.env` file in the working directory; shell variables take precedence, and `dbt init` adds `.env` to the default `.gitignore`.
* `dbt compile` writes compiled SQL for snapshots to `target/compiled/`, one output file per snapshot.
## Upgrade steps
Check your project against the "What can break" table: un-nested cumulative metrics now error, failing `on-run-start` hooks now skip everything, and macro argument validation is on. Fix the code, or explicitly set a flag to `false` in `dbt_project.yml` to defer (remembering v2 removes the opt-out).
Pin a Bolt environment to dbt™ 1.12 in **Settings > Environments** or use a staging workspace, and run your schedules and a full `dbt build` from the Code IDE terminal.
Run `dbt parse --use-v2-parser` in the Code IDE terminal and fix anything it reports. This is the lowest-risk way to start on [v2 readiness](/guides/migrations/dbt-version-upgrades/prepare-for-dbt-v2).
In **Settings > Workspace > General**, select **Change version**, choose **1.12**, and save. See [Upgrade dbt Core™ version](/guides/upgrade-dbt-core-version).
`dbt --version` reports 1.12.x, Bolt schedules run green, and `dbt parse --use-v2-parser` completes cleanly. The most likely failures come from the flipped behavior flags: cumulative metrics missing `cumulative_type_params` now error, and `on-run-start` hook failures now skip the whole run.
## Next steps
What the v2 engine removes, and the readiness checklist.
Automate the flag audit and fixes with an agent-driven PR.
The workspace setting and per-environment overrides.
The upstream dbt™ documentation this guide is based on.
## Related topics
- [Upgrade to dbt™ 1.11](/guides/migrations/dbt-version-upgrades/upgrade-to-dbt-1.11.md)
- [dbt™ version upgrades](/guides/migrations/dbt-version-upgrades/index.md)
- [Prepare for dbt™ v2](/guides/migrations/dbt-version-upgrades/prepare-for-dbt-v2.md)
- [Upgrade with the DinoAI agent](/guides/migrations/dbt-version-upgrades/upgrade-with-the-dinoai-agent.md)
- [Pin a dbt™ version per environment](/changelog/2026-08-19/per-environment-dbt-versions.md)