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

# state

> Manage the virtual mode state store.

# sqb state

Manages the virtual mode state store lifecycle, locks, and checkpoints. Requires `virtual_environments = true`.

## Usage

```bash theme={null}
sqb state <subcommand> [flags]
```

## Subcommands

### init

Create state tables in the configured schema.

```bash theme={null}
sqb state init
```

### migrate

Back up the current state schema and re-initialize state tables. Creates a backup schema (e.g. `sqlbuild_state__backup_<id>`) before re-initializing.

```bash theme={null}
sqb state migrate
```

### rollback

Restore state from a backup.

```bash theme={null}
# Restore from the latest backup
sqb state rollback

# Restore from a specific backup
sqb state rollback --backup-id <id>
```

### reset

Drop all state tables. Requires `allow_reset = true` in the target state config and `--auto-approve` on the command line.

```bash theme={null}
sqb state reset --auto-approve
```

### adopt

Convert existing stateless warehouse relations into versioned physical relations with VDE views. Interactive only - requires typed confirmation.

```bash theme={null}
sqb state adopt [--allow-copy]
```

| Flag           | Description                                                  |
| -------------- | ------------------------------------------------------------ |
| `--allow-copy` | Allow CTAS copy fallback when native rename is not available |

See [Adopt and Detach](/concepts/virtual-environments/adopt-detach) for details.

### detach

Collapse a VDE back into stateless warehouse relations. Interactive only - requires typed confirmation. The VDE must be finalized.

```bash theme={null}
sqb state detach [--allow-copy]
```

| Flag           | Description                                                  |
| -------------- | ------------------------------------------------------------ |
| `--allow-copy` | Allow CTAS copy fallback when native rename is not available |

### locks

List active locks in the state store.

```bash theme={null}
sqb state locks
```

### locks clear

Clear a stuck lock.

```bash theme={null}
sqb state locks clear <lock_key> --force
```

Only clear locks when you are certain the holding operation is no longer running.

### checkpoints list

List finalized checkpoints for a VDE.

```bash theme={null}
sqb state checkpoints list [--virtual-env <name>]
```

### checkpoints show

Show the model refs stored in a checkpoint.

```bash theme={null}
sqb state checkpoints show <checkpoint_id> [--virtual-env <name>]
```

### checkpoints diff

Diff current VDE refs against a checkpoint.

```bash theme={null}
sqb state checkpoints diff <checkpoint_id> [--virtual-env <name>]
```