> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bugspray.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade and recover without losing evidence

> Back up the whole deployment, then validate the candidate on isolated data.

Record the exact installed source commit, package lockfile, runtime, configuration and image digests. Package version `0.1.0` alone does not identify a tested release or maintenance commitment.

## Local Node and SQLite

1. Stop the instance cleanly before a consistent backup. Preserve the entire private data directory: SQLite state, artifacts, authentication profiles and any separately stored configuration/keys. A live database copy must account for journals/WAL.
2. Restore into a **different private directory**. Run the candidate with `QA_SUITE_DATA_DIR` pointing there and a free port; never let old and new processes share writable data.
3. Run `pnpm install --frozen-lockfile` and `pnpm build`, then start the candidate with repros disabled. Startup initializes/upgrades local schema; hosted D1 commands are not the SQLite migration path.
4. Verify findings, artifacts, catalog history and profiles. Test optional integrations deliberately after data verification. A successful startup alone is not a restore test.
5. Retain the pre-upgrade backup until recovery is demonstrated. Never delete `data/` to resolve an upgrade error.

## Hosted D1, R2 and broker

Back up database records **and** private objects, tenant/broker configuration, signing material and encryption/recovery keys. A database export cannot recover missing video or lost profile keys. Review all migrations between installed and candidate commits and the required code/schema ordering. Restore into isolated resources and verify authorized artifact access.

Older checkouts may contain operator manifests. Preserve them through the [deployment preservation procedure](https://github.com/SynclyUS/bugspray/blob/main/docs/deployment.md) before upgrading to a manifest-free source tree. A metadata export is not a D1/R2 backup or proof of managed key recovery.

Use the reviewed release path, with the exact candidate canary, release eligibility and current migration-exception reviews. Build success or a Worker dry-run does not establish live launch readiness.

## Roll back deliberately

Keep prior code/image identities available. Confirm old code can read the new schema before rolling it back; prefer schema-compatible rollback or reviewed forward repair. Do not automatically reverse DDL or delete additive tables. Backup restoration may discard later writes, requiring an operator decision about reconciliation.

The maintained [upgrade runbook](https://github.com/SynclyUS/bugspray/blob/main/docs/upgrading.md) and [observability guide](https://github.com/SynclyUS/bugspray/blob/main/docs/observability.md) cover operational details. Retention periods and backup ownership are deployment policy, not implied by the UI.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.