# Backup and recovery

## Locate the database

The bundled default is `profile:memory-spaces-v4.sqlite`. Installed packages resolve it to the owning DSH profile directory. A linked source checkout cannot infer a profile and must set `DSH_MEMORY_SPACES_DATABASE_PATH` or an explicit config path. Never point two profiles at one file unless shared storage is intentional and separately tested.

## Back up

1. Stop every DSH process using the profile.
2. Record the DSH and plugin versions and database path.
3. Copy the SQLite file and any sibling `-wal` and `-shm` files as one set, or use a SQLite online-backup method while the database is open.
4. Protect the copy as sensitive unencrypted conversation data.
5. Restore a copy in an isolated profile and run `pnpm doctor:fts -- <database-path>` plus `PRAGMA integrity_check` before relying on it.

Schema 3 migration first creates a consistent sibling file named like `.schema-3-backup-<time>-<id>.sqlite` with `VACUUM INTO`, then migrates inside `BEGIN IMMEDIATE`. Unknown schemas fail without changing the schema version or journal mode. The automatic backup is not a retention policy and may itself contain sensitive data.

## Legacy global database

Version 4 does not silently adopt a previous global `$DSH_HOME/memory-spaces-v3.sqlite`. Stop DSH, make an external backup, identify the exact target profile, and copy the legacy database to that profile as `memory-spaces-v4.sqlite`. Start only that profile and inspect the generated schema-3 backup and migration result. Do not copy one legacy file into multiple writable profiles.

## Restore

Stop DSH, preserve the failed database for analysis, replace the complete database/WAL/SHM set with the selected backup, then start one process. Verify schema version, `PRAGMA integrity_check`, FTS counts, space/member counts, version chains, snapshot revocation/use counts, and one synthetic recall flow. Restoration can reintroduce revoked links or deleted/provenance-cleared values that existed at backup time.

## Package upgrade, removal, and rollback

Stop the Web process and complete the backup procedure above before changing the package version. Upgrade by running `dsh plugin --profile web add dsh-memory-spaces@<version>` with the intended exact version, inspect `dsh --profile web --dump-config`, restart Web, and verify a synthetic save-and-recall flow.

`dsh plugin --profile web remove dsh-memory-spaces` removes the package from the Profile configuration but does not delete the profile-local database, its WAL/SHM siblings, or backups. Reinstalling the same version reconnects the retained database. Full data removal is a separate destructive operation: resolve and inspect the exact Profile paths before deleting the complete database set and backups.

For a version rollback, install the earlier exact package version. If the newer version changed the schema, restore the database backup recorded for the target version before starting Web. An older plugin rejects an unknown schema rather than modifying it, so package rollback without the matching data backup is not a database downgrade.

Logical deletion and provenance clearing are application operations, not secure physical erasure. SQLite free pages, WAL, storage media, backups, provider logs, and DSH Session logs can retain related data.