# Backing up and restoring Quaeriva

Quaeriva keeps almost everything in the database. A backup is therefore small and quick, and there is no excuse for not having one before an upgrade.

---

## 1. What to back up

| Item | Where | Why |
|---|---|---|
| **The database** | your MySQL/MariaDB server | Every question, answer, user, setting, theme appearance value, menu, widget and advertisement |
| `config/database.local.php` | project root | Your database credentials. **Not** in the release archive, so a file-only restore loses it |
| `.env` | project root, if you created one | `APP_BASE_URL` for subdirectory installs, and `APP_ADMIN_PATH` if you renamed the admin panel. Losing it puts the panel back on `/admin` and can break every link on a subdirectory install |
| `public/themes/` | project root | Any theme you uploaded yourself |
| Uploaded images | wherever you host them | Quaeriva stores image URLs, not image files |

You do **not** need to back up the application code — it is the release archive, downloadable again at any time.

---

## 2. Backing up the database

### From cPanel

phpMyAdmin → select the database → **Export** → Quick → SQL → Go.

### From the command line

```
mysqldump -u USER -p --single-transaction --default-character-set=utf8mb4 DATABASE > quaeriva-backup.sql
```

`--default-character-set=utf8mb4` is not optional. Without it, Arabic text and emoji can be mangled in the dump itself, and you will not notice until you restore.

---

## 3. Restoring

1. Create an empty database, or empty the existing one.
2. Import the dump:
   ```
   mysql -u USER -p --default-character-set=utf8mb4 DATABASE < quaeriva-backup.sql
   ```
3. Restore `config/database.local.php`, editing it if the database name or credentials changed.
4. Open `/admin` and check the System page; run the **Upgrade database** action if the code is newer than the dump.

Restore the database and the files **as a pair**. A new database with old code, or old data with new code, is the state most likely to go wrong.

---

## 4. How often

- **Before every upgrade.** Without exception.
- **Before changing anything in Administration → Languages**, which can affect which content is reachable.
- Otherwise on a schedule that matches how much content you are willing to lose. A weekly dump is a reasonable floor for an active site; many hosts do this automatically — check whether yours does, and whether you can actually download the result.

**An untested backup is not a backup.** Restore one into a scratch database at least once, so you find out then rather than during an incident.

---

## 5. What is not in the database

- Uploaded theme files under `public/themes/`.
- Images you linked from elsewhere: Quaeriva stores the URL, so if the image host disappears, so does the image.
- Logs under `storage/logs/` — diagnostic only, safe to lose.

---

Back up the MySQL database plus `.env`, `config/site.local.php`, public uploads, and any trusted filesystem plugins/themes. Restore files first, restore the database, run migrations and doctor, then clear relevant caches. Never place database dumps under the public document root.
