docs(management): move SQLite Backup & Restore out of Tools category
This commit is contained in:
2 files changed
-71
No files matched your search
@@ -1,5 +0,0 @@
|
|||||||
{
|
|
||||||
"label": "Tools",
|
|
||||||
"collapsed": true,
|
|
||||||
"position": 10
|
|
||||||
}
|
|
||||||
@@ -1,66 +0,0 @@
|
|||||||
---
|
|
||||||
title: SQLite Backup & Restore
|
|
||||||
tags:
|
|
||||||
- Management
|
|
||||||
- Backup
|
|
||||||
- Restore
|
|
||||||
- SQLite
|
|
||||||
---
|
|
||||||
|
|
||||||
The SQLite Backup & Restore feature allows you to export and import your entire Homarr database as a portable ZIP file. This is useful for creating backups, migrating between instances, or recovering from failures.
|
|
||||||
|
|
||||||
:::info SQLite only
|
|
||||||
This feature is only available when using the SQLite database driver (`DB_DRIVER=better-sqlite3`). MySQL and PostgreSQL users should use their respective database backup tools.
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Accessing Backup & Restore
|
|
||||||
|
|
||||||
Navigate to **Management → Tools → Backup** from the sidebar. This page is only visible when running with SQLite.
|
|
||||||
|
|
||||||
## Exporting a Backup
|
|
||||||
|
|
||||||
Click the **Export** button to download a ZIP archive containing:
|
|
||||||
|
|
||||||
- **`db.sqlite`** — A consistent snapshot of your database (created via `VACUUM INTO`)
|
|
||||||
- **`metadata.json`** — Contains:
|
|
||||||
- `homarrVersion` — The version of Homarr that created the backup
|
|
||||||
- `exportedAt` — Timestamp of the export
|
|
||||||
- `dbDialect` — The database dialect (`sqlite`)
|
|
||||||
- `encryptionKey` — Your `SECRET_ENCRYPTION_KEY` (needed to decrypt integration secrets)
|
|
||||||
|
|
||||||
:::caution
|
|
||||||
The exported ZIP contains your encryption key and database. Store it securely and do not share it publicly.
|
|
||||||
:::
|
|
||||||
|
|
||||||
A confirmation dialog will ask you to type **"I understand"** before the export proceeds.
|
|
||||||
|
|
||||||
## Importing a Backup
|
|
||||||
|
|
||||||
1. Click the **Import** button and upload a previously exported ZIP file
|
|
||||||
2. Homarr analyzes the backup **entirely in your browser** using WebAssembly (sql.js) — no data is sent to the server during preview
|
|
||||||
3. The preview shows:
|
|
||||||
- **Entity counts** — How many boards, apps, users, integrations, etc. are in the backup
|
|
||||||
- **Board names** — A list of all boards contained in the backup
|
|
||||||
- **Migration status** — If the backup is from an older version, Homarr shows each pending database migration as animated timeline steps
|
|
||||||
4. Review the preview and type **"I understand"** to confirm
|
|
||||||
5. Homarr applies any pending migrations, re-encrypts integration secrets if the `SECRET_ENCRYPTION_KEY` differs between instances, and replaces the live database
|
|
||||||
6. The server automatically restarts to pick up the new database
|
|
||||||
|
|
||||||
:::tip
|
|
||||||
The import process is **backward-compatible** with older backups that used a separate `encryption-key.txt` file instead of embedding the key in `metadata.json`.
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Onboarding Integration
|
|
||||||
|
|
||||||
When setting up a fresh Homarr instance with SQLite, the onboarding wizard includes a **"Restore from SQLite backup"** option. This lets you upload a backup ZIP to bootstrap your new instance with data from a previous installation.
|
|
||||||
|
|
||||||
## Docker Restart Behavior
|
|
||||||
|
|
||||||
After a successful import, only the Next.js process restarts — nginx and Redis remain running. The `run.sh` script automatically restarts Next.js in a loop, so the application comes back online within seconds. Running `docker stop` still works gracefully.
|
|
||||||
|
|
||||||
## Best Practices
|
|
||||||
|
|
||||||
- **Back up regularly** — Create exports before major updates or configuration changes
|
|
||||||
- **Test restores** — Periodically verify your backups by importing them on a test instance
|
|
||||||
- **Secure storage** — Keep backups in an encrypted or access-controlled location since they contain your encryption key
|
|
||||||
- **Check versions** — Backups from newer versions cannot be imported into older Homarr instances; always import into the same or newer version
|
|
||||||
Reference in new issue
Block a user