Back up and restore data

This page describes how to use the 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.

Firestore stores metadata related to backups and backup schedules related to a database. 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

Make sure that billing is enabled for your Google Cloud project. Learn how to check if billing is enabled on a project.

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 Firestore database

  • The following roles are also available but not visible in the Google Cloud 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.

Create a daily backup schedule

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).

Create a weekly backup schedule

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

List backup schedules

To list all backup schedules for a database, use the gcloud alpha firestore backups schedules list command. This command returns information about all backup schedules. 

gcloud alpha 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 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 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 each backup schedule when you list all backup schedules.
  • RETENTION_PERIOD: Set this to a value up to 14 weeks (14w).

Delete a backup schedule

To delete a backup schedule, 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.

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 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 Firestore location.

Describe a backup

To view details about a backup, use the gcloud alpha firestore backups describe command:

gcloud alpha firestore backups describe \
--location=LOCATION \
--backup=BACKUP_ID
  • LOCATION: The location of the database.
  • BACKUP_ID: The ID of a backup. You can view the ID each backup when you list all backups.

Delete backup

To delete a backup, use the gcloud alpha firestore backups delete command:

gcloud alpha firestore backups delete \
--location=LOCATION \
--backup=BACKUP_ID
  • LOCATION: The location of the database.
  • BACKUP_ID: The ID of a backup. You can view the ID each backup when you list all backups.

Restore data from a database backup

A restore operation writes the data from a backup to a new Firestore database. To begin a restore operation, 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'
  • 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 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 database mode will match that of the backup.

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