> ## 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

> Checkpoints and rollback for virtual environments.

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:

```bash theme={null}
sqb rollback
```

For an explicit VDE:

```bash theme={null}
sqb rollback --virtual-env pr_123
```

## Explicit checkpoint

Restore a specific checkpoint:

```bash theme={null}
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`:

```bash theme={null}
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`:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
sqb state checkpoints list
sqb state checkpoints list --virtual-env pr_123
```

Show a checkpoint's model refs:

```bash theme={null}
sqb state checkpoints show <checkpoint_id>
```

Diff current VDE refs against a checkpoint:

```bash theme={null}
sqb state checkpoints diff <checkpoint_id>
```