Skip to main content
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

  1. Target VDE lock is acquired
  2. The target checkpoint is located (previous finalized by default, or explicit id)
  3. Checkpoint physical relations are validated to still exist in the warehouse
  4. VDE refs are replaced with the checkpoint’s ref set
  5. VDE function refs are replaced with the checkpoint’s function ref set
  6. Logical VDE views are refreshed to point at the restored physical versions
  7. Function definitions are republished from the checkpoint’s function versions
  8. 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

ConditionBehavior
No previous checkpoint existsBlocks. Build the VDE first to create a finalized checkpoint.
Checkpoint physical relations deletedBlocks. The physical version tables have been cleaned up by janitor. Use a more recent checkpoint or rebuild.
Unknown checkpoint idBlocks with error.
Target VDE is lockedBlocks. Wait or clear the lock.
Target VDE is detachedBlocks. Detached VDEs cannot be rolled back.
Partial rollback leaves VDE workingBlocks 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>