# Backup

VibeSonic keeps all of its state under one directory,
`VIBESONIC_DATA_DIR` (default `/var/lib/vibesonic`, or `/data` in the
provided Docker image). Everything that must be backed up lives there:

```
<DataDir>/
  vibesonic.db            SQLite database — users, library index,
                           playlists, favorites, sessions, API keys,
                           podcast subscriptions, shares, ...
  vibesonic.db-wal        SQLite write-ahead log (see below)
  vibesonic.db-shm        SQLite shared-memory index for the WAL
  cache/covers/           resized cover-art cache (safe to delete —
                           regenerated on demand from source images)
  podcasts/                downloaded podcast episodes
```

Your music library itself (the folders configured via
`VIBESONIC_MUSIC_DIRS` / the admin "Music Folders" page) is not inside
`DataDir` and has its own backup story — it's your source media, and
VibeSonic never modifies it.

## What must be backed up

1. **`vibesonic.db`** (plus `-wal`/`-shm` if present — see below). This
   is the only thing whose loss is unrecoverable: it holds every user
   account, password/API-key hash, the entire scanned library index,
   playlists, favorites/ratings, play history, podcast subscriptions,
   share links, and configuration stored in the `settings` table.
2. **`podcasts/`**, if you don't want to re-download subscribed
   episodes after a restore.
3. Anything you passed via `VIBESONIC_*` environment variables
   (systemd unit, Docker Compose file, `.env`) — these aren't stored in
   the database and won't come back from a database restore alone.

## What does not need to be backed up

- **`cache/covers/`** — purely a derived cache, regenerated
  automatically the first time each cover art size is requested again.
  Safe to delete at any time, including while VibeSonic is running.
- **Your music files** — back these up through whatever process you
  already use for your media library; VibeSonic treats them as
  read-only input, never as its own state.

## Correct SQLite backup: mind the WAL

VibeSonic runs SQLite in **WAL (write-ahead log) mode** for concurrency
(`internal/database/database.go`: `PRAGMA journal_mode=WAL`). In WAL
mode, recently-committed data can live in the `vibesonic.db-wal` file
rather than in `vibesonic.db` itself, and isn't merged back
("checkpointed") into the main file on any fixed schedule.

**Do not just `cp vibesonic.db` from a live server.** A plain file copy
of `vibesonic.db` alone, taken while VibeSonic is running, can miss data
that only exists in the `-wal` file, or copy `vibesonic.db` and
`vibesonic.db-wal` at slightly different points in time and produce an
inconsistent pair. Either failure mode can leave you with a backup that
looks fine (opens without error) but is silently missing recent writes
or is outright corrupt.

Use one of these instead:

### Option A — stop the server, then copy (simplest, requires downtime)

```sh
systemctl stop vibesonic
cp /var/lib/vibesonic/vibesonic.db* /path/to/backup/
systemctl start vibesonic
```

On a clean shutdown SQLite checkpoints and closes the WAL cleanly, so a
plain copy of the (possibly WAL-less) database directory taken while the
process is stopped is always consistent.

### Option B — the SQLite online backup API, via the `sqlite3` CLI (no downtime)

`sqlite3`'s `.backup` command uses SQLite's own backup API, which
correctly handles an in-progress WAL and produces a consistent snapshot
without stopping VibeSonic or blocking writers for more than the brief
final copy step:

```sh
sqlite3 /var/lib/vibesonic/vibesonic.db ".backup /path/to/backup/vibesonic.db"
```

Do this on a schedule (cron/systemd timer) and rotate the output.

### Option C — filesystem snapshot (LVM, ZFS, Btrfs)

A crash-consistent filesystem snapshot of the whole `DataDir` (taken
atomically, e.g. `zfs snapshot` or an LVM snapshot) is also safe — SQLite
in WAL mode is designed to recover cleanly from a snapshot equivalent to
an ungraceful power loss, the same way it recovers on the next open
after a crash. Plain `rsync`/`cp` while the server is running is **not**
equivalent to this, since it isn't atomic across the `.db`/`-wal`/`-shm`
trio.

## Restoring

1. Stop VibeSonic.
2. Replace `vibesonic.db` (and `-wal`/`-shm` if you backed those up too)
   with the backup copy.
3. Restore `podcasts/` if you backed it up.
4. Start VibeSonic. It runs pending migrations automatically on
   startup, same as any other launch.

If you only have a `vibesonic.db` from Option B/C without matching
`-wal`/`-shm` files, that's fine — `.backup` and filesystem snapshots
both produce a database file that's already fully checkpointed/consistent
on its own.