Backup and restore documentation #336
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
|
Contributor
There was a problem hiding this comment. Specifically note that clients will continue syncing the old data during reprocessing - no new changes will be synced here until reprocessing completed. |
||
|
|
||
| <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) | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not sure if this reprocessing will actually happen automatically in all cases - we need to test this for each one.