# Backup & Restore

YotoShelf provides built-in CLI subcommands for backup and restore. No external tools required.

## What to back up

YotoShelf stores all state in two locations:

- **Database** (`YOTOSHELF_DB_PATH`) — all user data, cards, collections, tokens, jobs. This is the critical backup.
- **Library** (`YOTOSHELF_LIBRARY_PATH`) — audio files, cover images, generated assets. Large but regenerable from Yoto for the audio; covers may be irreplaceable.

## Backup command

```sh
docker exec yotoshelf /yotoshelf backup \
  --db-path /data/yotoshelf.db \
  --output /backups/yotoshelf-$(date +%Y%m%d).db
```

The backup command uses SQLite's online backup API — it is safe to run against a live database without locking the server.

## Restore command

```sh
# Stop the server first
docker stop yotoshelf

# Restore
docker run --rm \
  -v yotoshelf-db:/data \
  -v /backups:/backups \
  registry.gitlab.com/yotoshelf/yotoshelf:latest \
  /yotoshelf restore \
    --db-path /data/yotoshelf.db \
    --input /backups/yotoshelf-20260101.db

# Restart
docker start yotoshelf
```

## Cron scheduling

Example cron entry for daily backups at 02:00, keeping 30 days of history:

```sh
0 2 * * * docker exec yotoshelf /yotoshelf backup --db-path /data/yotoshelf.db --output /backups/yotoshelf-$(date +\%Y\%m\%d).db && find /backups -name 'yotoshelf-*.db' -mtime +30 -delete
```

## Restore validation

After restoring, verify the database is intact:

```sh
curl http://localhost:8080/readyz
```

A `200 OK` response confirms the database is reachable and migrations are current.