Configure and validate backups for Google Cloud Firestore

Set up and validate backups for Google Cloud Firestore.

Onboard Google Cloud Firestore

Onboard a Google Cloud Firestore instance to begin protecting your Google Cloud Firestore data. During onboarding, you connect to Google Cloud Firestore, choose the content to protect, assign a backup plan, and create the backup configuration.

Start the configuration

1. From the Command Center navigation pane, go to Protect > AI & Analytics.

2. Click Add AI application.

3. Select Google Cloud Firestore, and then click Next.

Specify credentials

Cloud App Connection Details

• In the Name field, provide a display name for this Google Cloud Firestore backup configuration.

Configure Credential

• Service Account Email: Enter the client_email value from the Service Account JSON key file.

• Private Key: Paste the entire PEM-encoded private key from the private_key field in the JSON key file, including the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- markers.

• GCP Project Name: Enter the GCP project ID where your Firestore database is located.

• Region: Enter the GCP region where your Firestore database is located.

• Database Name: Enter the Firestore database name (for example, (default) for the default database).

• GCS Bucket Name: Enter the name of the GCS bucket where backups will be stored.

Choose the backup content

• Click the pencil (edit) icon next to Content.

• Choose either: select the collections shown in the browse tree, or define rules to select content for the subclient.

Top-level collections are displayed in the browse tree. To back up all collections, use the special value "ALL" in the content rules. Tag-based discovery is also supported to automatically include or exclude collections matching GCP resource tag criteria.

Select a backup plan

• Select an existing backup plan, or click + to create a new one.

• After you create a backup plan, you can select it when you onboard additional Google Cloud Firestore instances.

Review summary

• Review the instance name, plan name, schedule, and backup content.

• Click Submit.

Run a backup

1. From the Command Center navigation pane, go to Protect > AI & Analytics.

2. For the application that you want to back up, click the action button , and then click Back up now to run a full backup.

3. Monitor job progress in the Jobs view.

Firestore enforces 1 concurrent export or import operation per database at a time. Long-running export operations are polled every 10 seconds until the operation completes successfully or fails.

Validate the backup

Verify the configuration

After you assign the backup plan, confirm that:

• The Google Cloud Firestore instance appears in the AI applications list with the correct GCP project name and region.

• The browse tree displays the top-level collections from your Firestore database.

Confirm that the backup completed successfully

1. From the Command Center navigation pane, go to Monitor > Jobs.

2. Locate the completed backup job.

3. Verify that the job status is Completed.

4. Check the job details to confirm:

5. Collections backed up: The number of collections exported (or 1 if non-granular mode)

6. Storage used: The size of the exported data in the GCS bucket

7. Duration: The time taken to complete the export operation

Test a restore

1. From the Jobs view, select the completed backup job.

2. Click Restore.

3. Select one or more collections to restore.

4. Choose the restore destination: same database (in place) or a different database (out of place).

5. Click Submit.

6. Verify that the restore completes with status Completed and that the data matches the original.

For complete restore procedures, see Restore Google Cloud Firestore data.

Common causes of failures and what to check first

Configuration and permission issues

• Permission denied on Firestore export: The Service Account is missing the roles/datastore.importExportAdmin role. Verify the role assignment in the Google Cloud Console IAM settings.

• Permission denied on GCS bucket: The Service Account is missing the roles/storage.objectAdmin role or the bucket doesn't exist. Verify the role assignment and confirm the bucket exists in the specified region.

• Invalid credential: The client_email or private_key was not copied correctly from the JSON key file. Verify that you copied the complete PEM key including the header and footer markers.

• Database not found: The specified database name doesn't exist in the GCP project. Verify the database name in the Google Cloud Console Firestore settings.

Backup job failures

• Missing change stream for incremental backup: One or more collections selected for incremental backup don't have a change stream configured. Either configure change streams for all collections or run a full backup instead.

• Incremental backup converted to full: The last successful backup is older than 7 days. This is expected behavior. The job automatically converts to a full backup when the incremental window exceeds 7 days.

• Concurrent operation limit: Firestore allows only 1 export or import operation per database at a time. Wait for the current operation to complete before starting another backup.

• Export operation timeout: The export operation is taking longer than expected. Check the Firestore database size and consider scheduling backups during off-peak hours.

Restore failures

• Target database not found: The destination database for out-of-place restore doesn't exist. Create the target database in the destination GCP project before running the restore.

• Composite index already exists: The restore encountered an HTTP 409 error when creating a composite index that already exists in the destination. This is expected behavior and is silently skipped.

• Backup bucket not accessible: The original GCS bucket where the backup was stored is no longer accessible. Verify that the bucket exists and the Service Account has read access.