Back up and restore data

Note: This feature is a public preview. This means that the functionality might change in backward-incompatible ways. A preview release is not subject to any SLA or deprecation policy and may receive limited or no support.

This page describes how to use the Cloud Firestore scheduled backups feature. Use backups to protect your data from application-level data corruption or from accidental data deletion.

Backups let you configure backup schedules to take daily or weekly backups of the specified database. You can then use these backups to restore data to a new database.

About backups

A backup is a consistent copy of the database at a point in time. The backup contains all data and index configurations at that point in time. A backup does not contain database time to live policies. A backup resides in the same location as the source database.

Backups have a configurable retention period and are stored until the retention period expires or until you delete the backup. Deleting the source database does not automatically delete related backups.

Cloud Firestore stores metadata related to backups and backup schedules related to a database. Cloud Firestore retains this metadata until all backups for the database expire or are deleted.

Creating or retaining backups does not affect the performance of reads or writes in your live database.

Costs

When you use backups, you're charged for the following:

• The amount of storage used by each backup.
• For a restore operation, you're charged based on the size of the backup.

For more details and exact rates, see the Pricing page.

Before you begin

This feature requires the Blaze pricing plan.

Required roles

To get the permissions that you need to manage backups and backup schedules, ask your administrator to grant you one or more of the following Identity and Access Management roles:

• roles/datastore.owner: Full access to the Cloud Firestore database

• The following roles are also available but not visible in the Google Cloud Platform Console. Use the Google Cloud CLI to assign these roles:

  • roles/datastore.backupsAdmin: Read and write access to backups
  • roles/datastore.backupsViewer: Read access to backups
  • roles/datastore.backupSchedulesAdmin: Read and write access to backup schedules
  • roles/datastore.backupSchedulesViewer: Read access to backup schedules
  • roles/datastore.restoreAdmin: Permissions to initiate restore operations

Create and manage backup schedules

The examples below demonstrate how to set up a backup schedule. For each database, you can configure up to one daily backup schedule and up to one weekly backup schedule. You cannot configure multiple weekly backups schedules for different days of the week.

You cannot configure the exact time of day of the backup. Backups are taken at different times each day. For weekly backup schedules, you can configure the day of the week to take a backup.

Create a backup schedule

To create a backup schedule for a database, use the gcloud alpha firestore backups schedules create command or the firebase firestore:databases:backups:schedules command.

Create a daily backup schedule

gcloud

To create a daily backup schedule, set the --recurrence flag to daily:

gcloud alpha firestore backups schedules create \
--database='DATABASE_ID' \
--recurrence=daily \
--retention=RETENTION_PERIOD

Replace the following:

• DATABASE_ID: The ID of the database to back up. Set to '(default)' for the default database.
• RETENTION_PERIOD: Set this to a value up to 14 weeks (14w).

Firebase CLI

To create a daily backup schedule, set the --recurrence flag to DAILY:

firebase firestore:backups:schedules:create \
--database 'DATABASE_ID' \
--recurrence 'DAILY' \
--retention RETENTION_PERIOD

Replace the following:

• DATABASE_ID: The ID of the database to back up. Set to '(default)' for the default database.
• RETENTION_PERIOD: Set this to a value up to 14 weeks (14w).

Create a weekly backup schedule

gcloud

To create a weekly backup schedule, set the --recurrence flag to weekly:

gcloud alpha firestore backups schedules create \
--database='DATABASE_ID' \
--recurrence=weekly \
--retention=RETENTION_PERIOD \
--day-of-week=DAY

Replace the following:

• DATABASE_ID: The ID of the database to back up. Set to '(default)' for the default database.
• RETENTION_PERIOD: Set this to a value up to 14 weeks (14w).
• DAY: The day of the week to take the backup. Set to one of the following:
  • SUN for Sunday
  • MON for Monday
  • TUE for Tuesday
  • WED for Wednesday
  • THU for Thursday
  • FRI for Friday
  • SAT for Saturday

Firebase CLI

To create a weekly backup schedule, set the --recurrence flag to WEEKLY:

firebase firestore:backups:schedules:create \
--database 'DATABASE_ID' \
--recurrence 'WEEKLY' \
--retention RETENTION_PERIOD
--day-of-week DAY

Replace the following:

• DATABASE_ID: The ID of the database to back up. Set to '(default)' for the default database.
• RETENTION_PERIOD: Set this to a value up to 14 weeks (14w).
• DAY: The day of the week to take the backup. Set to one of the following:
  • SUNDAY for Sunday
  • MONDAY for Monday
  • TUESDAY for Tuesday
  • WEDNESDAY for Wednesday
  • THURSDAY for Thursday
  • FRIDAY for Friday
  • SATURDAY for Saturday

List backup schedules

To list all backup schedules for a database, use one of the following methods:

gcloud

Use the gcloud alpha firestore backups schedules list command.

gcloud alpha firestore backups schedules list \
--database='DATABASE_ID'

Replace DATABASE_ID with the ID of the database. Use '(default)' for the default database.

Firebase CLI

Use the firebase firestore:backups:schedules:list command.

firebase firestore:backups:schedules:list \
--database 'DATABASE_ID'

Replace DATABASE_ID with the ID of the database. Use '(default)' for the default database.

Describe backup schedule

To retrieve information about a backup schedule, use one of the following methods:

gcloud

Use the gcloud alpha firestore backups schedules describe command:

gcloud alpha firestore backups schedules describe \
--database='DATABASE_ID' \
--backup-schedule=BACKUP_SCHEDULE_ID

Replace the following:

• DATABASE_ID: The ID of the database to back up. Set to '(default)' for the default database.
• BACKUP_SCHEDULE_ID: The ID of a backup schedule. You can view the ID of each backup schedule when you list all backup schedules.

Update a backup schedule

To update the retention period of a backup schedule, use one of the following methods:

gcloud

Use the gcloud alpha firestore backups schedules update command:

gcloud alpha firestore backups schedules update \
--database='DATABASE_ID' \
--backup-schedule=BACKUP_SCHEDULE_ID \
--retention=RETENTION_PERIOD

Replace the following:

• DATABASE_ID: The ID of the database to back up. Set to '(default)' for the default database.
• BACKUP_SCHEDULE_ID: The ID of a backup schedule. You can view the ID of each backup schedule when you list all backup schedules.
• RETENTION_PERIOD: Set this to a value up to 14 weeks (14w).

Firebase CLI

Use the firebase firestore:backups:schedules:update command:

firebase firestore:backups:schedules:update \
BACKUP_SCHEDULE \
--retention RETENTION_PERIOD

Replace the following:

• BACKUP_SCHEDULE: The full resource name of a backup schedule. You can view the name of each backup schedule when you list all backup schedules.
• RETENTION_PERIOD: Set this to a value up to 14 weeks (14w).

You can update the retention period of a backup schedule, but you cannot update its recurrence. If you need a backup schedule with a different recurrence, delete the old backup schedule if it is no longer required and create a new backup schedule with the desired recurrence.

Delete a backup schedule

To delete a backup schedule, use one of the following methods:

gcloud

Use the gcloud alpha firestore backups schedules delete command:

gcloud alpha firestore backups schedules delete \
--database='DATABASE_ID' \
--backup-schedule=BACKUP_SCHEDULE_ID

Replace the following:

• DATABASE_ID: The ID of the database to back up. Set to '(default)' for the default database.
• BACKUP_SCHEDULE_ID: The ID of a backup schedule. You can view the ID of each backup schedule when you list all backup schedules.

Firebase CLI

Use the firebase firestore:backups:schedules:delete command:

firebase firestore:backups:schedules:delete \
BACKUP_SCHEDULE

Replace the following:

• BACKUP_SCHEDULE: The full resource name of a backup schedule. You can view the name of each backup schedule when you list all backup schedules.

Note that deleting a backup schedule will not delete backups already created by this schedule. You can wait for them to expire after their retention period, or to manually delete a backup, see delete backup.

Manage backups

List backups

To list available backups, use one of the following methods:

gcloud

Use the gcloud alpha firestore backups list command:

gcloud alpha firestore backups list \
--format="table(name, database, state)"

The --format="table(name, database, state)" flag formats the output into a more readable format. To list only the backups from a specific location, use the --location flag:

gcloud alpha firestore backups list \
--location=LOCATION \
--format="table(name, database, state)"

Replace LOCATION with the name of a Cloud Firestore location.

Firebase CLI

Use the firebase firestore:backups:list command:

firebase firestore:backups:list

To list only the backups from a specific location, use the --location flag:

firebase firestore:backups:list \
--location=LOCATION

Replace LOCATION with the name of a Cloud Firestore location.

Describe a backup

To view details about a backup, use one of the following methods:

gcloud

Use the gcloud alpha firestore backups describe command:

gcloud alpha firestore backups describe \
--location=LOCATION \
--backup=BACKUP_ID

Replace the following:

• LOCATION: The location of the database.
• BACKUP_ID: The ID of a backup. You can view the ID of each backup when you list all backups.

Firebase CLI

Use the firebase firestore:backups:get command:

firebase firestore:backups:get BACKUP

Replace the following:

• BACKUP: The full resource name of a backup. You can view the name of each backup when you list all backups.

Delete backup

To delete a backup, use one of the following methods. Warning: You cannot recover a deleted backup.

gcloud

Use the gcloud alpha firestore backups delete command:

gcloud alpha firestore backups delete \
--location=LOCATION \
--backup=BACKUP_ID

Replace the following:

• LOCATION: The location of the database.
• BACKUP_ID: The ID of a backup. You can view the ID of each backup when you list all backups.

Firebase CLI

Use the firebase firestore:backups:delete command:

firebase firestore:backups:delete \
BACKUP

Replace the following:

• BACKUP: The full resource name of a backup. You can view the name of each backup when you list all backups.

Note: Cloud Firestore stores metadata related to backups and backup schedules related to a database. Cloud Firestore retains this metadata until all backups for the database expire or are deleted.

Restore data from a database backup

A restore operation writes the data from a backup to a new Cloud Firestore database.

To begin a restore operation, use one of the following methods:

gcloud

Use the gcloud alpha firestore databases restore command:

gcloud alpha firestore databases restore \
--source-backup=projects/PROJECT_ID/locations/LOCATION/backups/BACKUP_ID \
--destination-database='DATABASE_ID'

Replace the following:

• PROJECT_ID: Your project ID.
• LOCATION: The location of the database backup and the location of the new database created for the restored data.
• BACKUP_ID: The ID of a backup. You can view the ID of each backup when you list all backups.
• DATABASE_ID: A database ID for the new database. You cannot use a database ID that is already in use.

The output will include metadata, name, and response components:

metadata:
  '@type': type.googleapis.com/google.firestore.admin.v1.RestoreDatabaseMetadata
  backup: projects/PROJECT_ID/locations/LOCATION/backups/BACKUP_ID
  database: projects/PROJECT_ID/databases/DATABASE_ID
  operationState: PROCESSING
  progressPercentage:
    completedWork: '20'
    estimatedWork: '100'
  startTime: '2023-12-06T14:20:17.398325Z'
name: projects/PROJECT_ID/databases/DATABASE_ID/operations/operation_uuid
response:
  '@type': type.googleapis.com/google.firestore.admin.v1.Database
  createTime: '2023-12-06T14:20:17.398325Z'
  name: projects/PROJECT_ID/databases/DATABASE_ID
  ...

The metadata field includes a progressPercentage component, detailing the estimated progress of the restore thus far, and an operationState specifying the overall state of the restore. To retrieve this information again, use gcloud firestore operations list:

gcloud firestore operations list --database=DATABASE_ID

or, using the name field from the output described above, with gcloud firestore operations describe:

gcloud firestore operations describe OPERATION_NAME

Firebase CLI

Use the firebase firestore:databases:restore command:

firebase firestore:databases:restore \
--backup 'BACKUP' \
--database 'DATABASE_ID'

Replace the following:

• BACKUP: The full resource name of a backup. You can view the name of each backup when you list all backups.
• DATABASE_ID: A database ID for the new database. You cannot use a database ID that is already in use.