Platform
Backups & recovery
Understand SQL backups, Google Drive copies, application recovery files, and what remains available during an outage.
Getting started
Know the backup type
Dashboard configuration exports, host file snapshots, SQL database dumps, and application recovery JSON protect different data. A host file backup does not automatically include a remote MySQL database.
Connect Google Drive
The bot operator runs scripts/setup_drive_backup.py with --client-json pointing to the downloaded OAuth client file. Keep the generated configuration private and upload it as backups/drive-config.json on the host, then restart the updated bot.
Verify a real export
The running bot attempts a backup on startup and then hourly. Current Drive uploads are .sql database exports. Check the Drive folder for a recent, non-empty file. A configuration file alone does not prove backups are running.
Understand downtime
The in-process backup loop cannot run when its host or bot process is offline. scripts/scheduled_backup.py can be scheduled independently, but its machine must remain online and able to reach the database and Drive. No job can export a database while that database is unavailable.
Restore to an empty test database
Download the .sql file and import it using your host's MySQL import tool into a separate empty database first. Check tables, row counts, application answers, and server settings before changing production connections. See deploy/mysql-restore-check.md for the operator drill.
Handle older encrypted archives
Legacy .ncbackup files are not SQL imports. Use scripts/recover_drive_backup.py with --backup, --config, and --output to authenticate and decrypt the archive, then inspect the extracted database.sql. Keep the original encryption configuration for those archives.
Keep recovery copies separate
Application Types can select a private recovery channel for answer snapshots. Those JSON files are application evidence, not a full database restore. Restrict access because both SQL exports and recovery files contain private information.
Settings reference
Use this reference when you need to check what a setting does.
Current database export; use your MySQL host's import tool.
Legacy encrypted archive requiring the original configuration to decrypt.
Private OAuth and installation configuration; not the database backup.
Application-specific answer snapshot; not a full SQL database.
Runs within the online bot process; does not survive a host outage by itself.
How it works
Here’s what happens once you’ve finished setup.
- 1Export
Read the available database into a SQL file.
- 2Upload
Send the completed file to the configured Drive folder.
- 3Verify
Confirm freshness and non-zero size; retain a protected copy.
- 4Restore drill
Import into a separate empty test database and validate before production recovery.
Example
Use the newest valid Drive SQL export, import into a separate empty MySQL database, verify records, then deliberately reconnect the application once recovery is approved.
Tips
A backup only contains data present at its export time. It cannot recover an answer that never reached durable storage.
When Drive upload fails, the SQL export is kept locally under backups/drive for recovery. Local files can still be lost with the host.
New SQL exports are directly importable and are not encrypted .ncbackup containers. Restrict Drive folder access.
Things to know
Do not overwrite production merely to test a backup. A restore can replace or conflict with existing records.
Database exports may contain records for every server hosted by that installation. They are operator backups, not a file to share with individual server staff.
Troubleshooting
Check bot uptime, database connectivity, OAuth configuration, Drive access, and backup health logs.
Do not treat it as a valid backup. Obtain a completed export and inspect it.
The local backup loop could not run. Use the last successful off-host copy; it may not include recent changes.