Skip to content

Plans & Deployments

Plans deploy model changes from your Git repository to a target environment. A plan shows you what will change before it is applied, and supports an approval workflow for production environments.

What is a Plan?

A plan:

  • Shows what will change before execution
  • Calculates dependencies and impact
  • Requires approval before execution
  • Tracks execution status and logs in real time

The plan workflow differs between frameworks. SQLMesh plans use state-based change detection and single-phase execution. dbt plans use version-based change detection and a two-phase build-then-run pipeline.

Environments

Environment Purpose
prod Production.
dev Development environment for testing changes.
preview Preview environment for reviewing changes before production.

Every plan requires approval before execution, in any environment. Approval is governed by the approve_plan role permission — see Organizations.

Separately, Environment Protection restricts which users can connect to an environment from the dagctl CLI during local development.

Plan Workflow

SQLMesh Plans

  1. Create — dagctl runs sqlmesh plan to detect model changes and calculate backfills
  2. Review — Web UI displays added, modified, and removed models with dependency impact
  3. Approve — A team member with the approve_plan permission approves the plan
  4. Execute — dagctl runs the plan as a Kubernetes Job to apply changes

Model change types:

Type Description
Added New models
Modified Changed models that need backfill
Removed Deleted models
Directly Modified Breaking changes to a model
Indirectly Modified Models affected by upstream changes

Full SQLMesh plan details →

dbt Plans

  1. Create — dagctl detects a new version in .dagctl/config.yaml and runs a git diff to identify changed files
  2. Review — Web UI displays changed files categorized by type (models, tests, macros, etc.)
  3. Approve — A team member with the approve_plan permission approves the plan
  4. Build — dagctl builds a new container image for your project using Kaniko
  5. Run — dagctl executes the configured dbt commands against the new image

dbt plans have three build scopes:

Scope When What happens
selective Model files changed Only changed models are run via --select
all Non-model files changed (macros, configs) Full dbt build is executed
build_only No model changes, only config/infra changes Image is rebuilt but no dbt commands run

Full dbt plan details →

Creating a Plan

  1. Navigate to your project → Plans tab
  2. Click Create Plan
  3. Review the changes
  4. Approve or request approval from a team member
  5. Monitor execution in real time

Next Steps