Migration Guide

This guide covers migrating between FireBackup versions and migrating from other backup solutions to FireBackup.

Version Migration

Migrating from v1.x to v2.x

Version 2.0 introduced significant changes including multi-organization support, new API endpoints, and an updated backup format.

Breaking Changes

Area	v1.x	v2.x	Action Required
API Base URL	/api/	/api/v1/	Update all API calls
Authentication	Session cookies	JWT tokens	Update auth flow
Backup format	Single file	Chunked with metadata	Re-download old backups if needed
Webhooks	Custom format	Standard event format	Update webhook handlers
Organizations	None	Multi-org support	Migrate to organization model

Pre-Migration Checklist

v1.x to v2.x Migration Checklist:

• Backup current v1.x database
• Export existing backups (they'll remain accessible)
• Document current API integrations
• Review webhook handler code
• Schedule maintenance window
• Notify team members of migration
• Test migration in staging environment

Migration Steps

Step 1: Update Database Schema

# For self-hosted installations
cd /opt/firebackup

# Pull new version
git pull origin v2.0.0

# Run migrations
yarn prisma migrate deploy

Step 2: Update API Calls

Update all API endpoints to include the /v1/ prefix:

- POST /api/backups
+ POST /api/v1/backups

- GET /api/projects
+ GET /api/v1/projects

- POST /api/webhooks
+ POST /api/v1/webhooks

Step 3: Update Authentication

Migrate from session-based auth to JWT:

// v1.x - Session-based
fetch('/api/backups', {
  credentials: 'include'
});

// v2.x - JWT-based
fetch('/api/v1/backups', {
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  }
});

Step 4: Update Webhook Handlers

The webhook payload format changed in v2.x:

// v1.x format
{
  "event": "backup_completed",
  "backup_id": "abc123",
  "project": "my-project"
}

// v2.x format
{
  "id": "evt_abc123",
  "type": "backup.completed",
  "timestamp": "2024-01-15T10:30:45Z",
  "data": {
    "backup": {
      "id": "bkp_abc123",
      "projectId": "proj_abc123",
      "status": "completed"
    },
    "project": {
      "id": "proj_abc123",
      "name": "My Project"
    }
  }
}

Step 5: Create Organizations

v2.x requires all resources to belong to an organization:

# API call to create organization
curl -X POST https://api.firebackup.io/api/v1/organizations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"name": "My Organization"}'

# Migrate existing projects to organization
curl -X PATCH https://api.firebackup.io/api/v1/projects/proj_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"organizationId": "org_xyz789"}'

Rollback Procedure

If migration fails:

# Stop services
docker-compose down

# Restore database backup
pg_restore -d firebackup backup_pre_migration.sql

# Checkout v1.x
git checkout v1.5.0

# Restart services
docker-compose up -d

---

Migrating from v2.x to v3.x

Coming Soon

Version 3.0 is currently in development. This section will be updated with migration instructions before the v3.0 release.

Planned Breaking Changes:

• Removal of legacy webhook format
• New backup file format with improved compression
• Updated PITR storage format
• Deprecation of v1 API endpoints

---

Migration from Other Solutions

Migrating from Firebase Export/Import

If you're currently using Firebase's native export/import functionality, follow this guide to migrate to FireBackup.

Why Migrate?

Feature	Firebase Export	FireBackup
Automation	Manual or Cloud Functions	Built-in scheduling
Encryption	None	AES-256-GCM
Point-in-Time	❌	✅
Multi-cloud storage	GCS only	S3, GCS, Spaces
Incremental backups	❌	✅
Restore preview	❌	✅

Migration Steps

Step 1: Export Existing Backups

If you have existing Firebase exports you want to preserve:

# List existing exports
gcloud firestore export list --project=YOUR_PROJECT

# Exports are stored in GCS bucket
gsutil ls gs://YOUR_PROJECT.appspot.com/firestore_exports/

Step 2: Connect to FireBackup

1. Sign up at app.firebackup.io
2. Connect your Firebase project via OAuth
3. Configure your storage destination

Step 3: Create Initial Backup

# Create a full backup via API
curl -X POST https://api.firebackup.io/api/v1/backups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "proj_abc123",
    "type": "full",
    "collections": ["*"]
  }'

Step 4: Set Up Schedules

Replace Cloud Functions or manual exports with FireBackup schedules:

# Create daily backup schedule
curl -X POST https://api.firebackup.io/api/v1/schedules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "proj_abc123",
    "name": "Daily Backup",
    "cron": "0 2 * * *",
    "retention": 30,
    "enabled": true
  }'

Step 5: Disable Old Export System

// Remove Cloud Function if using scheduled exports
// firebase.json
{
  "functions": {
    // Remove or disable backup function
  }
}

---

Migrating from Custom Backup Scripts

If you have custom backup scripts, follow this guide to migrate.

Step 1: Inventory Current System

Document your current backup system:

Backup System Inventory:

• Backup frequency: ____________
• Collections backed up: ____________
• Storage location: ____________
• Retention policy: ____________
• Encryption: Yes / No
• Notifications: ____________
• Dependencies: ____________

Step 2: Map to FireBackup Features

Your System	FireBackup Equivalent
Cron job	Schedule with cron expression
S3 upload script	Storage destination (S3)
Email on failure	Webhook → Email service
Log to file	Audit logs + webhook

Step 3: Configure FireBackup

Replicate your backup configuration:

# Example: Daily backup at 2 AM with 30-day retention
curl -X POST https://api.firebackup.io/api/v1/schedules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "projectId": "proj_abc123",
    "name": "Daily Production Backup",
    "cron": "0 2 * * *",
    "collections": ["users", "orders", "products"],
    "retention": 30,
    "storageDestinationId": "stor_abc123"
  }'

Step 4: Run in Parallel

Run both systems simultaneously for verification:

Week 1: Run both systems, compare outputs
Week 2: Verify FireBackup restores correctly
Week 3: Primary: FireBackup, Backup: Old system
Week 4: Disable old system completely

Step 5: Decommission Old System

# Remove cron job
crontab -e
# Delete backup cron entry

# Archive old scripts
mv /opt/backup-scripts /opt/backup-scripts.deprecated

# Update documentation
# Document new backup process using FireBackup

---

Migrating from Third-Party Solutions

From Backupify/Spanning

1. Export any existing backups from your current provider
2. Connect Firebase projects to FireBackup
3. Set up equivalent schedules and retention
4. Verify backup integrity with test restores

From DBaaS Backup Features

If using database backup features from other providers:

1. Document current backup configuration
2. Set up FireBackup with equivalent settings
3. Run parallel for validation period
4. Transition notification systems
5. Disable old backup system

---

Data Migration

Importing Historical Backups

If you have existing backup files in a supported format, you can import them:

# Upload historical backup to storage
aws s3 cp old-backup.json s3://my-bucket/firebackup/historical/

# Register with FireBackup via API
curl -X POST https://api.firebackup.io/api/v1/backups/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "projectId": "proj_abc123",
    "storageDestinationId": "stor_abc123",
    "path": "firebackup/historical/old-backup.json",
    "metadata": {
      "createdAt": "2023-06-15T10:30:00Z",
      "type": "full",
      "source": "custom-script"
    }
  }'

Backup Format Conversion

Convert between backup formats if needed:

# Install FireBackup CLI
npm install -g @firebackup/cli

# Convert custom format to FireBackup format
firebackup convert \
  --input old-backup.json \
  --output firebackup-format.fbk \
  --format firebackup-v2

---

Environment Migration

Moving from SaaS to Self-Hosted

Organizations migrating from FireBackup SaaS to self-hosted:

Step 1: Request Data Export

Contact support@firebackup.io to request:

• Complete database export
• Backup metadata export
• Configuration export

Step 2: Set Up Self-Hosted Infrastructure

Follow the Installation Guide:

# Clone and configure
git clone https://github.com/firebackup/firebackup.git
cd firebackup
cp .env.example .env
# Configure environment variables

Step 3: Import Data

# Import database
psql -d firebackup < export.sql

# Run any migrations
yarn prisma migrate deploy

# Verify data
yarn prisma studio

Step 4: Reconfigure Storage Destinations

Storage credentials need to be reconfigured:

# Update storage credentials via API or dashboard
curl -X PATCH https://your-domain.com/api/v1/storage-destinations/stor_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "credentials": {
      "accessKeyId": "NEW_ACCESS_KEY",
      "secretAccessKey": "NEW_SECRET_KEY"
    }
  }'

Moving from Self-Hosted to SaaS

For organizations migrating to FireBackup SaaS:

1. Sign up at app.firebackup.io
2. Reconnect Firebase projects via OAuth
3. Reconfigure storage destinations
4. Set up new schedules
5. Existing backups remain in your storage

---

Troubleshooting Migration Issues

Common Issues

Database Migration Failures

# Check migration status
yarn prisma migrate status

# Reset and re-run if needed (CAUTION: data loss)
yarn prisma migrate reset

# Apply pending migrations manually
yarn prisma migrate deploy

API Compatibility Issues

If API calls fail after migration:

1. Check API version in request URL
2. Verify request body format matches new schema
3. Update authentication headers
4. Check for deprecated fields

Webhook Delivery Failures

After migrating webhook format:

// Update webhook handler to support both formats during transition
function handleWebhook(payload) {
  // Check format version
  if (payload.type) {
    // v2.x format
    handleV2Webhook(payload);
  } else if (payload.event) {
    // v1.x format (legacy)
    handleV1Webhook(payload);
  }
}

Getting Help

If you encounter migration issues:

1. Check the troubleshooting guide
2. Search the community forums
3. Contact support@firebackup.io for assistance
4. Enterprise customers: Contact your account manager

---

Related Documentation

• Changelog - Version history
• Installation Guide - Self-hosted setup
• API Reference - API documentation
• Support - Get help