Pre-Apply Drift Detection for Versioned Migrations

Atlas now blocks migrations when the target database has drifted from the expected state at the latest applied revision, turning drift detection into a synchronous, preventive control inside your deployment pipeline.

Versioned migrations are intentionally simpler than declarative apply: atlas migrate apply trusts the revisions table and executes the next pending migration files in order, without re-inspecting the target database. That assumption breaks the moment someone runs an out-of-band ALTER, an emergency hotfix, or another tool writes to the same database.

The new pre-apply drift check closes that gap. Before any migration file runs, Atlas compares the target database against the expected state for the latest applied revision (pulled from the Atlas Registry) and aborts the apply if they differ:

env "prod" {
  url = env("DATABASE_URL")
  migration {
    dir = "atlas://my-app"
  }
  check "migrate_apply" {
    drift {
      on_error = FAIL
    }
  }
}

With this configuration in atlas.hcl, every atlas migrate apply first runs the drift check. If drift is detected, the deployment exits non-zero and the apply transcript shows the exact diff that caused the failure:

Executing pre-execution check (1 check in total):
 
  -- check at atlas.hcl:10 (drift):
    -> check drift against version 20260423120000
 
        --- expected state
        +++ actual state
        @@ -0,0 +1,3 @@
        +CREATE TABLE "audit_log" (
        +  "id" integer NULL
        +);
 
    Error: database state does not match expected state at version 20260423120000

Failed Deployments in Atlas Cloud

With migration reporting enabled, the same failure surfaces in Atlas Cloud as a Failed run with the diff inline:

Per-Environment Behavior

Use atlas.env to switch behavior per environment. Production gets a hard stop while staging or canary environments only emit a warning:

check "migrate_apply" {
  drift {
    on_error = atlas.env == "prod" ? FAIL : CONTINUE
  }
}

For the full reference, including exclude patterns for objects intentionally maintained outside the migration scope and the recommended rollout flow on existing environments, see the drift detection doc and the compliance guide.