Backup and restore documentation

docs.json

@@ -173,7 +173,8 @@
                   "usage/lifecycle-maintenance/handling-write-validation-errors",
                   "usage/lifecycle-maintenance/upgrading-the-client-sdk",
                   "usage/lifecycle-maintenance/postgres-maintenance",
-                  "usage/lifecycle-maintenance/compacting-buckets"
+                  "usage/lifecycle-maintenance/compacting-buckets",
+                  "usage/lifecycle-maintenance/restoring-source-database"
                 ]
               },
               {
@@ -395,6 +396,7 @@
                   "self-hosting/lifecycle-maintenance/telemetry",
                   "self-hosting/lifecycle-maintenance/metrics",
                   "self-hosting/lifecycle-maintenance/diagnostics",
+                  "self-hosting/lifecycle-maintenance/backup-and-recovery",
                   "self-hosting/lifecycle-maintenance/migrating",
                   "self-hosting/lifecycle-maintenance/multiple-instances"
                 ]

self-hosting/lifecycle-maintenance.mdx

@@ -126,10 +126,6 @@ migrations:
 Note that if you disable automatic migrations, and do not run the migration job manually,
 the service may run with an outdated storage schema version. This may lead to unexpected and potentially difficult-to-debug errors in the service.
 
-## Backups
+## Backup and Recovery
 
-We recommend using Git to backup your configuration files.
-
-None of the containers use any local storage, so no backups are required there.
-
-The sync bucket storage database may be backed up using the recommendations for the storage database system. This is not a strong requirement, since this data can be recovered by re-replicating from the source database.
+For detailed information on backup strategies and recovery procedures, including how PowerSync handles database restoration and re-sync scenarios, see the [Backup and Recovery](/self-hosting/lifecycle-maintenance/backup-and-recovery) guide.

self-hosting/lifecycle-maintenance/backup-and-recovery.mdx

@@ -0,0 +1,29 @@
+---
+title: "Backup Considerations"
+description: "What to back up for PowerSync self-hosted deployments"
+---
+
+## Overview
+
+PowerSync self-hosted deployments have minimal backup requirements. This page covers what you need to consider.
+
+## Configuration Files
+
+We recommend using Git to version control and backup your PowerSync configuration files:
+
+- `powersync.yaml` - Service configuration
+- [`sync-rules.yaml`](/usage/sync-rules)
+
+PowerSync containers use no persistent storage - configuration is mounted from the host and all data is stored in external databases, so no container-level backups are required.
+
+## Bucket Storage Database
+
+The [sync bucket storage](/usage/sync-rules/organize-data-into-buckets) database (MongoDB or Postgres) may be backed up using standard database backup procedures. However, this is optional since bucket data can be fully recovered by re-replicating from the source database.
+
+<Note>
+Bucket storage contains derived data from your source database. If lost, PowerSync can rebuild it automatically through [replication](/architecture/powersync-service#replication).
+</Note>
+
+## Source Database
+
+For guidance on what happens when you restore your source database, including multi-tenant recovery scenarios, see [Restoring Your Source Database](/usage/lifecycle-maintenance/restoring-source-database).

usage/lifecycle-maintenance/restoring-source-database.mdx

@@ -0,0 +1,80 @@
+---
+title: "Restoring your source database"
+description: "How PowerSync handles source database restores and what to expect during reprocessing"
+---
+
+## Overview
+
+Backing up your source database does not affect PowerSync operation. However, restoring from a backup typically requires PowerSync to perform a **full reprocess** of the data.
+
+This page explains what happens when you restore your [source database](/installation/database-setup) and how to plan for it.
+
+## What happens after a database restore
+
+When you restore your source database from a backup:
+
+- PowerSync's replication state may become invalid
+- The PowerSync Service will need to reprocess data from the restored database
+- The reprocessing happens automatically
+- Clients can continue syncing during reprocessing, though they may experience temporary delays
+
+<Warning>
+A full reprocess can take significant time for large datasets. Plan maintenance windows accordingly when restoring source database backups.
+</Warning>
+
+## Planning for database restores
+
+When planning source database backup and recovery:
+
+1. **Test restore procedures** in a staging environment to understand reprocessing duration
+2. **Plan maintenance windows** during low-traffic periods for database restores
+3. **Consider data volume** when estimating recovery time - larger datasets take longer to reprocess
+
+### Factors affecting reprocessing time
+
+- **Data volume**: Total size of data in synced tables
+- **Sync rules complexity**: Number of tables, joins, and transformations
+- **Database performance**: CPU, memory, and I/O capacity
+
+For more details on performance considerations, see [Performance and Limits](/resources/performance-and-limits).
+
+## Multi-tenant considerations
+
+For multi-tenant architectures using a shared database with tenant isolation through [sync rules](/usage/sync-rules), you can perform tenant-specific recovery without triggering a full reprocess.
+
+### Tenant-specific recovery
+
+Instead of restoring the entire database, restore only the affected tenant's data:
+
+1. **Backup and restore tenant-specific data** using your source database's native tools with filtering (e.g., `WHERE tenant_id = X`)
+2. **PowerSync detects restored data as incremental changes** and [replicates them](/architecture/powersync-service#replication) automatically
+3. **Other tenants continue operating** without interruption (assuming replication keeps pace)
+
+<Tip>
+Implement soft deletes for accidental deletions to avoid database-level recovery in many scenarios. See [Handling Update Conflicts](/usage/lifecycle-maintenance/handling-update-conflicts) for related patterns.
+</Tip>
+
+### Performance considerations
+
+Large tenant restores increase replication volume. Monitor:
+
+- **Replication lag** during restore operations using [Monitoring and Alerting](/usage/tools/monitoring-and-alerting)
+- **Data volume impact** - high volumes can affect all tenants if replication falls behind
+
+## Database-specific notes
+
+Different [source databases](/installation/database-setup) use different replication mechanisms:
+
+- **Postgres:** Logical replication slots (see [Postgres Maintenance](/usage/lifecycle-maintenance/postgres-maintenance) for slot management)
+- **MongoDB:** Change stream resume tokens
+- **MySQL:** Binary log positions (GTID)
+- **MSSQL:** Change Data Capture (CDC)
+
+The specific behavior after a restore may vary by database type. PowerSync uses checkpoints to maintain [consistency](/architecture/consistency#consistency) during the recovery process.
+
+## Related resources
+
+- [Architecture Overview](/architecture/architecture-overview)
+- [PowerSync Service](/architecture/powersync-service)
+- [Sync Rules](/usage/sync-rules)
+- [Troubleshooting](/resources/troubleshooting)