Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sqlbuild.com/llms.txt

Use this file to discover all available pages before exploring further.

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: 
sqb rollback --select fact_orders
Partial rollback is guarded by default if it would leave the VDE working: 
sqb rollback --select fact_orders --allow-partial-rollback
Use --include-stale-upstreams to add 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>