Data, backups and upgrades#
Sugar's SQLite database, credential-encryption key, authentication secret and provider configuration form one recovery unit.
Back up#
Prerequisites#
- Know the active
SUGAR_DATA_DIR. - Preserve
SUGAR_CREDENTIAL_KEYandAUTH_SECRETin protected secret storage. - Use a maintenance window or SQLite's online backup API.
Back up SQLite online, or stop Sugar and copy the database with any WAL and SHM files. Record the source version and verify the backup in an isolated restore.
Upgrade#
- Back up data and secrets.
- Build the new source in a separate release directory.
- Run tests and require a successful production build.
- Stop the old process, switch the release and start one new process.
- Check loopback and public health before allowing clients.
Verify#
Sign in, list providers and models, create a temporary key and make a request. Confirm historical usage remains visible and stored credentials decrypt. Keep the previous release available until this verification completes.
If it does not work#
| Symptom | Check | Recovery |
|---|---|---|
| Provider credentials fail after a restore | Whether the credential key came from the same backup set | The database alone is not a backup — restore the matching key |
| An upgrade leaves the service unhealthy | What readiness names | See Health returns 503 |
| A restore starts serving traffic unexpectedly | Whether it was isolated first | Stop it; a restored gateway can call real providers and spend real money |
| Backups exist but have never been restored | — | Restore one into a disposable environment now; an untested backup is not a recovery plan |