Restoring Data

Data restoration is a critical capability of FireBackup. This guide covers how to restore from backups, preview data before restoration, and handle various restore scenarios.

Restore Overview

FireBackup supports multiple restore scenarios:

Scenario	Description	Method
Full Restore	Restore entire backup to project	Standard restore
Selective Restore	Restore specific collections	Collection filter
Point-in-Time	Restore to a specific timestamp	PITR restore
Cross-Project	Restore to different project	Target override
Preview	View data before restoring	Preview mode

Prerequisites

Before restoring data:

1. Valid backup - Backup must be verified and accessible
2. Target project access - OAuth token or service account with write access
3. Sufficient IAM permissions - roles/datastore.importExportAdmin on target
4. Encryption key - If backup is encrypted

Restore Impact

Restoring data will overwrite existing documents with matching IDs. This operation cannot be undone. Always preview and verify before restoring to production.

Restoring from a Backup

Step 1: Select Backup

1. Navigate to Backups in the sidebar
2. Find the backup you want to restore
3. Click Restore in the actions menu

Step 2: Choose Restore Mode

Mode	Description	Use Case
Full Restore	Restore all collections	Complete recovery
Selective Restore	Choose specific collections	Partial recovery

Step 3: Select Target Project

By default, data restores to the original project. You can override this:

1. Same Project - Restore to source project
2. Different Project - Select another connected project

Cross-Project Restore

Ensure the target project has appropriate schema and indexes for the restored data.

Step 4: Configure Options

Option	Description	Default
Merge Mode	How to handle existing data	Overwrite
Include Auth	Restore Firebase Auth users	From backup
Dry Run	Preview without writing	Off

Merge Modes

Mode	Behavior
Overwrite	Replace existing documents
Skip Existing	Only restore missing documents
Merge	Merge fields into existing documents

Step 5: Preview (Recommended)

Before restoring, preview what will change:

1. Click Preview Changes
2. Review the diff:
   • Documents to be added
   • Documents to be modified
   • Documents to be deleted (if applicable)

Step 6: Execute Restore

1. Review the restore summary
2. Type the project name to confirm
3. Click Start Restore

Monitoring Restore Progress

Real-Time Status

During restore, you'll see:

• Status: Current operation phase
• Progress: Percentage complete
• Documents: Count restored
• Errors: Any issues encountered

Restore Phases

1. Initializing - Preparing restore job
2. Downloading - Fetching backup from storage
3. Decrypting - Decrypting backup data
4. Decompressing - Decompressing data
5. Validating - Verifying data integrity
6. Restoring - Writing to Firestore
7. Finalizing - Cleanup and verification
8. Completed - Restore finished

Selective Restore

Restoring Specific Collections

1. In the restore dialog, select Selective Restore
2. Check the collections to restore
3. Subcollections are included by default

Restoring Specific Documents

For granular restoration:

1. Use Preview to browse backup contents
2. Identify specific documents needed
3. Use the API for document-level restore

# Restore specific documents via API
curl -X POST https://api.firebackup.io/api/v1/backups/restore \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "backupId": "backup-123",
    "collections": ["users"],
    "documentIds": ["user-456", "user-789"]
  }'

Cross-Project Restore

Restore data to a different Firebase project:

Use Cases

• Environment promotion: Dev → Staging → Production
• Data migration: Old project → New project
• Testing: Production data → Test environment
• Disaster recovery: Primary → Secondary region

How to Cross-Project Restore

1. Ensure target project is connected to FireBackup
2. Select backup from source project
3. In restore dialog, select target project
4. Complete restore process

Data Scrubbing

When restoring production data to test environments, consider removing sensitive fields using the selective restore feature.

Preview Backup Contents

Before restoring, you can explore backup contents:

Accessing Preview

1. Navigate to the backup details
2. Click Preview tab
3. Browse collections and documents

Preview Features

• Collection browser - Navigate collection hierarchy
• Document viewer - View document fields and values
• Search - Find specific documents
• Export - Download preview data as JSON

Preview vs Actual Data

Compare backup contents with current data:

1. Click Compare with Live
2. View differences:
   • Added documents (in backup, not in live)
   • Modified documents (different values)
   • Deleted documents (in live, not in backup)

Restore Verification

After restore completes:

Automatic Verification

FireBackup automatically verifies:

• Document count - Matches expected count
• Collection structure - All collections present
• Sample validation - Random document spot checks

Manual Verification

Recommended post-restore checks:

1. Spot check critical documents - Verify key data
2. Run application tests - Ensure functionality
3. Check indexes - Verify Firestore indexes work
4. Monitor for errors - Watch application logs

Restore History

View past restore operations:

1. Navigate to Backups in the sidebar
2. Click Restore History tab
3. View all restore operations

Field	Description
Date	When restore occurred
Backup	Source backup
Target	Destination project
Status	Success, Failed, or In Progress
Documents	Number of documents restored
Duration	Time to complete

Handling Restore Failures

Common Failure Scenarios

Permission Denied

Error: IAM permission denied

Solution:

1. Verify OAuth token is valid
2. Check IAM roles on target project
3. Re-authenticate if needed

Quota Exceeded

Error: Firestore write quota exceeded

Solution:

1. Wait for quota reset
2. Restore in smaller batches
3. Request quota increase from Google

Network Timeout

Error: Connection timeout during restore

Solution:

1. Check network connectivity
2. Retry the restore
3. For large restores, contact support

Partial Restore Recovery

If restore fails mid-operation:

1. Note the error message and last processed document
2. Check what was restored (may be partial)
3. Fix the underlying issue
4. Retry with Skip Existing mode to resume

Best Practices

Before Restore

1. Always preview first - Understand what will change
2. Backup current data - Create a backup before restoring
3. Test in staging - Try restore in non-production first
4. Notify stakeholders - Communicate planned restore
5. Schedule maintenance - Restore during low-traffic periods

During Restore

1. Monitor progress - Watch for errors
2. Don't interrupt - Let restore complete
3. Keep session active - Stay logged in

After Restore

1. Verify data - Spot check critical documents
2. Test application - Ensure functionality works
3. Document the restore - Record what was restored and why
4. Monitor application - Watch for issues

Restore API

For programmatic restore operations:

Start Restore

POST /api/v1/backups/restore
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "backupId": "backup-123",
  "targetProjectId": "my-project",
  "options": {
    "mergeMode": "overwrite",
    "collections": ["users", "orders"],
    "dryRun": false
  }
}

Check Restore Status

GET /api/v1/backups/restore/{restoreJobId}
Authorization: Bearer YOUR_TOKEN

See API Reference for complete documentation.

Next Steps

• Configure Point-in-Time Recovery
• Set up backup schedules
• Learn about storage destinations
• API Reference for restore