diff --git a/guides/backup-restore-clickhouse.md b/guides/backup-restore-clickhouse.md new file mode 100644 index 0000000..8f17fa3 --- /dev/null +++ b/guides/backup-restore-clickhouse.md @@ -0,0 +1,135 @@ +Guide to backing up and restoring `plausible_events_db`. Based on ["Backup and Restore" from ClickHouse.](https://clickhouse.com/docs/en/operations/backup/) + +**Note:** following this guide you'd need to stop some containers and it would make your plausible instance temporarily unavailable. + +--- + +### Plan + +1. dump contents of the Plausible tables (events, sessions, imported\_\*) to files in a mounted volume +1. load dumps from the mounted volume into `plausible_events_db` + +--- + +### Backup + +1. Add backup config to allow reading backup files in the ClickHouse container + +```console +$ touch clickhouse/backups.xml +``` + +```xml + + + + + local + /backups/ + + + + + backups + /backups/ + + +``` + +2. Add backups volume to `plausible_events_db` in your `docker-compose.yml` + +```diff + plausible_events_db: + image: clickhouse/clickhouse-server:22.6 + volumes: + - event-data:/var/lib/clickhouse + - ./clickhouse/:/etc/clickhouse-server/config.d/ ++ - ./clickhouse-backups:/backups +``` + +3. Stop relevant containers to avoid writing to old `plausible_events_db` + +```console +> docker compose stop plausible plausible_events_db +[+] Running 2/2 + ⠿ Container hosting-plausible-1 Stopped 6.5s + ⠿ Container hosting-plausible_events_db-1 Stopped 0.2s +``` + +4. Restart `plausible_events_db` container to attach volume + +```console +> docker compose up plausible_events_db -d +[+] Running 1/1 + ⠿ Container hosting-plausible_events_db-1 Started 0.3s +``` + +5. Dump old `plausible_events_db` contents to backup files + +```console +> docker compose exec plausible_events_db sh -c "clickhouse-client --query 'BACKUP TABLE plausible_events_db.events TO Disk('backups', 'events.zip')'" +> docker compose exec plausible_events_db sh -c "clickhouse-client --query 'BACKUP TABLE plausible_events_db.sessions TO Disk('backups', 'sessions.zip')'" +> docker compose exec plausible_events_db sh -c "clickhouse-client --query 'BACKUP TABLE plausible_events_db.imported_visitors TO Disk('backups', 'imported_visitors.zip')'" + +# etc. +``` + +**TODO:** script + +6. (Optional) verify backup went OK + +```console +> ls backups +events.zip sessions.zip imported_visitors.zip ... +``` + +7. Move the backups somewhere, like a different host + +### Restore + +1. Ensure relevant containers are stopped + +```console +> docker compose stop plausible plausible_events_db +[+] Running 2/2 + ⠿ Container hosting-plausible-1 Stopped 0.0s + ⠿ Container hosting-plausible_events_db-1 Stopped 0.2s +``` + +3. Ensure backup config from step 1 and backups mount from step 2 are still present. + +4. Load data into from backups. **TODO:** User + permissions + +```console +> docker compose exec plausible_events_db sh -c "clickhouse-client --query 'RESTORE TABLE plausible_events_db.events FROM Disk('backups', 'events.zip')'" +> docker compose exec plausible_events_db sh -c "clickhouse-client --query 'RESTORE TABLE plausible_events_db.sessions FROM Disk('backups', 'sessions.zip')'" +> docker compose exec plausible_events_db sh -c "clickhouse-client --query 'RESTORE TABLE plausible_events_db.imported_visitors FROM Disk('backups', 'imported_visitors.zip')'" + +# etc. +``` + +6. Start all other containers + +```console +> docker compose up -d +[+] Running 4/4 + ⠿ Container hosting-plausible_events_db-1 Running 0.0s + ⠿ Container hosting-mail-1 Running 0.0s + ⠿ Container hosting-plausible_db-1 Started 0.5s + ⠿ Container hosting-plausible-1 Started 0.5s +``` + +7. (Optional) Remove backups from `docker-compose.yml` and your filesystem + +```diff + plausible_events_db: + image: clickhouse/clickhouse-server:22.6 + volumes: + - event-data:/var/lib/clickhouse + - ./clickhouse/:/etc/clickhouse-server/config.d/ +- - ./clickhouse-backups:/backups +``` + +``` +> rm -rf ./clickhouse-backups +``` diff --git a/guides/backup-restore-postgres.md b/guides/backup-restore-postgres.md new file mode 100644 index 0000000..5d17c42 --- /dev/null +++ b/guides/backup-restore-postgres.md @@ -0,0 +1 @@ +Please see [upgrading `plausible_db` (PostgreSQL)](upgrade/postgres.md) for backup/restore steps.