Rollback

Rollback restores a VDE to a prior finalized state by rebinding its refs to a stored checkpoint.

Checkpoints

Checkpoints are created automatically when a VDE reaches finalized status:

After a whole build where all models match expected versions
After a whole promotion where the target VDE is finalized

Each checkpoint stores the complete set of model refs and function refs for that VDE at that point in time. Checkpoints are retained according to [janitor] max_checkpoints (default: 20).

Basic rollback

Restore the previous finalized checkpoint for the default VDE:

sqb rollback

For an explicit VDE:

sqb rollback --virtual-env pr_123

Explicit checkpoint

Restore a specific checkpoint:

sqb rollback --checkpoint-id <id>

Use sqb state checkpoints list to see available checkpoints.

What happens during rollback

Target VDE lock is acquired
The target checkpoint is located (previous finalized by default, or explicit id)
Checkpoint physical relations are validated to still exist in the warehouse
VDE refs are replaced with the checkpoint’s ref set
VDE function refs are replaced with the checkpoint’s function ref set
Logical VDE views are refreshed to point at the restored physical versions
Function definitions are republished from the checkpoint’s function versions
Target VDE lock is released

Partial rollback

Roll back a subset of models with --select:

sqb rollback --select fact_orders

Rolling back some models but not others can leave the VDE with stale models - models whose restored versions no longer line up with the rest of the VDE. When this happens, rollback is blocked by default so you don’t leave the VDE in a working state by accident. To accept a working VDE, pass --allow-partial-rollback:

sqb rollback --select fact_orders --allow-partial-rollback

The VDE is marked working after the rollback. You can finalize it later by building or rolling back the remaining models. If the models you select depend on upstream models that also need to be restored for the scope to be coherent, pass --include-stale-upstreams to expand the selection to the minimal set of required upstream refs from the checkpoint:

sqb rollback --select fact_orders --include-stale-upstreams

Guards

Condition	Behavior
No previous checkpoint exists	Blocks. Build the VDE first to create a finalized checkpoint.
Checkpoint physical relations deleted	Blocks. The physical version tables have been cleaned up by janitor. Use a more recent checkpoint or rebuild.
Unknown checkpoint id	Blocks with error.
Target VDE is locked	Blocks. Wait or clear the lock.
Target VDE is detached	Blocks. Detached VDEs cannot be rolled back.
Partial rollback leaves VDE working	Blocks unless `--allow-partial-rollback` is set.

Checkpoint inspection

List checkpoints for a VDE:

sqb state checkpoints list
sqb state checkpoints list --virtual-env pr_123

Show a checkpoint’s model refs:

sqb state checkpoints show <checkpoint_id>

Diff current VDE refs against a checkpoint:

sqb state checkpoints diff <checkpoint_id>

Getting Started

dbt Compatibility

Concepts

Python Nodes

Virtual Environments (Alpha)

Integrations

CLI Reference

Checkpoints

Basic rollback

Explicit checkpoint

What happens during rollback

Partial rollback

Guards

Checkpoint inspection

​Checkpoints

​Basic rollback

​Explicit checkpoint

​What happens during rollback

​Partial rollback

​Guards

​Checkpoint inspection

Checkpoints

Basic rollback

Explicit checkpoint

What happens during rollback

Partial rollback

Guards

Checkpoint inspection